Skip to content
AI Engineer Guide.

concept · coding · intermediate · concept 21 of 30

AGENTS.md

0 of 30 complete

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

Nearest file wins, stale line losesInteractive
11 nodes · 3 branches
filevalidation gateincludedrootnoteruled out or rejected

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

Step 1/8 · Cold start

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.

  1. Write the build, test, lint and type-check commands exactly as CI runs them, including the working directory.
  2. State the invariants an agent cannot infer: generated files not to edit, migration rules, branch naming.
  3. Keep only commands and constraints that change behaviour, and link to deeper documentation.
  4. Add a package-level file where a subproject has different tooling or conventions.
  5. Review the file when CI changes, and treat a broken documented command as a bug.
  6. Test it by running every documented command in a fresh checkout.

Trade-offs

ChoiceGood forCostFails when
Single root fileOne place to lookToo coarse for monoreposPackages use different toolchains
Nested per-package filesLocal accuracyDuplication and driftConventions differ subtly between packages
Long comprehensive fileCovers edge casesConsumes context, gets ignoredAgent window is tight
Minimal file with linksCheap to readAgent may not follow linksTask needs exact commands
Trade-off mapInteractive

Good for

One place to look

Cost

Too coarse for monorepos

Fails when

Packages use different toolchains

  1. Packages use different toolchains
  2. Conventions differ subtly between packages
  3. Agent window is tight
  4. 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