Guides

What Is AGENTS.md? Where It Goes and What to Put in It

Karan KalraGrowth, Trail

AGENTS.md is a plain Markdown file at the root of a repository that tells AI coding agents how to build, test, and change the project. To use it, create the file, add your exact commands plus the conventions an agent cannot discover from the code, and commit it. Supporting agents read it automatically at the start of each session.

Key takeaways

  • AGENTS.md is an open format with no required fields, governed by the Linux Foundation's Agentic AI Foundation since December 2025.
  • Claude Code has read AGENTS.md since version 2.1.277 (September 18, 2026), but only when no CLAUDE.md exists in the working directory or above it.
  • In our check of 40 well-known repositories on October 1, 2026, 31 had a root AGENTS.md, and the median real file was 8,528 bytes.
  • OpenAI Codex cuts AGENTS.md off at 32 KiB by default without warning. Two of the 27 real files we measured are larger than that.
  • Studies disagree on whether AGENTS.md helps: ETH Zurich found no general gain in task success and over 20% higher cost, while a 124-pull-request study found 28.64% lower median runtime.
  • The studies agree on content: specific commands and non-obvious rules help, and codebase overviews the agent could find itself only add cost.
  • Phrasing matters too. In Augment Code's evals, a numbered workflow cut pull requests with missing files from 40% to 10%, while a file of 30 bare "don't" rules doubled the time of a simple task.

What is AGENTS.md?

AGENTS.md is an open, plain-Markdown file that gives AI coding agents project-specific instructions: setup commands, test commands, conventions, and boundaries. AGENTS.md sits at the repository root, has no required fields or schema, and is read automatically at session start by agents including OpenAI Codex, Cursor, GitHub Copilot, and Claude Code.

The official AGENTS.md site describes the file as a README for agents. A README explains a project to people. AGENTS.md holds the operational detail an agent needs and a human reader would skip.

Few facts about AGENTS.md worth mentioning:

  • Origin: AGENTS.md was formalised as an open specification in August 2025, led by OpenAI with Google, Cursor, and Factory, according to a 2026 study of AGENTS.md as a governance artefact.
  • Governance: The AGENTS.md specification was donated to the Linux Foundation's Agentic AI Foundation in December 2025, per the same study.
  • Adoption: AGENTS.md was reported in more than 60,000 open-source repositories by mid-2026, according to Agentailor's review of agent standards.
  • Format: AGENTS.md has no required headings, no YAML frontmatter, and no custom syntax.

Which AI coding tools read AGENTS.md in 2026?

OpenAI Codex, Cursor, GitHub Copilot's coding agent, Google Jules, Gemini CLI, Aider, Zed, Windsurf, Devin, and Amp are all listed as AGENTS.md readers on the official AGENTS.md site. Claude Code joined on September 18, 2026 with version 2.1.277, but reads AGENTS.md only as a fallback when a project has no CLAUDE.md.

ToolReads AGENTS.mdWhat to know
OpenAI CodexYes, nativelyLoads ~/.codex/AGENTS.md, then every AGENTS.md from the project root down to the current directory. AGENTS.override.md replaces AGENTS.md in the same folder. (Codex docs)
Claude CodeYes, as a fallback since 2.1.277Skips AGENTS.md if any CLAUDE.md or CLAUDE.local.md exists at or above the working directory. Not yet available on Bedrock, Vertex, or Foundry. (DevOps.com)
CursorYesApplies AGENTS.md alongside .cursor/rules/; explicit Cursor rules take priority. (Codersera)
GitHub CopilotYes, in the coding agentCopilot pull request review still reads .github/copilot-instructions.md. (SSW Rules)
Gemini CLIListed as a readerSome guides report Gemini CLI looking for GEMINI.md by default, so confirm in your own configuration.

Claude Code's rule has three cases:

Your repository hasClaude Code reads
AGENTS.md and no CLAUDE.mdAGENTS.md
AGENTS.md and a CLAUDE.mdCLAUDE.md only
A CLAUDE.md containing the line @AGENTS.mdCLAUDE.md, with AGENTS.md pulled in through the import

Claude Code also has a setting, claude-md-and-agents-md, that reads both files. The Hacker News thread on the release notes that the feature does not cover .agents/skills.

