AGENTS.md
The AGENTS.md File, Explained
A README for coding agents: one plain-Markdown file at your repo root that tells AI coding tools how to build, test, and follow the conventions of your project. Here is the format, a copy-ready example, and a free generator.
Short answer
Create a file named AGENTS.md at the root of your repo and write, in plain Markdown, what an agent needs: setup and build commands, how to run tests, code style, and PR rules. There is no schema and no required section. Codex, Cursor, GitHub Copilot, Jules, Claude Code and 20+ other agents read it. In a monorepo, add more AGENTS.md files inside packages; the one closest to the code being edited wins. Claude Code skips AGENTS.md when a CLAUDE.md exists, so import it from CLAUDE.md if you keep both.
The big idea
One open Markdown file that most coding agents read
It is just Markdown
A plain AGENTS.md file at your repo root. No required fields, no schema — use whatever headings make sense for your project.
One file, many agents
Codex, Cursor, GitHub Copilot, Jules, Zed, Claude Code and 20+ other tools read the same AGENTS.md. Stop maintaining a different rules file per tool.
A README for agents
READMEs are for humans. AGENTS.md holds the build steps, test commands, and conventions an AI needs — without cluttering the README.
What AGENTS.md Is — and Why It Exists
A README.md is for humans: a quick start, what the project does, how to contribute. But coding agents need a different, often more detailed kind of context — the exact build steps, the test commands, the conventions to follow — that would clutter a README or simply isn't relevant to human contributors.
AGENTS.md gives agents a clear, predictable place to find that guidance. It is plain Markdown, lives at the root of your repository, and has no required fields — you write whatever headings help an agent work effectively. Crucially, it is a single open format: rather than maintain a separate rules file for every tool, you write one AGENTS.md and most agents read it. The agents.md site counts over 60,000 open-source projects that ship one.
It is one of the core Markdown-for-AI files — alongside llms.txt — and a good example of why Markdown is the format AI tooling keeps reaching for: it is readable, token-efficient, and preserves structure.
A Complete Example
Here is a realistic AGENTS.md. Notice there is nothing special about the syntax — it is just headings, lists, and inline code. Pick the sections that matter for your project and skip the rest.
# My Project
## Project overview
A TypeScript monorepo. Apps live in apps/, shared
code in packages/. Start with apps/web.
## Dev environment tips
- Run `pnpm install` at the root to set up all packages.
- Use `pnpm dev` to start the local server on :3000.
## Build and test commands
- `pnpm build` — production build, must pass clean.
- `pnpm test` — run the full Vitest suite.
- `pnpm lint` — ESLint + TypeScript checks.
## Code style
- TypeScript, 2-space indent, no semicolons.
- Match the style of the surrounding code.
## Testing instructions
- Add or update tests for any code you change.
- Fix all test and type errors before finishing.
## PR instructions
- Title format: [<area>] <Short description>
- Run `pnpm lint` and `pnpm test` before committing.What to Include
There are no required fields, so think of these as a menu, not a checklist. Add what helps an agent ship correct changes; leave out the rest.
| Section | Why it helps |
|---|---|
| Project overview | What the project is and how the code is laid out, so the agent orients itself before editing. |
| Build & test commands | The exact commands to build, test, and lint. Agents will run these and fix failures if you list them. |
| Code style guidelines | Language, formatting, naming, and the patterns you want matched — keeps generated code consistent. |
| Testing instructions | How to run tests, what must pass, and the expectation to add tests for changed code. |
| Security considerations | Secrets handling, what must never be committed, and any sensitive areas to avoid. |
| PR & commit guidelines | Title format, commit message conventions, and pre-commit checks the agent should run. |
Free AGENTS.md Generator
Edit the starter sections below — reorder, rename, or delete them — and the AGENTS.md builds live on the right. Copy it or download it as AGENTS.md. Everything runs in your browser.
# My Project
## Project overview
A short description of what this project is and how the code is organized.
Mention the language, framework, and where the main entry points live.
## Dev environment tips
- Use `pnpm install` to install dependencies.
- Run `pnpm dev` to start the local server.
- Node 20+ is required.
## Build and test commands
- `pnpm build` — production build, must pass with zero errors.
- `pnpm test` — run the full test suite.
- `pnpm lint` — ESLint + TypeScript checks.
## Code style
- TypeScript, 2-space indentation, no semicolons.
- Prefer functional components and named exports.
- Match the style of the surrounding code.
## Testing instructions
- Add or update tests for any code you change.
- Run `pnpm test` and fix failures before finishing.
- Run `pnpm lint` after moving files or changing imports.
## PR instructions
- Title format: [<area>] <Short description>
- Run `pnpm lint` and `pnpm test` before committing.
Generated entirely in your browser — nothing is uploaded. Save the result as AGENTS.md at the root of your repository.
Nested Files & Precedence
For a single project, one root-level AGENTS.md is enough. In a large monorepo, drop a nested AGENTS.md inside each package so every subproject can ship tailored instructions.
my-monorepo/
├─ AGENTS.md ← repo-wide defaults
├─ apps/
│ └─ web/
│ └─ AGENTS.md ← overrides for the web app
└─ packages/
└─ ui/
└─ AGENTS.md ← overrides for the ui packageNearest file wins
The closest AGENTS.md to the file being edited takes precedence. Most tools still load the root file too: Codex joins every AGENTS.md from the repo root down to the current directory, so closer files come later and win where they disagree.
Chat overrides everything
An explicit instruction you give in the prompt takes priority over anything written in an AGENTS.md file.
~/.codex/AGENTS.md, lets an AGENTS.override.md replace the AGENTS.md in the same folder, and stops reading once the combined files reach 32 KiB by default. VS Code marks nested AGENTS.md support as experimental. Check your tool's docs before relying on deep nesting.AGENTS.md vs README.md, CLAUDE.md & .cursorrules
These often sit in the same repo and get confused. AGENTS.md is the vendor-neutral baseline; the others are either for humans or for one specific tool.
| File | Read by | Scope | Note |
|---|---|---|---|
| AGENTS.md | All AI coding agents | Build, test, style & conventions for the whole repo | The open, cross-tool format. 60k+ open-source projects, per agents.md. |
| README.md | Human contributors | What the project is, install steps, how to contribute | Kept concise; agent-only detail moves to AGENTS.md. |
| CLAUDE.md | Claude Code (Copilot's cloud agent and CLI read it too) | Claude-specific guidance | If a CLAUDE.md exists, Claude Code skips AGENTS.md unless CLAUDE.md imports it with @AGENTS.md. |
| .cursorrules | Cursor (legacy) | Tool-specific rules for one editor | Still supported but deprecated. Cursor recommends .cursor/rules, or AGENTS.md for simple setups. |
AGENTS.md vs CLAUDE.md
CLAUDE.md is Claude Code's own instructions file. Since v2.1.277, Claude Code also reads AGENTS.md directly, but only as a fallback: if a CLAUDE.md, .claude/CLAUDE.md, or CLAUDE.local.md sits in your working directory or any folder above it, Claude reads those and skips AGENTS.md. Your personal ~/.claude/CLAUDE.md does not count and loads alongside it.
| Your repo has | Claude Code reads (default) |
|---|---|
| AGENTS.md only | AGENTS.md |
| AGENTS.md and CLAUDE.md (or CLAUDE.local.md) | CLAUDE.md only. AGENTS.md is ignored. |
| CLAUDE.md that starts with @AGENTS.md | Both: AGENTS.md first, then the rest of CLAUDE.md |
So keep one shared AGENTS.md for every agent, and if you need Claude-only rules, put them in a CLAUDE.md that imports AGENTS.md on its first line:
@AGENTS.md
## Claude Code
Use plan mode for changes under src/billing/.If you need no Claude-specific rules, a symlink works too (ln -s AGENTS.md CLAUDE.md), though Anthropic recommends the import on Windows, where Git often checks symlinks out as plain text. To make Claude read both files without an import, set Project instructions to claude-md-and-agents-md in /config. For where each CLAUDE.md lives, load order, and .claude/rules, see the CLAUDE.md guide. Source: Claude Code memory docs.
Which Tools Read AGENTS.md
AGENTS.md emerged from collaboration across OpenAI Codex, Amp, Jules (Google), Cursor, and Factory. In December 2025 OpenAI contributed it to the Agentic AI Foundation, a Linux Foundation project, which now stewards it. These agents read it, per agents.md and the tools' own docs:
Gemini CLI reads GEMINI.md unless you set context.fileName, and Aider only loads files you list with read:; the FAQ has both one-liners. GitHub Copilot's cloud agent and CLI read AGENTS.md, CLAUDE.md, and GEMINI.md; Copilot Chat in VS Code reads AGENTS.md.
Common Mistakes
The errors that make an AGENTS.md less useful than it should be.
Avoid
Keeping five tool-specific rules files in sync
Do
Write one AGENTS.md and point every tool at it
Avoid
Dumping the whole README into AGENTS.md
Do
Include the agent-relevant build, test, and convention detail
Avoid
Listing test commands you do not want run
Do
Only list commands that are safe to execute
Avoid
One giant AGENTS.md for a large monorepo
Do
Add nested AGENTS.md files inside each package
Avoid
Adding a CLAUDE.md next to AGENTS.md and assuming Claude reads both
Do
Start the CLAUDE.md with an @AGENTS.md import
Frequently Asked Questions
What is AGENTS.md?
AGENTS.md is a plain Markdown file at the root of a code repository that tells AI coding agents how to work on the project: setup and build commands, how to run tests, code-style conventions, and any gotchas. Think of it as a README written for agents instead of humans. According to agents.md, over 60,000 open-source projects use one, and it is read by OpenAI Codex, Cursor, GitHub Copilot, Jules, Zed, Claude Code, and 20+ other tools.
Are there any required fields in AGENTS.md?
No. AGENTS.md is just standard Markdown with no required fields or schema. You can use any headings you like; the agent simply reads the text you provide. Common sections include a project overview, build and test commands, code style guidelines, testing instructions, security considerations, and pull-request or commit conventions, but none of them are mandatory.
Where do I put the AGENTS.md file?
Create it as AGENTS.md (all caps) at the root of your repository. In a monorepo you can add more AGENTS.md files inside individual packages. Agents read the nearest file in the directory tree, so each subproject can ship tailored instructions. Some tools also support a personal, global file, for example ~/.codex/AGENTS.md for Codex.
What happens if instructions conflict?
The agents.md answer: the AGENTS.md closest to the file being edited wins, and an explicit instruction in your chat prompt overrides everything. In practice most tools combine the files rather than picking one. Codex, for example, joins every AGENTS.md from the repo root down to the current directory, so the closer files come later and override earlier guidance where they disagree.
Will an agent actually run the commands listed in AGENTS.md?
Yes, if you list them. When you include build, test, or lint commands, the agent will try to run the relevant checks and fix any failures before finishing the task. That is useful, but it also means you should only list commands that are safe to run automatically.
What is the difference between AGENTS.md and README.md?
README.md is written for humans: what the project is, how to install it, and how to contribute. AGENTS.md is written for coding agents: the exact build commands, test commands, code-style rules, and conventions an AI needs to make correct changes. Keeping them separate lets the README stay concise while giving agents a predictable place to find machine-relevant instructions.
AGENTS.md vs CLAUDE.md: do I need both?
Usually not. Claude Code (v2.1.277 and later) reads AGENTS.md on its own, but only when the repo has no CLAUDE.md, .claude/CLAUDE.md, or CLAUDE.local.md in the working directory or above it. If a CLAUDE.md exists, Claude reads only that and skips AGENTS.md. So either keep AGENTS.md alone, or, if you want Claude-specific rules, make @AGENTS.md the first line of your CLAUDE.md and put the Claude-only instructions below it. A personal ~/.claude/CLAUDE.md does not count and loads alongside AGENTS.md.
Does Claude Code read AGENTS.md?
Yes, since Claude Code v2.1.277. By default it reads AGENTS.md as the project instructions when there is no CLAUDE.md or CLAUDE.local.md in your working directory or above it, and it picks up a subdirectory's AGENTS.md when it opens a file there. To have Claude read both files, set Project instructions to claude-md-and-agents-md in /config, or import AGENTS.md from CLAUDE.md with @AGENTS.md.
Which AI coding tools read AGENTS.md?
The agents.md site lists OpenAI Codex, Cursor, GitHub Copilot, Jules and Gemini CLI from Google, Aider, Zed, Amp, Windsurf, Devin, Warp, RooCode, Junie from JetBrains, Factory, Kilo Code, goose, opencode, VS Code, Augment Code, Ona, Semgrep, Phoenix, and UiPath. Claude Code reads it too. Two need a one-line setting: Gemini CLI reads GEMINI.md by default, and Aider only loads files you list.
How do I migrate an existing AGENT.md or rules file to AGENTS.md?
Rename the file to AGENTS.md and, if you want backward compatibility, create a symbolic link from the old name: mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md. For tools that need it, point them at AGENTS.md: set read: AGENTS.md in .aider.conf.yml for Aider, or { "context": { "fileName": "AGENTS.md" } } in .gemini/settings.json for Gemini CLI.
Is AGENTS.md an official standard?
It is an open format, not a formal standard with a spec body. It came out of work across OpenAI Codex, Amp, Jules from Google, Cursor, and Factory. In December 2025 OpenAI contributed it to the Agentic AI Foundation, a Linux Foundation project launched alongside Anthropic's Model Context Protocol and Block's goose, which now stewards it. Because it is plain Markdown with no schema, there is nothing to install or validate.