Skip to main content
A good AGENTS.md gives a coding agent the smallest set of repository-specific instructions it needs to work correctly. It should explain the commands, constraints, and verification steps the agent cannot safely infer from the code. It should not try to summarize the entire codebase or teach the agent general software engineering. Last reviewed July 18, 2026. Maintained by the Plannotator project. If your team uses Claude Code, the equivalent file is CLAUDE.md. The filename and loading rules differ, but the writing principle is the same: include only durable guidance that should influence almost every task in that scope. The best test for every line is simple:
Would removing this instruction cause the agent to make a specific, recurring mistake?
If the answer is no, remove it or move it to documentation that the agent can read when relevant.
Totman writes a single AGENTS.md file containing commands, boundaries, verification, and documentation pointers before one coding agent carries its guidance through the repository and reaches a passing check.

​
What is AGENTS.md?

AGENTS.md is a plain Markdown file containing instructions for AI coding agents. The open AGENTS.md format describes it as a README for agents: a predictable place for build steps, tests, conventions, and other project guidance. The file is normally committed to Git. That makes the instructions reviewable by the team and available to every supported agent that works in the repository. There are no required headings or fields. AGENTS.md does not contain the agent, model, or task. It changes the context the agent receives before working on a task. In practice, it sits between the agent’s built-in instructions and the repository it must understand.

​
What is the difference between AGENTS.md and CLAUDE.md?

AGENTS.md is an open format supported by a growing set of coding tools. CLAUDE.md is Claude Code’s native project-memory file. Anthropic’s Claude Code best practices recommend checking the project-level CLAUDE.md into Git so the team can maintain it together. OpenAI’s Codex documentation explains how Codex discovers and combines AGENTS.md files. If your team uses both formats, you can keep one canonical file and create a symbolic link:
Use separate files only when the tools need genuinely different guidance. Duplicating the same instructions in two independent files creates another place for them to drift.

​
How coding agents use repository instructions

Repository instructions are added to the agent’s working context. The model can use them while it explores the repository, makes a plan, edits files, runs commands, and decides whether the task is complete. For Codex, discovery happens once when a run starts. Codex reads global guidance from ~/.codex, then walks from the project root toward the current working directory. In each directory it checks AGENTS.override.md before AGENTS.md. Applicable files are combined from broad to specific, with the closer file taking precedence. The default combined project-instruction limit is 32 KiB. Claude Code reads CLAUDE.md at the start of each conversation. It can combine a user-level file, a project file, parent-directory files, and more specific child files. CLAUDE.md can also import another file with @path/to/file syntax. That hierarchy matters most in a monorepo. The root should contain rules shared by the whole repository. A package-level file should contain only the guidance that changes inside that package.

Instruction scope

Put each instruction as close as possible to the work it governs

Global

~/.codex/AGENTS.md

Personal defaults that apply across repositories.

Repository

/AGENTS.md

Shared tooling, boundaries, and completion checks.

Package

/apps/web/AGENTS.md

Only the rules that change for this package.

A nested file should narrow or override broader guidance, not repeat it.

​
What should you put in AGENTS.md?

Include facts that materially change how the agent should work and are difficult to infer reliably.

​
One sentence about the repository

State what the repository produces and any boundary that changes engineering decisions.
The second sentence earns its place because it prevents a plausible architectural mistake. A long directory tour does not.

​
Exact setup, build, and test commands

Name non-obvious tools and commands. Explain when to run them and what successful completion requires.
Commands are high-value instructions because the agent cannot always infer the team’s preferred package manager, test scope, or final verification gate.

​
Repository-specific constraints

Include boundaries that are easy to violate and expensive to repair.
Each rule names an action, a scope, and, where useful, the correct alternative.

​
A definition of done

Tell the agent how it can prove the work is complete.
Verification is more useful than a vague instruction to “write high-quality code.” A test, build, screenshot, or request transcript gives the agent a result it can inspect and improve.

​
Pointers to authoritative guidance

Link to detailed documentation when it applies only to some tasks.
This is progressive disclosure. The agent starts with a small map and loads the relevant detail when the task requires it. Matt Pocock’s AGENTS.md guide recommends the same pattern: keep the root file focused, then point to narrower documentation and skills that load only when the work needs them.

​
What should you leave out?

​
Information the agent can discover safely

Do not list every directory, dependency, or common language convention. Agents can inspect a repository tree, read package.json, follow imports, and observe local code patterns. The 2026 paper Evaluating AGENTS.md found that repository overviews did not help agents reach task-relevant files faster. Generated files were often redundant with documentation already present in the repository.

​
Rules a deterministic tool can enforce

Use a formatter for formatting, a linter for static rules, tests for behavior, and permissions or hooks for hard safety boundaries. A model instruction is advisory. Anthropic makes this distinction explicit: CLAUDE.md guidance influences behavior, while Claude Code hooks run deterministic scripts. If a command must run after every edit, or one directory must never be modified, an enforceable mechanism is safer than a sentence in a context file.

Choose the right surface

Instructions guide judgment. Tools enforce invariants.

Put in AGENTS.md

  • Use the repository’s focused test command.
  • Read the API contract before changing routes.
  • Ask before adding a production dependency.

Enforce elsewhere

  • Code formatting belongs in a formatter.
  • Forbidden imports belong in a linter.
  • Protected paths belong in permissions or hooks.