How do you create an AGENTS.md file?

To create an AGENTS.md file, add a Markdown file named exactly AGENTS.md to your repository root, write the commands and rules an agent needs under plain headings, and commit it. AGENTS.md needs no schema, generator, or build step. A useful first version fits in 30 lines.

  1. Create the file. Add AGENTS.md at the repository root, with that exact uppercase name. Agents look for the file by name.
  2. Write the exact commands. List install, build, lint, and test commands with their flags, including how to run a single test. Agents run what the file names.
  3. Add the rules an agent cannot infer. Record the conventions that are not visible in the code, such as which package manager to use or which test style the team prefers.
  4. Set boundaries. State what the agent must never touch or do: secrets, generated files, CI configuration, release builds.
  5. Connect other tools. If you keep a CLAUDE.md, make its only line @AGENTS.md so Claude Code loads the same instructions as every other agent.
  6. Test it. Start a fresh agent session, ask which instruction files it loaded, and run one small task to confirm the commands work.
  7. Commit and review it like code. Changes to AGENTS.md change agent behaviour for the whole team, so they belong in pull requests.

A minimal starting point:

# AGENTS.md

## Commands
- Install: `pnpm install`
- Test everything: `pnpm test`
- Test one file: `pnpm vitest run path/to/file.test.ts`
- Lint: `pnpm lint --fix`

## Rules
- Use pnpm, never npm or yarn.
- New tests go next to the file they test.
- Run lint and the affected tests before you report a task as done.

## Never
- Never commit secrets or edit `.env` files.
- Never change files under `generated/`.

Last verified: 2026-10-01

Three real AGENTS.md files show how far the format stretches. Sizes are as measured on October 1, 2026.

RepositorySizeWhat the file does
microsoft/vscode271 bytes, 6 linesA pointer. It sends agents to the project's existing Copilot instructions file and says nothing else.
astral-sh/uv2,432 bytes, 34 linesA flat list of ALWAYS, PREFER, and NEVER rules with no overview: test style, banned Rust patterns, lockfile handling.
apache/airflow22,493 bytes, 251 linesA full manual with sections for naming, environment setup, commands, architecture boundaries, security model, testing, and commits. It opens with a house rule: write "Dag" in prose.

The uv file is the best model for a first AGENTS.md. Every line is a rule the code alone would not reveal.

What should you put in AGENTS.md, and what should you leave out?

Put in AGENTS.md only what an agent cannot discover by reading the repository: exact commands, non-obvious tooling choices, house conventions, and hard boundaries. Leave out codebase overviews, directory tours, and anything already in the README or config files. Agents find that material themselves, and repeating it in AGENTS.md raises cost without raising success. Every line is input tokens on every session, which is why a loaded instruction file is one of the token drains behind a greeting that eats a chunk of your limit. The same rule governs a company brain: store only what the agent cannot infer.

Put in AGENTS.mdLeave out of AGENTS.md
Exact commands with flagsProject descriptions copied from the README
Tooling choices the code does not reveal, such as uv over pipDirectory listings and architecture tours
House conventions an agent gets wrong by defaultStyle rules a linter or formatter already enforces
Boundaries: files and actions that are off limitsMentions of deprecated tools, which agents may start using
Pointers to deeper docs, by pathFull documentation pasted inline
Security rules for your codebaseAnything true of every project in your language

The evidence for this split comes from ETH Zurich. Gloaguen et al. (2026) found that agents follow the instructions in context files closely, while repository overviews did not help. A tool named in an AGENTS.md file gets used, whether or not it suits the task.

The lines in a real AGENTS.md fall into three kinds, and they do not work equally well. One Hacker News commenter sorted them this way:

  1. Facts. Commands, where the docs live, which package manager to use. These work almost every time, because the agent would otherwise have to go looking.
  2. Regression rules. One sentence written after you watched the agent fail, such as "Validate JWTs at the route level, not in components." These work too.
  3. Rules written before any failure. "Write clean, maintainable code." "Think carefully before acting." These are mostly ignored. The agent already believes it does them.

Addy Osmani gives the most useful test in "Stop Using /init for AGENTS.md": before adding a line, ask whether the agent could find it by reading the code. He treats AGENTS.md as a running list of friction in the codebase that has not been fixed yet.

