What Is AGENTS.md? How to Create and Use It (2026)

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.

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.

Claude Code's rule has three cases:

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.

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.

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.

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.

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.

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:

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.

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:

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.

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.

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.

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.

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.

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 each repeated mistake. When an agent gets the same thing wrong twice, write the rule down.
4. Delete lines that tooling now enforces. Once a linter rule or CI check covers a line, remove it from AGENTS.md.
5. 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.

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.

Small additions without deletions are how AGENTS.md grows past the point of usefulness. 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.

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.