AGENTS.md Guide: How to Write One (vs CLAUDE.md)

AGENTS.md is a plain Markdown file at the root of a repository that tells AI coding agents how to work on the project: how to build it, how to run the tests, which conventions to follow and what to avoid. Think of it as a README written for agents. One AGENTS.md is read by Codex, Cursor, GitHub Copilot's agents, Aider (with one config line) and many others. Claude Code reads it too, but by default only when the repository has no CLAUDE.md.

The AGENTS.md site says the format is used by more than 60,000 open-source projects. OpenAI released it in August 2025 and contributed it to the Agentic AI Foundation under the Linux Foundation that December, alongside MCP and Block's goose. This guide covers what to put in AGENTS.md, exactly how each major tool loads it, and how to share one file with Claude Code without duplicating instructions.

What goes in an AGENTS.md file

There are no required fields. Agents read whatever Markdown you write. The sections that consistently pay off are the ones a new teammate would otherwise ask about:

• Setup and build commands: the exact commands, such as pnpm install and pnpm build.
• Test commands: how to run all tests, one package and one test. Agents use these to check their own work.
• Code style: only rules that differ from your linter's defaults, or that the linter can't enforce.
• Project layout: where things live, if it isn't obvious from the folder names.
• Boundaries: files never to edit (generated code, vendored code, migrations), commands never to run, and secrets to never touch.
• Pull request and commit rules: title format, required checks, changelog conventions.

Keep it short and concrete. Claude Code's documentation recommends staying under about 200 lines per instruction file, because longer files use more context and reduce adherence. Codex stops reading instruction files once their combined size reaches 32 KiB by default. "Run pnpm test before committing" beats "make sure things work."

A copy-paste AGENTS.md template

# AGENTS.md

## Project overview
Next.js 15 web app with a Postgres database (Prisma). API routes live in `app/api/`.