Francis Dortort adds a second test: does the code allow several valid ways to do this, with nothing to show which one you prefer? If the agent could find the answer in the code, and the code already shows one clear way, delete the line.

That test rules out auto-generated files. Commands such as /init scan the repository and write down what they found, which is the content an agent could already discover. Write AGENTS.md by hand, one line per mistake you have watched an agent make.

How should you phrase the rules in AGENTS.md?

Phrase each rule as a specific action with the exact command or alternative, and put multi-step work in a numbered list. The largest public test of phrasing is Augment Code's eval of its own monorepo files. The best files improved output about as much as switching from Haiku to Opus. The worst did worse than no file at all.

Augment ran dozens of its AGENTS.md files against golden pull requests, once with each file and once without. Like the Vercel result below, it is vendor data from one codebase. Four patterns held up across their runs:

PatternWhat it looks likeAugment's result
Numbered workflows"To add an integration: 1. ... 2. ... 6. Register it in wiring.ts"Pull requests missing wiring files fell from 40% to 10%; correctness rose 25%
Decision tables"Server state: React Query. UI state: Zustand."Best-practice scores rose 25%
Short real snippets3 to 10 lines copied from production code, not invented examplesCode reuse rose 20%
A "do" for every "don't""Never call fetch directly; use apiClient"A file of 30-plus bare "don't" rules doubled the time for a CRUD task, and the result was 20% less complete

Developers who publish their files add three more patterns:

  • Give a pointer a trigger. Shrivu Shankar found that @-importing a doc loads it into every session, and a bare path gets ignored. A condition works: "If you hit a FooBarError, read docs/errors.md."
  • Wrap a hard command in a script. If a command takes three paragraphs to explain, write a short wrapper and document the wrapper instead. Armin Ronacher adds that anything the agent runs must be fast and must never hang. A crash is fine, because the agent can read the error.
  • Show one example per tool. Simon Willison found that one usage example of the shot-scraper CLI was enough for an agent to adapt it to new URLs.

Does "don't" plant the idea? Some developers argue that "don't do X" puts X in the context, and the agent goes looking for it. Others find that naming the exact thing to avoid helps the agent catch itself. Augment's data supports a middle path. Keep the "don't", and follow it with the "do".

Does ALL CAPS help? Developers split on it. Jesse Vincent's widely copied global file runs on MUST and NEVER, and the uv file above is built the same way. Peter Steinberger dropped capitals entirely after finding that shouting made GPT-5 less effective. If capitals help at all, it is on the one or two rules that keep slipping, not across the whole file.

Does AGENTS.md actually improve AI coding agent results?

AGENTS.md improves AI coding agent results when it contains specific instructions the agent could not discover, and adds cost when it contains overviews. ETH Zurich found no general gain in task success and over 20% higher inference cost from context files. A separate study of 124 pull requests found 28.64% lower median runtime with AGENTS.md present.

Five studies, read together:

StudyWhat was testedResult
Gloaguen et al., ETH Zurich (2026)SWE-bench tasks with generated context files, plus real issues from repositories with developer-written filesNo general improvement in task success; inference cost up more than 20% on average
Lulla et al. (2026)10 repositories and 124 pull requests, run with and without AGENTS.mdMedian runtime 28.64% lower and output tokens 16.58% lower, with comparable task completion
Vercel (2026)Next.js 16 API evals comparing an 8 KB docs index in AGENTS.md against agent skillsAGENTS.md index passed 100%; skills reached 79% with explicit instructions and 53% by default
McMillan (2026)1,650 Claude Code sessions varying file size, rule position, file layout, and conflicting rulesNone of the four layout variables changed compliance; compliance fell as the session went on
Chatlatanagulchai et al. (2025)Content of 2,303 context files from 1,925 repositoriesTest procedures appear in 75.9% of files; security in under 15%

These results fit together once the file contents are compared. The ETH Zurich study tested auto-generated and developer-committed files and measured task success; an independent summary of the paper reports that the generated files largely restated existing documentation. The Lulla study used files that developers maintained and measured speed. Vercel put version-specific documentation in the file, which is information the model did not have. When a procedure belongs in a skill instead of an always-loaded file, our Claude Code skills guide covers the split.

