Why it matters
Every agent session starts cold. The build command, the test subset, the generated files that must not be edited and the branch conventions all live in people's heads or in CI configuration the agent may not read. A repository instruction file makes those facts discoverable and versioned with the code, so a convention change ships in the same commit as the change that required it.
Mental model
It is a README for a new contractor, except this contractor follows it literally. The metaphor breaks because a human infers what an outdated line meant and asks a colleague, while the agent executes the line as written and reports the resulting failure as a task failure.
How it works
Step 1 of 8
Cold start
The session knows nothing about how the repository builds or which test subset matters. The next read may be a package.json, or it may be nothing at all.
root · current
Project instructions · one session
Nothing about the build, the tests or the conventions is in context at the start. The agent will infer them from whatever it happens to read unless a file states them.
Root of the hierarchy
Figure. Two instruction files with one overlapping slot: the root names jest and apps/web names vitest, so the nearer file wins. One rejected line is drawn crossed, because a documented command that CI no longer defines is a bug rather than a preference.
What to notice. The repository, the commands and the runner names are an authored example; the page gives no measurements, so none are drawn. The hierarchy is the point: depth buys locality and costs duplication, and precedence is what stops a conflict becoming a coin flip. Omitted: who signs off a change to an instruction file, which the page leaves to code review.
Text version
An instruction hierarchy for one session. The root is the project instructions at a cold start, with no project memory. Under it are two files: AGENTS.md at the repository root, and apps/web/AGENTS.md, which wins when the two disagree. The root file carries a test command that runs jest with its working directory, the invariant that generated files are not edited, a link to docs/testing.md instead of inlining it, and a rejected stale line naming a test script the repository removed. The package file carries its own test command using vitest and a local rule against editing barrels. A note records that the loaded files and their order are printed per session, and a verification gate runs every documented command in a fresh checkout.
- Write the build, test, lint and type-check commands exactly as CI runs them, including the working directory.
- State the invariants an agent cannot infer: generated files not to edit, migration rules, branch naming.
- Keep only commands and constraints that change behaviour, and link to deeper documentation.
- Add a package-level file where a subproject has different tooling or conventions.
- Review the file when CI changes, and treat a broken documented command as a bug.
- Test it by running every documented command in a fresh checkout.
Trade-offs
| Choice | Good for | Cost | Fails when |
|---|---|---|---|
| Single root file | One place to look | Too coarse for monorepos | Packages use different toolchains |
| Nested per-package files | Local accuracy | Duplication and drift | Conventions differ subtly between packages |
| Long comprehensive file | Covers edge cases | Consumes context, gets ignored | Agent window is tight |
| Minimal file with links | Cheap to read | Agent may not follow links | Task needs exact commands |
Good for
One place to look
Cost
Too coarse for monorepos
Fails when
Packages use different toolchains
- Packages use different toolchains
- Conventions differ subtly between packages
- Agent window is tight
- Task needs exact commands
Figure. Each choice with what it buys, what it costs, and the case where it loses.
What to notice. The fourth column is the decision: if the losing case describes your situation, the choice is wrong.
Text version
Four trade-offs: Single root file is good for One place to look, costs Too coarse for monorepos, and fails when Packages use different toolchains. Nested per-package files is good for Local accuracy, costs Duplication and drift, and fails when Conventions differ subtly between packages. Long comprehensive file is good for Covers edge cases, costs Consumes context, gets ignored, and fails when Agent window is tight. Minimal file with links is good for Cheap to read, costs Agent may not follow links, and fails when Task needs exact commands
Failure modes
- Stale command. The file names a test runner the repository replaced and every run fails the same way. Debug: execute each documented command in a clean container.
- Instruction conflict. Root and package files disagree and the agent picks the wrong one. Debug: print which files were loaded and their precedence order.
- Context crowding. A long file pushes the task and the diff out of the window. Debug: measure tokens per loaded instruction file.
In production
Version the file with the code and run its commands in CI. Alert when a documented command diverges from the CI definition.
Common misconceptions
People think: A longer instruction file produces better compliance.
Actually: Past a point it dilutes attention and hides the line that mattered.
People think: AGENTS.md is specific to one vendor's tool.
Actually: It is a convention several agents read, and portability is the reason to keep it tool-neutral.
Interview angle
Treat the file as executable documentation: exact commands, verified in CI, with a precedence rule for nested files. A strong answer mentions the context cost of a long file. Listing style preferences, with no way to check that the commands still work, is the weak version.
Sources
- AGENTS.md — the convention and its expected contents.
- Anthropic, Claude Code best practices — project instructions and command conventions.
- HumanLayer, 12-Factor Agents — owning your control flow and context explicitly.