An agent starts every new session with no memory of the project. It does not know how dependencies are installed, which command runs the tests, which directories must not be touched, or what counts as proof of completion. Until that is written down, you explain the same things in every prompt, and the agent rebuilds context from scratch each time - sometimes guessing wrong. And the price of such guessing is not a line in a log but real edits made on a wrong idea of how the project is built.
The naive move is clear: gather everything you know about the project into a single permanent file that is always loaded. Since context helps, let there be more of it - architecture, style, the history of decisions, long procedures. It seems that the fuller the always-on file, the less often the agent will err.
It breaks on the fact that always-on text is inserted into every request. A large file burns tokens on every turn, dilutes the model's attention and drowns in its own volume: the two important lines forbidding deploy get lost inside a page about project history. Worse, a long contract quickly diverges from the repository, and the agent trusts a stale line instead of the code.
Devin solves this with the AGENTS.md format at the repository root - a short portable contract loaded at the start of a session. It is the recommended format for always-on rules: plain Markdown, versioned together with the code and read not only by Devin. A practical structure is three sections: Commands (how to install, test, lint, build), Boundaries (what not to touch) and Completion (how to prove the work is done). Besides AGENTS.md Devin understands the singular AGENT.md and the legacy .windsurfrules, and which other formats to read - Cursor, Windsurf, Claude - is set by a separate read_config_from switch in the config.
Placement sets the scope. A file at the root loads immediately; an AGENTS.md in a subdirectory is discovered lazily when the agent reaches that part of the tree - so a module's narrow rules do not hang in the context of the whole job. Personal notes go into AGENTS.local.md and are added to gitignore so they do not reach the shared repository. A global contract for all projects lives in ~/.config/devin/AGENTS.md (on Windows, in %APPDATA%\devin\). The .devin path is preferred over the legacy .windsurf, and Devin also reads the familiar ~/.claude/CLAUDE.md. So the same contract works for the team through the root file, personally through the local version, and globally across all projects - without duplicating the same lines in every repository.
What to put here and what not is the main question. AGENTS.md holds only the universal and stable: commands, hard boundaries, completion criteria. A long procedure of dozens of steps is moved into a skill that loads on demand rather than hanging around always; Devin's documentation directly advises preferring skills to rules where possible, because a skill enters the context only when relevant. A good test for where a line belongs is simple: if it describes step by step how to do something, it is material for a skill; if it sets an unchanging frame - a command, a prohibition, a criterion - its place is in the contract.
The cost of a bloated contract is not abstract. Every extra line is tokens on every turn and attention pulled away from the task at hand. A contradiction between the file and the real code sends the agent down a false trail. And separately: AGENTS.md is committed, so secrets, keys and tokens have no place here - for those there are tracked config and environment variables, not the shared contract.
What a working minimum looks like is easier to show than to describe. Three short sections - commands, boundaries, completion rules - fit on one screen and cover most of the agent's recurring questions.
Such a contract must be verified with one caveat: a rule guides, it does not enforce. The phrase "do not run deploy" in Markdown is a useful hint but not a security boundary; only an agent that chose to honor it will honor it. A real boundary is created by a permission deny, a sandbox, or a hook with a blocking outcome. So the critical lines of the contract are backed by a hard mechanism, and the file's effect is checked in practice: does the agent follow the Commands and stop at the Boundaries. The Completion section is checked just as literally: the agent must show the relevant diff, name the exact verification commands and their outcome, and not declare completion with checks skipped.
The typical failures come down to three. AGENTS.md is turned into a documentation dump - and it bloats, goes stale and stops being read. Volatile or secret data is put into it - and you get either a leak or a lie in the context. It is relied on as protection - and people are surprised that Markdown stopped no one. The sign is the same: the file grows while trust in it shrinks. Keep the contract short, move the volatile into skills, and back the critical parts with a permission - then AGENTS.md stays what it should be: a short durable contract, not a long instruction no one follows.
# Project contract
## Commands
- Install: pnpm install --frozen-lockfile
- Test: pnpm test
- Lint: pnpm lint
- Build: pnpm build
## Boundaries
- Do not edit generated/** or migrations already shipped.
- Never read or modify .env* and key material.
- Preserve public API unless the task explicitly changes it.
## Completion
- Show the relevant diff.
- Report exact verification commands and failures.
- Do not claim completion with skipped checks.