Our reading: AGENTS.md is worth having, and its value depends almost entirely on what the file contains. Missing knowledge helps. Restated knowledge costs.

Three limits to keep in mind. The Vercel result is a vendor's own eval on its own framework. The Lulla study did not measure correctness. The McMillan study measured one simple rule in Claude Code only.

How long should an AGENTS.md file be?

An AGENTS.md file should stay under 32 KiB (32,768 bytes), because OpenAI Codex cuts off anything past that by default without warning. Below that hard limit, no study has found a best length. In our check of 40 well-known repositories, the median AGENTS.md was 8,528 bytes, roughly 100 to 160 lines.

We requested the root AGENTS.md of 40 well-known open-source repositories on October 1, 2026:

MeasureResult
Repositories with a root AGENTS.md31 of 40
Real files (not symlinks to another file)27
Median size of real files8,528 bytes
Smallest real file271 bytes (microsoft/vscode)
Largest real file43,870 bytes (PostHog/posthog)
Real files over Codex's 32 KiB default2 of 27

The two files over the limit are PostHog/posthog and openai/openai-agents-python at 38,241 bytes. Unless those projects raise Codex's project_doc_max_bytes setting, Codex reads only the first 32 KiB of each.

The truncation is easy to miss. Apache Airflow contributors found it while building an eval: their AGENTS.md was 35,417 bytes at the time, so a Codex run could report success while missing the end of the file (Airflow pull request 70120). Airflow's file measured 22,493 bytes in our check.

Common advice says to keep AGENTS.md under 150 lines so agents follow it. The one controlled test does not support a line limit. McMillan (2026) measured compliance of 60.0%, 65.2%, 67.7%, and 64.0% for files of 25, 100, 250, and 500 lines, with no detectable difference.

Short files still win on maintenance. OpenAI's team reported that one large AGENTS.md went stale quickly and moved to a file of about 100 lines that points to deeper docs (summary of OpenAI's harness engineering report). Check your own file with wc -c AGENTS.md.

Why do AI agents ignore AGENTS.md?

AI agents ignore AGENTS.md for two kinds of reasons. Either the file never loaded, because of a size limit, a competing CLAUDE.md, or a wrong filename, or the file loaded and the agent drifted from it during a long session. None of these failures produces an error message, so each has to be checked by hand.

SymptomLikely causeFix
Codex follows early rules and misses later onesAGENTS.md is over 32 KiB and was cut offTrim the file, or raise project_doc_max_bytes in Codex config
Claude Code ignores AGENTS.md entirelyA CLAUDE.md or CLAUDE.local.md exists at or above the working directoryMake CLAUDE.md a single line, @AGENTS.md, or switch the setting to read both files
Claude Code ignores local overridesClaude Code does not read AGENTS.override.md, AGENTS.local.md, or .agents/Keep Claude-specific overrides in a CLAUDE.md that also imports AGENTS.md
Claude Code 2.1.277 to 2.1.280 ignores AGENTS.md with telemetry offThe loader sat behind a remote feature flag that never arrived when DISABLE_TELEMETRY=1 was setUpgrade to 2.1.281 or later
No agent picks the file upWrong name or locationName it exactly AGENTS.md and place it at the repository root
Codex skips a subfolder's rulesThe nested AGENTS.md is not on the path between the root and the working directoryStart the agent from inside that subfolder
Rules hold early in a session, then slipCompliance decays as the agent writes more codeEnforce the rule with a linter, hook, or CI check

Drift within a session is the least known cause and the best measured. In McMillan's 1,650-session study, a one-line rule in the instruction file was followed for 60% to 68% of functions. Each additional function the agent wrote lowered the odds of compliance by about 5.6%, and the first miss typically came at the fourth function.

The type of task mattered more than the file. In the same study, compliance was 45.1% on a refactoring task and 71.3% on a new-build task of similar size.

AGENTS.md is guidance and carries no enforcement. Any rule that must hold every time belongs in tooling that fails the build. The same split between prompt rules and code-enforced limits applies to business rules for agents.

How do you check that an agent is reading AGENTS.md?

