You have a CLAUDE.md in your repo. You have a GEMINI.md. If you use Cursor, you have .cursorrules. They all say roughly the same thing: run pnpm test before committing, don't touch the generated files in src/generated/, keep components colocated with their tests.
Then you update one and forget the other two. The agent you're using today reads the stale file. Bugs follow.
There's a spec for this now. It's called AGENTS.md and it's worth knowing about.
The problem: one repo, five instruction files
Every coding agent has its own convention for where it looks for instructions. Claude Code reads CLAUDE.md. Codex reads AGENTS.md. Cursor reads .cursorrules. Gemini Code Assist reads GEMINI.md. Some tools read from multiple places and merge them.
The result is that a shared codebase ends up with a pile of overlapping instruction files, each slightly out of date. Whoever added the note about the database migration last month updated CLAUDE.md. Nobody updated the Cursor file. Now your teammate is using Cursor and the agent keeps trying to use the old migration pattern.
This is a solved problem in human tooling. We don't maintain separate README-for-alice.md and README-for-bob.md. We have one README. We need the same thing for agents.
What AGENTS.md is and where it came from
AGENTS.md is an open format that works as a "README for agents." It loads automatically into an agent's context and holds the information that would clutter a human README: build steps, test commands, project conventions, and things the agent should never do.
The format emerged from collaboration across the ecosystem. OpenAI Codex, Google Jules, Cursor, Amp, and Factory were all involved in the early development. A growing set of tools now supports it: Aider, goose, opencode, Zed, Warp, VS Code, and Devin are all on board.
The spec lives at agents.md and on GitHub. It's intentionally minimal. The goal is to be readable by both humans and tools, not to define a complex schema.
What goes in it (and what stays in the README)
Think of it as the context your agent needs that a human already knows from working in the repo. A good AGENTS.md usually covers:
# AGENTS.md
## Build
pnpm install
pnpm run build
## Test
pnpm test # unit tests (Vitest)
pnpm test:e2e # Playwright, requires local dev server
## Conventions
- Components live next to their tests: src/components/Foo/Foo.tsx + Foo.test.tsx
- Never edit files in src/generated/ — they are codegen outputs
- Use Zod for all input validation, not manual typeof checks
- CSS modules only, no inline styles in components
## Architecture notes
- Auth is handled in src/middleware.ts — do not add auth logic to route handlers
- Database access goes through src/lib/db.ts only — never import Prisma client directly
What stays in the README: human onboarding context, project history, how to get a dev environment running the first time, links to docs. That's for humans. The agent doesn't need your origin story.
The split sounds obvious once you name it. In practice, most READMEs are a mix of both, which is why agents end up reading things that don't help them and missing things that do.
Tool support across the ecosystem
Here's where things stand. This is worth bookmarking because it's moving fast:
| Tool | Reads AGENTS.md |
|---|---|
| OpenAI Codex | Yes (native) |
| Google Jules | Yes |
| Cursor | Yes |
| Amp | Yes |
| Factory (Droids) | Yes |
| Aider | Yes |
| goose | Yes |
| opencode | Yes |
| Zed | Yes |
| Warp | Yes |
| VS Code (Copilot) | Yes |
| Devin | Yes |
| Claude Code | Reads CLAUDE.md natively; AGENTS.md support in progress |
Claude Code currently reads CLAUDE.md as its primary file. If you're using Claude Code alongside other agents, you still want AGENTS.md as your canonical source and CLAUDE.md as a thin wrapper (more on that in the next section).
Deriving CLAUDE.md from one source
The pattern that works: put everything shared in AGENTS.md. In CLAUDE.md, include a short note pointing to it, then add only configuration specific to Claude.
<!-- CLAUDE.md -->
# Claude Code Instructions
See AGENTS.md for shared project conventions. The notes below are Claude-specific.
## Extended thinking
Use extended thinking for architecture decisions and debugging sessions where context depth matters.
## MCP tools
Local dev uses the Filesystem MCP mounted at /tmp/project. Don't use the Bash tool for file operations when the Filesystem MCP is available.
This way AGENTS.md is the truth. CLAUDE.md is an extension. When a convention changes (new test runner, new linting rule), you update one file.
Same pattern for GEMINI.md or any other agent file: start with "see AGENTS.md" and add only the things that are genuinely specific to that tool.
Gotchas: hierarchy, extensions, and edge cases
Codex extends the spec with a hierarchy. OpenAI Codex supports a hierarchical AGENTS.md system where you can place AGENTS.md files in subdirectories and they compose together. This is an extension specific to Codex, not part of the base spec. Other tools read the root AGENTS.md only (or whatever their lookup path is). Don't rely on the hierarchy pattern if you're targeting the broader ecosystem.
Keep it evergreen. The same rule about avoiding dates that applies to your README applies here. Agent instructions that reference a specific sprint or quarter confuse the agent when that sprint is long past. Write instructions for the current state of the codebase, not for what you were working on when you wrote them.
Test descriptions, not test output. Some teams paste in example test output to tell the agent "this is what passing tests look like." That output goes stale fast. Instead, describe the test runner invocation and what a passing run looks like in plain terms. If you're wiring up more rigorous evaluation for LLM agents in production, this framing carries over.
Tool lookup paths vary. Most tools look for AGENTS.md at the repo root, but some support workspace configurations. Check the docs for whichever tool you're using if you have a monorepo setup. Codex in particular has well documented monorepo support via the hierarchical extension.
FAQ
What is AGENTS.md?
It's an open format for a single instruction file that multiple coding agents can read automatically. It holds project conventions, build commands, and test steps that you want every agent working in the repo to know.
Which tools support AGENTS.md?
OpenAI Codex, Google Jules, Cursor, Amp, Factory, Aider, goose, opencode, Zed, Warp, VS Code (Copilot), and Devin. Claude Code reads CLAUDE.md natively and AGENTS.md support is in progress.
How is it different from a README?
A README is written for humans. AGENTS.md is written for agents. It covers build and test mechanics, codebase conventions, and architecture rules. Human onboarding context belongs in the README.
If you want to go deeper on structuring AI systems architecture in your codebase, that is exactly the kind of work I take on.
More writing on agentic patterns and developer tooling on my blog.
Curious which agents you're targeting. Drop a comment with your stack and whether you've hit the problem of maintaining five instruction files.
Top comments (0)