AGENTS.md for Spec-First Teams: What Belongs In It
Adding an AGENTS.md takes about ten minutes. Keeping it true takes discipline, because unlike code, an instruction file has no test that fails when it starts lying. Ours described a React and Tailwind stack for five months. The repository has never contained a line of React.
What AGENTS.md is
The format describes itself as a README for agents: a predictable place to put the context a coding agent needs before it changes your project. It lives at the repository root, has no required fields, and is read by more than twenty tools, including Codex, Jules, Cursor, VS Code, Zed, Aider, and GitHub Copilot's coding agent. That breadth is the entire argument for using it. A rule written once is a rule every agent on the team inherits, whichever one a given developer happens to run.
It complements the README rather than replacing it. A README is written for a person deciding whether to use a project; AGENTS.md is written for an agent about to modify it. The distinction matters most for detail that would clutter a README and bore a human contributor: the exact test command, the directory that must never be hand-edited because a generator owns it, the reason a dependency is pinned.
None of that is the hard part. The hard part is the boundary between rules that belong in a repository-wide file and decisions that belong in a spec, and the fact that nothing in your toolchain enforces it.
Ours was wrong for five months
This site is 219 hand-written HTML pages, vanilla ES modules, and a set of Node generators. No framework, no bundler, no JSX. On 2026-04-07 we committed an AGENTS.md whose Tech Stack section read: React, TypeScript, Tailwind CSS, shadcn/ui, Lucide icons, Framer Motion. We corrected it on 2026-09-08, five months later, while writing this article.
The file was not careless. It was written from a template, at a moment when the stack was still a plan rather than a fact, and it aged into a lie without any single person deciding to lie. That is the failure mode worth internalising: instruction files drift silently because nothing executes them. A wrong function signature breaks a test. A wrong stack declaration produces an agent that confidently proposes a React component for a static HTML page, and a developer who quietly ignores the file from then on.
The saving grace was a hedge that happened to be in the same section — "if an existing project structure already exists, follow the existing stack" — which is why the damage stayed at wasted suggestions rather than wrong code. That hedge is worth copying, but it is a seatbelt, not a reason to drive badly.
The durability test
Most bad AGENTS.md files fail one question: would this line need different wording for the next feature? If yes, it is a spec line that leaked into the wrong file.
| Belongs in AGENTS.md | Belongs in the spec for one change |
|---|---|
| The test command, and what counts as green | Which tests prove this criterion |
| Directories a generator owns and humans must not edit | The write scope for this task |
| The commit and PR conventions | The rollback plan for this release |
| Which areas require extra care: payments, auth, migrations | Why this change touches auth and what that implies |
| The stack, and the instruction not to introduce another | The decision to add one dependency, with its justification |
The practical consequence is that AGENTS.md should be shorter than teams expect. Repository-wide truths are a small set. Everything that varies per change belongs in the artifact that is written per change — a spec packet, or a repo-level spec.md when several agents need the same source of truth for one piece of work.
A starting AGENTS.md
The format has no required fields, so structure is a matter of convention. These sections cover what agents actually get wrong, in the order they need them.
# AGENTS.md ## What this repository is One paragraph. The shape of the codebase, and the one thing newcomers get wrong about it. ## Stack What is actually here, stated plainly. Name what is NOT here if a template or a sibling repo would suggest otherwise. ## Commands build: npm run build test: npm run check serve: npm run dev Say which one must pass before a change is proposed. ## Boundaries - Generated files: list the paths. Edit the generator, not the output. - Never touch without an approved spec: migrations, auth, billing. - Do not add a dependency to solve a twenty-line problem. ## Conventions Commit message format. PR expectations. Where tests live and how they are named. ## Before you finish The evidence a change must carry: which command was run, what it printed, what was skipped and why.
Two notes on the sections above. The Stack section should say what is absent, not only what is present — "no React, no bundler; pages are hand-written HTML" prevents a whole class of suggestion that "vanilla ES modules" alone does not. And Boundaries earns its place by naming generated output. Every repository with a generator eventually gets a pull request that edits the generated file, and the fix is one line in an instruction file.
Nested files: nearest wins
Subdirectory AGENTS.md files are part of the format. Agents read the nearest file in the directory tree, so the closest one takes precedence and each subproject can ship instructions that contradict the root without ambiguity. OpenAI's own repository reportedly carries 88 of them.
For a monorepo this is the difference between a usable file and an unusable one. A root file that tries to describe five packages with different stacks becomes a document of exceptions, and an agent working in packages/api has to read four irrelevant sections to find the one that applies. One file per package, each short, each true in its own directory. Keep the root file for what genuinely spans everything: the commit convention, the release process, the areas that require a spec before anyone touches them.
AGENTS.md, CLAUDE.md, and skills
Teams running more than one agent tool end up with more than one instruction file, and the temptation is to duplicate. Resist it — two files stating the same rule will disagree within a quarter, and nobody will know which one the agent read.
| File | Read by | What it should hold |
|---|---|---|
AGENTS.md | Twenty-plus tools, nearest file wins | Everything portable: stack, commands, boundaries, conventions |
Tool-specific file (for example CLAUDE.md) | One tool, loaded every session | Only what that tool alone needs. Point at AGENTS.md for the rest |
| A skill | One tool, loaded on demand | Procedures: the spec template, the review checklist, anything you would otherwise paste |
| The spec | Humans and agents, per change | Goal, non-goals, acceptance criteria, evidence |
The distinction between the second and third rows is cost. A session-level file is paid for on every turn, so it should hold facts, not procedures. A skill is loaded when the work matches, so it can afford to be long. A spec is written once per change and reviewed like code.
Four ways it goes stale
| Symptom | Root cause | Fix |
|---|---|---|
| Agents suggest patterns the codebase does not use | The file describes an intended stack, not the real one | Write it from the repository as it is today, not from the plan |
| Developers stop reading it | It grew into a style essay | Cut anything a linter, formatter, or test already enforces |
| It contradicts itself across sections | Per-change decisions were appended over time | Apply the durability test; move the variable lines into specs |
| Nobody notices it is wrong | No moment in the workflow rereads it | Review it in any PR that changes the stack, the commands, or a boundary |
Keeping it true
The only durable fix for silent drift is to make the file's claims checkable and to give someone a reason to check them. Three habits do most of the work. Write claims that can be falsified in one command — "npm run check must pass" can be verified; "we value quality" cannot. Treat a change to the stack, the commands, or a boundary as a change that must update AGENTS.md in the same pull request, the same way an API change updates its contract. And read the file end to end once a quarter with the repository open beside it, which is exactly the exercise that caught ours.
If your team already writes specs, none of this is new process. It is the same discipline applied one level up: a spec fixes intent for one change, and AGENTS.md fixes context for all of them. The failure mode is also the same. A spec nobody checks against the diff, and an instruction file nobody checks against the repository, both degrade into documents that exist mainly to be cited.
References
- AGENTS.md — the open format: root placement, nearest-file-wins precedence, the supporting tool list, and its relationship to README.md.
- Claude Code documentation: Skills — the on-demand loading model referenced in the comparison table.
Facts about the format verified against the linked sources on 2026-09-08. The five-month drift described above is from this site's own repository history, commits 8be159c (2026-04-07) and e7969a4 (2026-09-08).