Check that an agent is reading AGENTS.md by putting a word in the file that the agent could not know otherwise, then asking for it back. An ignored file gives no error. The agent just stops following your rules, and the only way to notice is to test for it.

  1. The load test. Make an empty folder with an AGENTS.md that contains the single word PERIWINKLE. Start a session and ask the agent to repeat the word without reading any files. If it cannot, the file did not load. Run it twice, because some tools fetch configuration on the first session. This test caught a real bug: Claude Code 2.1.277 silently skipped AGENTS.md when telemetry was off, and the fix shipped in 2.1.281 (Kunal Ganglani).
  2. The canary. Add a harmless instruction you will notice, such as "Address me as Captain." When the agent stops doing it, usually deep into a long session or after context compaction, assume the rest of the file has faded too. Start a fresh session. Matt Nunogawa puts the canary at the top of the file, next to instructions for what to do after compaction.
  3. Ask. Kaushik Gopal periodically asks the agent which instruction files it has loaded for the project. It is the quickest way to find a stray ~/CLAUDE.md or an old .cursorrules.
  4. Repeat the task. Armin Ronacher runs the same task three times and asks whether all three results are acceptable. One good run can be luck. Three tell you whether the instructions are doing the work.

Is AGENTS.md a security risk?

AGENTS.md is a security risk because agents load it as trusted instructions, so anyone who can add or change the file can redirect the agent. Researchers have shown two working attack paths: a malicious dependency that writes an AGENTS.md into the workspace, and a pull request branch that carries one into a CI run.

  • Dependency path. The NVIDIA AI Red Team showed a compromised dependency creating an AGENTS.md that hijacked OpenAI Codex and led toward a malicious pull request (NVIDIA, 2026).
  • Pull request path. The GitInject paper showed an attacker adding AGENTS.md, CLAUDE.md, or GEMINI.md to a pull request branch. The CI runner checks the file out, and the review agent loads it as operator-level instruction before reading the pull request (GitInject, 2026).

Most teams have not written security into the file either. Security guidance appears in under 15% of 2,303 agent context files studied by Chatlatanagulchai et al. (2025).

A short checklist for AGENTS.md security:

  • Require code-owner review for any change to AGENTS.md, CLAUDE.md, and similar files.
  • Fail CI when an untracked AGENTS.md appears in the workspace.
  • Run review agents against instruction files from the base branch, never the pull request branch.
  • Give agents the narrowest credentials the task needs.
  • Add your own security rules to AGENTS.md: where secrets live, what must never be logged, which workflows are off limits.

Can AGENTS.md set rules for other people's agents?

AGENTS.md can set rules for contributors' agents, because any agent pointed at a clone of the repository reads the file. Two projects use it that way, and neither wrote the file for agents of their own.

  • SQLite added an AGENTS.md that tells any agent reading its code that the project does not accept agentic code. Agent-found bug reports are welcome with a reproducible test case. A later commit removed the word "currently" from the statement.
  • Ghostty keeps a human-facing AI_POLICY.md that requires contributors to disclose any AI use. Its AGENTS.md carries two rules for the tools themselves: never create an issue, and never create a pull request. If the user asks for one anyway, the agent is told to write a file into the diff instead.

If your project has a policy on AI contributions, put it in CONTRIBUTING.md for people and in AGENTS.md for their tools. The agent reads the second file even when its user skips the first.

What belongs in a global instruction file instead of AGENTS.md?

A global instruction file holds how you like to work, and the project AGENTS.md holds how the codebase works. Most agents read both. Codex loads ~/.codex/AGENTS.md before any project file, and Claude Code loads ~/.claude/CLAUDE.md. The global file is personal and lives in your dotfiles. The project file is shared and reviewed like code.

Global fileProject AGENTS.md
Location~/.codex/AGENTS.md, ~/.claude/CLAUDE.mdRepository root, plus nested folders
Who it is forYou, on every projectEveryone who works on the repository
What goes inHow you like to workHow this codebase works
Committed?To your dotfiles, if anywhereYes, through pull requests

