What belongs in an AGENTS.md file, and what does not

Stefan-Iulian Tesoi · 9 October 2026 · 6 min read

The commands that build, test and lint the repository, the conventions a newcomer would get wrong, and the places a coding agent must not touch. Leave out anything a linter or test already enforces and anything that changes from task to task: a rules file that grows into a design document stops being followed reliably.

An AGENTS.md file is read at the start of a session by OpenAI Codex, Cursor, GitHub Copilot's coding agent, Gemini CLI and, since version 2.1.277 in September 2026, Claude Code. It is the one piece of text every agent in the repository sees on every task, which is why what goes into it matters more than how much.

What is an AGENTS.md file for?

It is a README for agents: plain Markdown at the root of a repository, holding what a coding agent needs on every task and a human contributor would pick up during onboarding.

The AGENTS.md format has no required fields and no schema. It is now stewarded by the Agentic AI Foundation under the Linux Foundation, and more than 60,000 open-source projects carry one. A repository can hold several: each subdirectory may have its own file, and the tools that read them let the nearest one take precedence.

That simplicity is the point and the risk. Nothing stops the file growing, and nothing checks whether a line in it is still true.

How do AGENTS.md, CLAUDE.md and Cursor rules differ?

They are three names for the same job, read by different tools under different loading rules.

Claude Code reads AGENTS.md only as a fallback. A CLAUDE.md in the working directory or any directory above it takes precedence, so a repository with both loads only CLAUDE.md unless it imports the other with @AGENTS.md. The Claude Code memory documentation sets out the full order.

The practical rule: keep one source of truth, usually AGENTS.md, and make the tool-specific files thin pointers to it. Two copies of the same instructions drift, and the stale copy is always the one being read.

Five things every AGENTS.md file should say

Each of these is true for every task, and an agent cannot reliably infer any of them from the code:

1. The exact commands. Install, build, test, lint and typecheck, with their flags. Without them an agent runs npm install in a pnpm repository and rewrites the lockfile.
2. What counts as passing. Name the one command that is the gate and say that its exit code is the answer. pnpm run ci | tail reports the exit code of tail, and an agent will read that as green.
3. Conventions a newcomer gets wrong. Commit message format, where new modules go, which of two similar helpers is current. Only the ones a linter cannot see.
4. No-go zones. Generated files, applied migrations, vendored code, production configuration, anything holding credentials.
5. Where to look next. Pointers to the architecture notes or the contribution guide, not copies of them.

What should stay out of it?

Anything that is enforced elsewhere, anything that changes per task, and anything that cannot be checked.

• Rules a linter, formatter or type checker already enforces. The tool corrects the agent anyway, and the line costs context on every task.
• Task-specific instructions. "Use the new pricing table" is true for one change and wrong for the next.
• Architecture essays and history. Link to them. An agent loads the whole file on every task whether the history is relevant or not.
• Aspirations. "Write clean, maintainable code" gives an agent nothing to do differently.
• Secrets and internal URLs that should not be in the repository at all.

Anthropic's CLAUDE.md best practices put the reason plainly: longer files consume more context and reduce adherence. A coding agent instructions file that holds everything is followed less reliably on the lines that matter.

Rules file or work order: where does an instruction belong?

If it is true for every task in the repository, it belongs in the rules file. If it is true for this task only, it belongs in the work order.

The test catches most of the drift. Acceptance criteria, the files likely to change, the behaviour that must not break and how the result will be checked are all properties of one change, and they belong in a work order for a coding agent. They start life as a backlog item an agent can execute. A cursor rules file that accumulates last month's task instructions is a backlog nobody reads.

Laimonade keeps the two apart for that reason. An agent fetches its work order and criteria over MCP, and get_project_rules returns the repository's own CLAUDE.md, AGENTS.md and Cursor rules files alongside it, unchanged.

How do you know the file is being followed?

By checking behaviour, not the file. Claude Code's own documentation says instruction files are context, not enforced configuration, and that blocking an action regardless of what the model decides takes a hook.

Our own repositories learned this the expensive way. Their instructions file said to take a git worktree before the first edit and never to commit in the shared checkout. The rule was broken three times in one day. The third session had read it, then lost it to context compaction, which left behind a paraphrase of the previous version: check which branch you are on before committing. It saw main, concluded it was compliant, and committed four times into the shared checkout. Better wording would not have reached it. A PreToolUse hook comparing git rev-parse --git-dir with --git-common-dir did.

A rule broken twice does not need stronger wording. It needs a check that cannot be half-remembered.

Three habits keep the file honest:

• When review catches the same mistake twice, move the rule into a hook, a test or CI.
• Run /doctor prompt-audit in Claude Code to find instructions that contradict each other across CLAUDE.md, AGENTS.md and rules files.
• Delete lines that no longer describe the repository. A stale instruction is followed as faithfully as a current one.

The pillar on running coding agents in a team workflow covers the review stage these checks feed.

Frequently asked questions

Do Claude Code and Cursor read AGENTS.md?

Both do. Cursor reads AGENTS.md at the root and in subdirectories, combining nested files with their parents. Claude Code reads it from version 2.1.277, released in September 2026, but only when no CLAUDE.md exists in the working directory or above it. To use both files in Claude Code, put @AGENTS.md at the top of CLAUDE.md.

Should each package in a monorepo have its own file?

Yes, when packages differ in commands or conventions. The nearest file wins, so the root holds what is shared and each package holds its own build, test and no-go list. Keep the root short, because Codex concatenates every file from the root down to 32 KiB. In Claude Code, one CLAUDE.md at the root switches off every AGENTS.md beneath it.

Who should review changes to the file?

The people who review the build configuration, because it has the same reach. One line changes the behaviour of every agent session in the repository on every task. Changes should go through a pull request like code, and an agent should not edit the file in passing during unrelated work: a rule an agent writes for itself is unreviewed policy.