## Setup
- Install: `pnpm install`
- Start dev server: `pnpm dev` (http://localhost:3000)
- Local database: `docker compose up -d db`, then `pnpm prisma migrate dev`

## Testing
- All tests: `pnpm test`
- One file: `pnpm vitest run path/to/file.test.ts`
- Run `pnpm lint && pnpm typecheck` before finishing any task.

## Conventions
- TypeScript strict mode; no `any` without a comment explaining why.
- Server code must not import from `app/(client)/`.
- Use the logger in `lib/log.ts`, never `console.log`.

## Boundaries
- Never edit files in `prisma/migrations/` by hand; create a new migration.
- Never commit `.env*` files or print secret values.
- Ask before adding a production dependency.

## Pull requests
- Title format: `[area] short description`
- Include a test for every bug fix.

Swap in your own stack. The structure (overview, setup, testing, conventions, boundaries, PRs) works for almost any repository.

Nested AGENTS.md files for monorepos

You can put an AGENTS.md in any subdirectory. The rule shared across tools is that the closest file to the code being edited wins, and the user's explicit chat instructions override every file. A monorepo might have a short root file for shared rules and a file in each package for that package's test command. The AGENTS.md site notes that OpenAI's main repository had 88 of them at the time of writing.

How each coding agent loads AGENTS.md

This is where most guides are vague. Here is what each tool's own documentation says, as of October 2026.

OpenAI Codex

Codex builds an instruction chain at the start of each run, according to its AGENTS.md guide. It first reads a global file from ~/.codex, preferring AGENTS.override.md over AGENTS.md. It then walks from the project root down to your current directory and takes at most one file per directory: AGENTS.override.md, then AGENTS.md, then any fallback names you configure. Files are joined root first, so the closest file appears last and takes precedence. It skips empty files and stops at project_doc_max_bytes, which is 32 KiB by default.

Two useful knobs live in ~/.codex/config.toml. project_doc_fallback_filenames lets Codex treat another name, such as TEAM_GUIDE.md, as instructions. project_doc_max_bytes raises the cap. In the CLI, /init scaffolds an AGENTS.md for you.

Claude Code

Claude Code uses CLAUDE.md as its own instruction file, but its memory docs describe native AGENTS.md support from version 2.1.277. The default behavior is the part people miss:

• If your repository has an AGENTS.md and no CLAUDE.md or CLAUDE.local.md in the working directory or above it, Claude reads AGENTS.md.
• If both exist, Claude reads only the CLAUDE.md files by default.
• You can change this with the Project instructions setting in /config. The value claude-md-and-agents-md loads both.
• Claude Code does not read AGENTS.override.md or AGENTS.local.md.

The most portable setup is a one-line import. Create a CLAUDE.md next to your AGENTS.md that pulls it in, then add any Claude-only notes below:

@AGENTS.md

## Claude Code
Use plan mode for changes under `src/billing/`.

A symlink (ln -s AGENTS.md CLAUDE.md) also works. Claude's docs advise using the import on teams with Windows users, because Git may check symlinks out as plain text files.

Cursor

Cursor reads an AGENTS.md at the project root and in subdirectories, applying a nested file when the agent works on files in that folder. Its .cursor/rules/ system adds features plain Markdown lacks, such as glob-scoped rules and rules the agent pulls in only when relevant. A sensible split is shared, portable guidance in AGENTS.md and Cursor-specific scoping in rules. See Cursor's rules docs.

GitHub Copilot

GitHub Copilot supports AGENTS.md for its cloud agent and CLI, and VS Code can use it as project instructions. Repository-wide instructions can also go in .github/copilot-instructions.md. GitHub's docs say Copilot code review doesn't use AGENTS.md, so put review-specific rules where that feature reads them. See GitHub's custom instructions docs.

Gemini CLI and Aider

Gemini CLI reads GEMINI.md by default. To make it read AGENTS.md, set the context file name in .gemini/settings.json:

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

Aider needs one line in .aider.conf.yml: read: AGENTS.md.

AGENTS.md vs CLAUDE.md: which should you use?

Use AGENTS.md as the source of truth if more than one coding agent touches the repository, or if contributors bring their own tools. It's the only file read across most of the ecosystem.

Add a CLAUDE.md that imports AGENTS.md if your team uses Claude Code and wants Claude-specific additions, such as hook reminders, plan-mode rules or skill pointers.

Use only CLAUDE.md if Claude Code is the only agent anyone uses and you want its extra features: user, project and local scopes, @path imports, and path-scoped rules in .claude/rules/.

Don't maintain two copies of the same instructions. They drift, and an agent that reads both gets contradictions.

Best practices that actually change agent behavior

1. Write commands, not wishes. Exact, copy-pasteable commands get run; vague guidance gets ignored.
2. Document the non-obvious. Skip anything an agent can learn by reading package.json or the folder tree. Spend your lines on gotchas.
3. State boundaries plainly. "Never edit generated/" is more reliable than hoping the agent notices a header comment.
4. Use hooks or CI for hard rules. Instruction files are context, not enforcement. Claude's docs recommend hooks for anything that must always happen, and the same logic applies to CI checks for every agent.
5. Update it when an agent repeats a mistake. Treat AGENTS.md as living documentation. If you correct an agent twice for the same thing, add a line.
6. Never put secrets in it. The file is committed and fed to hosted models.

Pros and cons of AGENTS.md

Pros: One vendor-neutral file instead of five tool-specific ones. Plain Markdown with no schema to learn. Supports nesting for monorepos. Governed by a neutral foundation.

Cons: Loading rules still differ between tools. Claude Code prefers CLAUDE.md, and Gemini CLI and Aider need a setting. It has no built-in way to scope a rule to file types; tools add that through their own rule systems.

Who it's for: Any team or open-source project where more than one coding agent might touch the code. That is most of them by now.

To connect the same agents to your own tools, see how to build an MCP server in Python. For background on how the open standards fit together, read MCP vs A2A.

Related guides: compare the agents that read this file in Claude Code vs Codex vs Gemini CLI, or see the best open-source coding agents.

FAQ

Is AGENTS.md the same as CLAUDE.md?

No. Both are Markdown instruction files, but CLAUDE.md is Claude Code's own format, with extra features such as imports and scoped rules. AGENTS.md is the cross-tool standard. Claude Code can read AGENTS.md, and the simplest bridge is a CLAUDE.md containing @AGENTS.md.

Where do I put AGENTS.md?

At the repository root. Add more files in subdirectories when a package needs different instructions; the closest file to the code being edited takes precedence.

Does Claude Code read AGENTS.md?

Yes, from version 2.1.277, but by default only when there is no CLAUDE.md or CLAUDE.local.md in your working directory or above it. Change the Project instructions setting in /config to load both.

How long should AGENTS.md be?

Short enough to read in a minute. Claude Code's docs suggest under 200 lines per file, and Codex stops loading instruction files at 32 KiB combined by default. Move package-specific detail into nested files.

Can an agent generate AGENTS.md for me?

Yes. Codex's /init command creates one, and the AGENTS.md site notes that most coding agents can scaffold one if you ask. Review the draft by hand: generated files tend to repeat what's already obvious from the code and miss the gotchas only your team knows.