Developers who publish their global files keep them about process and judgement, not tech stacks:

  • "Stop after three failed attempts and reassess." (Chris Dzombak)
  • "Never use --no-verify. Never disable a test to make it pass." (Dzombak again)
  • "Run git status before git add, and never git add -A." Chris Jones added this after an agent committed .env files.
  • "Never run migrate:fresh." Jones again, after an agent tried to drop every table to fix one missing column.
  • "Fix lint errors and flaky tests even if they were already broken." (Josh Finnie)

None of these belongs in a shared repository file. They are one person's habits.

To keep one copy across tools, Kaushik Gopal stores the instructions in a dotfiles repository. A make setup target symlinks them into each tool's expected path, and the CLAUDE.md is the one-line @AGENTS.md shim.

One trap in Claude Code: the fallback rule looks for a CLAUDE.md at or above the working directory, and your home folder is above every project in it. One Hacker News user found a stray ~/CLAUDE.md switching the AGENTS.md fallback off in every repository. Move it, or switch the setting to claude-md-and-agents-md.

How does AGENTS.md work in a monorepo?

In a monorepo, AGENTS.md works in layers: a root AGENTS.md holds rules for the whole repository, and each package can add its own AGENTS.md with local rules. Agents combine the files on the path to the code being edited, and the file closest to that code takes priority when rules conflict.

repo/
  AGENTS.md            # package manager, commit format, security rules
  apps/
    api/AGENTS.md      # API conventions, database rules
    web/AGENTS.md      # component and styling conventions

OpenAI Codex loads AGENTS.md files in a fixed order: the global file in ~/.codex, then each AGENTS.md from the project root down to the current working directory. An AGENTS.override.md in a folder replaces the AGENTS.md beside it (Codex docs). Check the combined size against Codex's 32 KiB default if you nest many files.

Most repositories need fewer nested files than guides suggest. Several guides state that OpenAI's own Codex repository contains 88 AGENTS.md files. A tree API check by DevToolLab on September 14, 2026 found two.

Splitting rules across files is also unproven as a way to raise compliance. In McMillan's study, adding nested instruction files gave 61.7% compliance against 67.7% for a single file, a gap that was not statistically significant. Add a nested AGENTS.md when a package has different commands or conventions, and for no other reason.

What is the difference between AGENTS.md, CLAUDE.md, and .cursorrules?

AGENTS.md is the cross-tool instruction file read by most AI coding agents. CLAUDE.md is Claude Code's own instruction file and takes priority over AGENTS.md inside Claude Code. .cursorrules is Cursor's older single-file format, now treated as legacy. All three hold the same kind of content: project rules in plain text.

FeatureAGENTS.mdCLAUDE.md.cursorrules
Read byCodex, Cursor, Copilot, Claude Code (fallback), and othersClaude CodeCursor
Nested filesYesYesNo, one root file
Local overrideAGENTS.override.md in CodexCLAUDE.local.mdNone built in
StatusOpen standard, growingCurrentLegacy
Best forThe shared source of truthClaude-only additionsNothing new

Feature rows follow Morph's 2026 comparison.

Keep the rules in AGENTS.md and make every other file point to it. That is already the common pattern. In our October 1, 2026 check, 17 of the 31 repositories with a root AGENTS.md also had a CLAUDE.md. In 14 of those 17, CLAUDE.md was a short pointer or symlink to AGENTS.md. Two projects, pytorch and bun, point the other way, from AGENTS.md to CLAUDE.md.

A CLAUDE.md with the single line @AGENTS.md works in every Claude Code session type, including Bedrock, Vertex, and Foundry, where the native AGENTS.md fallback is not yet available.

How do you keep an AGENTS.md file up to date?

Keep AGENTS.md up to date by giving it an owner, changing it in the same pull request as the thing it describes, and deleting lines once the underlying problem is fixed. A stale AGENTS.md is worse than a missing one, because agents follow outdated instructions as faithfully as current ones.

