AGENTS.md vs CLAUDE.md
Short answer: they do the same job — tell an AI coding agent how to work in your repo — but they're read by different tools. AGENTS.md is the open, tool-agnostic standard (28+ agents read it); CLAUDE.md is the file Claude Code reads. The trick is keeping one source of truth.
What is AGENTS.md?
An open, vendor-neutral Markdown file at the root of your repo that gives coding agents the context they need: stack, commands, conventions, constraints, definition of done. It's deliberately tool-agnostic, which is why 28+ agents read it — OpenAI Codex, Cursor, Aider, Cline, Continue, Goose, Jules, Zed and more. You can also place an AGENTS.md in a subdirectory; the nearest file to the code being edited wins.
What is CLAUDE.md?
The memory file Claude Code reads. Same purpose as AGENTS.md, with two Claude-specific extras: it supports @path imports (so one file can pull in others), and there's a user-level ~/.claude/CLAUDE.md that applies across all your projects in addition to the per-repo file.
The honest difference
| AGENTS.md | CLAUDE.md | |
|---|---|---|
| Read by | 28+ tools (Codex, Cursor, Aider, Cline, Continue, Goose, Zed…) | Claude Code |
| Standard | Open, tool-agnostic | Claude Code convention |
| Imports | No (one flat file; subdir override) | Yes — @path imports |
| User-level file | No | ~/.claude/CLAUDE.md |
| What goes in it | Identical: stack · commands · conventions · don't · definition of done | |
Should you use both? Yes — but keep one source
If more than one agent touches your repo, you want both files present. The mistake is maintaining two copies — they drift, and a stale rule is worse than no rule. Two clean ways to keep a single source of truth:
Option A — symlink (simplest):
ln -s AGENTS.md CLAUDE.md
Option B — import (Claude Code): make CLAUDE.md a one-liner:
@AGENTS.md
Either way you edit one file and every agent stays current.
What goes in them (keep it lean)
- One-line project description + the stack
- Key commands — build, test, lint, deploy
- Conventions & decisions the agent must follow
- Explicit don't-dos (the anti-patterns)
- Definition of done
Keep it short. ETH Zurich's Evaluating AGENTS.md found dump-everything machine-generated files lowered task success ~3% and raised cost 20%+, while lean curated ones improved success ~4%. More rules ≠ better agent.
Generate AGENTS.md + CLAUDE.md (and Cursor, Copilot, Gemini) — free
Fill in your project's rules once and get every file, correctly formatted, with a token-budget warning so they stay lean. No signup.
Open the Agent Memory Compiler →Keep them in sync with your work
Generated files drift the moment your project changes. In TaskPrio your project's rules live in one place and your agents pull them over MCP with get_next_task — so the memory and the task queue are the same source of truth. Edit once; every tool and every agent stays current. See how the MCP queue works →
FAQ
What's the difference between AGENTS.md and CLAUDE.md?
Same guidance, different readers — AGENTS.md is the open standard (28+ tools), CLAUDE.md is Claude Code's. CLAUDE.md adds @-imports and a user-level file. Content is otherwise identical.
Do I need both?
If you use more than one agent, yes — but keep one source: ln -s AGENTS.md CLAUDE.md or @AGENTS.md inside CLAUDE.md. Don't maintain two copies.
What should go in them?
Stack, commands, conventions, don't-dos, definition of done — kept lean. Bloated context files measurably hurt agent success.