AGENTS.md: one instructions file for every coding agent
AGENTS.md is the cross-agent conventions file. Where to put it, what to write, which tools read it, and how Claude Code loads it next to CLAUDE.md.
On this page6 sections
AGENTS.md is an open format described as a README for coding agents: a predictable place for setup, build, test, and convention notes. The point is one file many CLI agents read, instead of a different dotfile for each tool. It is plain Markdown with no required fields.
1. Create AGENTS.md at the repo root
Put the file at the root of the repository. In a large monorepo you can add nested AGENTS.md
files per subproject; an agent reads the nearest one in the tree, so the closest file takes
precedence. Explicit chat prompts still override whatever the file says.
2. Write build, test, and conventions
# Project overview
Short description of what this repo is.
## Setup & build
- Install: `pnpm i`
- Build: `pnpm build`
## Testing
- Run: `pnpm test` — all tests must pass before a PR.
## Conventions
- TypeScript strict, no `any`. Do not edit anything under `src/generated/`.
Keep it to what an agent cannot infer from the code: exact commands, conventions, and no-go zones.
3. Know which tools read it
The agents.md spec lists many adopters, including Codex, Cursor, Gemini CLI, GitHub Copilot coding agent, Jules, Aider, goose, Zed, Warp, and Windsurf. A repository already set up for one of these works for the others without a rename.
4. AGENTS.md vs CLAUDE.md in Claude Code
Claude Code reads AGENTS.md directly (v2.1.277 or later), but only when you have no CLAUDE.md or
CLAUDE.local.md in your working directory or above it. If both exist, CLAUDE.md wins by default.
To load both, type /config and set Project instructions to claude-md-and-agents-md. On older
versions, import it with @AGENTS.md inside a
CLAUDE.md.
5. Migrate from a tool-specific file
mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md
Renames the old singular file and leaves a symlink for backward compatibility. For Cursor or Copilot
rules, Claude Code’s /init reads .cursorrules and .github/copilot-instructions.md and folds the
relevant parts into a generated CLAUDE.md. Codex reads AGENTS.md natively, as in
Codex CLI first steps.
Verify it worked
In Claude Code, run /memory and look for your AGENTS.md path in the list, or run /context and
check Memory files. If the path is there, the file loaded.
If it fails:
- AGENTS.md is ignored in Claude Code — a
CLAUDE.mdon the project path takes precedence; set Project instructions toclaude-md-and-agents-md, or add@AGENTS.mdto thatCLAUDE.md. claude --versionbelow 2.1.277 — direct reading is unavailable; runclaude updateor use the@AGENTS.mdimport.- A
CLAUDE.mdsymlink checks out as one line of text on Windows — Git stored the symlink as plain text; use the@AGENTS.mdimport instead of a symlink.