The strongest public files were not written in one sitting. They grew one failure at a time. Mitchell Hashimoto calls this harness engineering: each time an agent makes a mistake, decide whether a line in AGENTS.md will prevent it or whether it needs a small script. Every line in Ghostty's AGENTS.md traces back to a real failure.

  1. Name an owner. Add AGENTS.md to your CODEOWNERS file so every change gets a reviewer.
  2. Update it with the code. When a command, path, or tool changes, change AGENTS.md in that pull request.
  3. Add a line after a real mistake, not before one. When an agent gets the same thing wrong twice, write the rule down. Keep it to a sentence, phrased as a do.
  4. Re-run the task to check the line works. Pamela Fox reverts the agent's changes and runs the same task again. If the new line does not fix it, the line goes.
  5. Let the agent draft lessons after the fact. Agents write noisy rules up front and useful ones in hindsight. One Hacker News user ends every session with a standing prompt: add any lasting lesson to AGENTS.md, and add nothing if nothing was learned.
  6. Delete lines that tooling now enforces. Once a linter rule or CI check covers a line, remove it from AGENTS.md.
  7. Delete lines that newer models no longer need. Peter Steinberger's file reached about 800 lines, mostly written by Codex, which Steinberger described as organisational scar tissue. Much of it covered tools newer than the model's training data, such as the React Compiler and Tailwind 4. When the models caught up, those notes came out.
  8. Verify the commands. Run every command in AGENTS.md on a schedule and record the date in a "Last verified" line at the bottom of the file.

Keep task status out of the file. Geoffrey Huntley's Ralph loop has the agent write durable build knowledge to AGENTS.md and progress to a separate fix_plan.md. AGENTS.md is for things that stay true. A to-do list goes stale within a day.

Stale instruction files cause real failures. The authors of "Codified Context" (2026) report that outdated context documents twice led agents to write code that conflicted with recent refactors. The files change often in practice: Chatlatanagulchai et al. (2025) found that agent context files evolve like configuration code, through frequent small additions.

Not everyone likes the scar-tissue approach. Alex Jacobs argues that rules written in frustration never expire. A rule in Jacobs's file against creating documentation files, added after one unwanted summary, later made the model refuse a README that Jacobs had asked for. Models are also post-trained inside their own harness, so every line you add moves them further from the setup they were tuned in. Jacobs corrects the agent in conversation instead, and lets the correction end with the session.

Both camps agree on one thing. Small additions without deletions are how AGENTS.md grows past the point of usefulness, so a line that no longer fixes a real problem should go. Treat every line as temporary.

Frequently asked questions about AGENTS.md

Is AGENTS.md an official standard?

AGENTS.md is an open specification governed by the Linux Foundation's Agentic AI Foundation since December 2025. AGENTS.md is not an ISO or IETF standard. It is the shared convention most AI coding tools have adopted, published at agents.md.

Does Claude Code read AGENTS.md?

Claude Code reads AGENTS.md from version 2.1.277, released September 18, 2026, when the project has no CLAUDE.md or CLAUDE.local.md at or above the working directory. If a CLAUDE.md exists, Claude Code reads that file and skips AGENTS.md unless CLAUDE.md imports it with @AGENTS.md.

Does AGENTS.md have required fields?

AGENTS.md has no required fields, headings, or frontmatter. AGENTS.md is ordinary Markdown, and agents read whatever text the file contains. Common sections are commands, testing, code style, and boundaries.

Do you need an AGENTS.md at all?

Not always. Most of Simon Willison's projects have no AGENTS.md or CLAUDE.md. A project with clear docs and a thorough test suite gives the agent most of what it needs. One line at the start of a session, such as "Run tests with uv run pytest", covers the rest. If your tooling is strong, start without a file and add lines only when the agent gets something wrong.

Should you generate AGENTS.md with /init?

Generating AGENTS.md with /init is a poor default. Auto-generated files mostly restate what an agent can find in the repository, and ETH Zurich's 2026 study linked context files to over 20% higher inference cost with no general gain in task success. Write AGENTS.md by hand.

Can a repository have more than one AGENTS.md?

A repository can have an AGENTS.md at the root and another in any subdirectory. Agents apply the files on the path to the code being edited, and the closest file takes priority. Use nested files only where a package has different commands or rules.

What is the maximum size of an AGENTS.md file?

OpenAI Codex reads the first 32 KiB (32,768 bytes) of AGENTS.md by default and drops the rest without warning. The limit can be raised with the project_doc_max_bytes setting. We did not find a published size limit for other agents.

Share

See the mechanism
on your own documents.

Point Trail at the policy, SOP, agreement that decides your work, and watch it build an agent using rules traced back to the text they came from.