AGENTS.md: A README for Coding Agents

AGENTS.md is a plain Markdown file, placed at the root of a repository, that tells AI coding agents how to work in that project: how to install, build and test it, what style to follow and what to avoid. Its site calls it "a README for agents." Many different tools read the same file, so you write it once. Checked 31 October 2026.

At a glance

What it is for

The AGENTS.md site gives the reasoning. README files are for humans: quick starts, project descriptions and contribution notes. AGENTS.md carries the extra, sometimes detailed context agents need, such as build steps, tests and conventions that would clutter a README or do not matter to human contributors. The two are kept separate on purpose: it gives agents a clear, predictable place for instructions, keeps READMEs short for people, and adds agent-focused guidance that complements existing docs.

The format was chosen to avoid yet another proprietary file. The site says it emerged from collaboration across the AI software development ecosystem, including OpenAI Codex, Amp, Google's Jules, Cursor and Factory, and that it is stewarded by the Agentic AI Foundation under the Linux Foundation. The A2A project's 2026 announcement lists AGENTS.md among that foundation's projects, next to MCP and goose.

An example

The site's own example is short:

# AGENTS.md

## Setup commands
- Install deps: `pnpm install`
- Start dev server: `pnpm dev`
- Run tests: `pnpm test`

## Code style
- TypeScript strict mode
- Single quotes, no semicolons
- Use functional patterns where possible

There is no schema. The agent reads the text like a new teammate would. If you list a test command, the site's FAQ says the agent will try to run the relevant checks and fix failures before finishing.

What to put in it

The site suggests these sections as popular choices:

Write what an agent cannot work out by reading the code. "Run pnpm test" is useful. "Write clean code" is not. Concrete rules beat general advice, and short files get followed better than long ones.

Nested files for big repositories

For a monorepo, put another AGENTS.md inside each package. Agents read the nearest file in the directory tree, so the closest one takes precedence and each subproject can carry its own instructions. The site notes that, at the time of writing, the main OpenAI repository has 88 AGENTS.md files. A sensible layout:

Which tools read it

The site lists a long set of supporting tools, including Codex from OpenAI, Jules from Google, Factory, Aider, goose, opencode, Zed, Warp, VS Code, Devin, JetBrains Junie, Amp, Cursor, RooCode, Gemini CLI, Kilo Code, the coding agent from GitHub Copilot, Windsurf and Augment Code. That is the project's own list. We did not check how each tool loads the file today, so read the tool's own docs. On this site, see Codex CLI, Cursor, Gemini CLI and Amp.

Two tools need a small setting, per the FAQ:

# .aider.conf.yml
read: AGENTS.md

{ "context": { "fileName": "AGENTS.md" } }

The first is for Aider in .aider.conf.yml. The second goes in .gemini/settings.json for Gemini CLI. If you already use another filename, the site suggests renaming it and leaving a symbolic link: mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md.

AGENTS.md and Claude Code

Claude Code's own instruction file is CLAUDE.md, and it reads AGENTS.md too. The memory docs give this table:

So if your team uses several agents, keep the shared rules in AGENTS.md and make a small CLAUDE.md that imports it, adding anything Claude-specific:

@AGENTS.md

## Claude Code
- Use plan mode for changes that touch more than three files.

The docs note that reading AGENTS.md directly needs Claude Code v2.1.277 or later, and that some sessions cannot read it, in which case you import it from a CLAUDE.md. A setting in /config called Project instructions changes the default, for example to read both files.

Common mistakes

• Copying the README. The agent reads it already. Add what is missing.
• Writing a manual. Long files cost context and lower adherence.
• Vague style rules. Name the formatter or the specific convention.
• Stale commands. An old test command wastes runs. Review the file when tooling changes; the site says to treat it as living documentation.
• Secrets. Never put keys or private URLs in it. It is committed and shared.
• Conflicts. A nested file that contradicts the root file forces the agent to choose, and the closest one wins.

How it relates to other instruction layers

An instruction file is context, not enforcement. Claude Code's docs say to use a PreToolUse hook if an action must be blocked regardless of what the model decides. AGENTS.md can ask; it cannot force.

Moving to AGENTS.md from another file

If your team already keeps instructions for one tool, you do not need to start over. The site's advice for an existing file is to rename it and keep a symlink for backward compatibility. For tools that use their own formats, treat the migration as an edit, not a copy.

1. List the rules in the old file that every agent needs: commands, style, security.
2. Move those into AGENTS.md as short bullets under plain headings.
3. Leave tool-specific settings, such as a model choice or a permission mode, in that tool's own file.
4. Run each tool you use on one small task and note which rule it ignored.
5. Delete duplicates so the two files cannot drift apart.

How to review the file once a quarter

Open it next to your build scripts and ask four questions. Does every command still work? Is any rule now enforced by a linter, so the line can go? Did a recent code review catch something the agent should have known, so a line should be added? Is the file still short enough to read in two minutes? A file that passes those checks is doing its job. One that fails the first check is actively harmful, because agents trust commands they are given.

Get started

1. Start from our AGENTS.md starter template.
2. Add your real build, test and style commands.
3. Run an agent on a small task and see what it still gets wrong.
4. Add one line for each repeated mistake. Remove lines that never matter.
5. Read write a good AGENTS.md for a fuller walkthrough.

Our take

AGENTS.md is the sensible common denominator: one boring file that most coding tools can read. Use it for facts every agent needs and keep tool-specific tweaks elsewhere. The format has no enforcement and no schema, which is why it spread, and why quality depends entirely on what you write. We summarise the site and the Claude Code docs and have not tested each tool's loading behaviour.