​
Task-specific workflows

Do not load a release procedure, database playbook, or security-review checklist into every coding session. Put reusable workflows in separate docs or agent skills, then tell the agent when to use them.

​
Frequently changing facts

Release versions, temporary status, current incidents, and detailed file maps become stale quickly. Stale guidance is worse than missing guidance because the agent treats it as an active instruction.

​
Generic aspirations

Instructions such as “write clean code,” “follow best practices,” or “be concise” rarely change the resulting work. Replace them with a repository-specific behavior or remove them.

​
Can a large AGENTS.md hurt agent performance?

Yes. A context file consumes input space and attention before the agent reads the task or repository. More instructions can also cause more exploration, tests, and reasoning steps. The Evaluating AGENTS.md study tested several coding agents on real repository tasks. In that evaluation:
  • developer-written context files improved task success by about 4 percent on average;
  • LLM-generated context files reduced success by about 3 percent on average;
  • context files increased exploration, testing, and inference cost, with generated files raising cost by more than 20 percent in the reported settings;
  • agents generally followed the instructions, which means unnecessary instructions still consumed work.
Those results do not prove that AGENTS.md is useless. The benchmark focused heavily on Python repositories and measured issue resolution rather than every aspect of software quality. It does show that comprehensiveness is not a safe goal. A longer file can make an agent more thorough while making the task slower, more expensive, or less likely to succeed. Philipp Schmid’s practical analysis reaches a similar conclusion from the study: describe the non-obvious tooling and purpose that change agent behavior, but avoid generated directory tours, generic style rules, and requirements that apply only to occasional tasks. Anthropic gives similar practical advice for CLAUDE.md: keep it short, include only broadly applicable information, and move occasional domain knowledge into skills or separate files. Its documentation warns that a bloated CLAUDE.md can make the model ignore the instructions that matter. This is one form of context rot. The file may still fit inside the context window, but useful guidance competes with duplicated, irrelevant, or stale material.

​
A practical AGENTS.md template

This template is intentionally small. Add a section only when your repository has a real need for it.
For a monorepo, keep shared instructions at the root and add a shorter AGENTS.md inside a package only when that package has different commands or constraints.

​
How to improve an existing AGENTS.md

Review the file against real agent behavior rather than adding every rule someone can imagine.
  1. Find instructions that apply only sometimes. Move them to task-specific documentation or a skill.
  2. Delete facts the repository already makes obvious. Directory listings and dependency summaries are common sources of duplication.
  3. Replace vague rules with observable behavior. Name the command, file, boundary, or verification result.
  4. Find conflicts. Check root, nested, override, user, and tool-specific instruction files.
  5. Test representative tasks. Ask the agent which instructions it loaded, then observe whether it chooses the right tools and checks.
  6. Review the file after failures. If the agent repeatedly makes the same repository-specific mistake, decide whether the fix belongs in instructions, docs, tests, linting, permissions, or product code.
Do not treat the file as an append-only list of past frustrations. Every new rule should justify the permanent context it consumes.

​
How do you verify that the file is being used?

With Codex, start a fresh run in the target directory and ask it to list or summarize its active instruction sources. OpenAI documents commands for checking the root and a nested directory in its AGENTS.md guide. If guidance looks stale, restart the run because Codex builds the instruction chain when the run begins. With Claude Code, use /memory to inspect loaded memory files. Test from the project root and from a package with its own CLAUDE.md. Check that the agent can state the applicable commands and constraints without inventing additional rules. Verification should also cover behavior. Give the agent a small representative task and check whether it:
  • chooses the expected package manager and commands;
  • reads the linked task-specific document when relevant;
  • respects the nearest scoped instruction file;
  • runs the stated checks before finishing;
  • avoids boundaries that should be enforced elsewhere.

​
Should an AI generate AGENTS.md for you?

An agent can help inspect a repository and propose a draft, but a human should decide what remains in permanent context. The benchmark evidence is a reason to be skeptical of generated completeness. In the 2026 evaluation, LLM-generated context files tended to lower task success and raise cost. Anthropic’s /init command can provide a starting point for CLAUDE.md, but its own best-practices guide tells teams to refine the result, keep it concise, and remove anything the model can infer. Use generation as an inventory step, not as approval. Ask the agent to identify non-standard commands, safety boundaries, and verification paths. Then delete aggressively, confirm every command, and review the file like production configuration.

​
Who should maintain AGENTS.md?

The team that owns the repository should maintain it through normal code review. Changes affect future agent work, so an instruction deserves the same scrutiny as a test configuration or build script. Review the file when:
  • a command or repository boundary changes;
  • a nested package gains different tooling;
  • several agent runs repeat the same avoidable mistake;
  • an instruction becomes enforceable through code or tooling;
  • the file grows without evidence that the new rules help.
Builder’s CLAUDE.md guide recommends using code review as one maintenance signal: when a reviewer catches a repeated, repository-specific mistake, decide whether the lesson belongs in CLAUDE.md. The useful part is the evidence from real work. The dangerous part is adding every correction forever without pruning older rules. A good AGENTS.md is not a complete description of the codebase. It is a short, maintained operating guide that helps an agent begin in the right place, use the right tools, and show evidence before it stops.
Last modified on July 19, 2026