Software Development
AGENTS.md vs CLAUDE.md: Agent Context Files
August 20269 min read
Both are Markdown files at a repository root that give an AI coding agent standing context about your project. CLAUDE.md is Claude Code's memory file, read automatically each session and supporting imports and nesting. AGENTS.md is a tool-agnostic convention adopted across many agents, so its strength is portability rather than deep integration with one tool.
No. Most teams keep a single source of truth and support both, making one file a thin pointer to the other or symlinking them where tooling allows. This gives Claude Code the depth of CLAUDE.md while contributors on other agents still read a file whose name they recognize, all without maintaining two separate copies.
Keep it short and factual: how to install, how to run tests, the conventions that matter, and the things the agent must not do. Long essays get skimmed and diluted, so favor terse, high-signal lines. The content is the same whether you name the file AGENTS.md or CLAUDE.md.
Claude Code's dedicated memory file is CLAUDE.md, which it loads automatically. If you standardize on Claude Code, lead with CLAUDE.md for automatic loading and imports, and add AGENTS.md pointing at the same content only if contributors use other agents that expect that name.
Because the agent follows the file literally, an outdated build command or a removed convention actively misleads it rather than simply being ignored. A stale file is worse than none, so review these files in pull requests the same way you review code and delete guidance that no longer holds.
Key Takeaway
AGENTS.md and CLAUDE.md both give AI coding agents standing instructions about your project, but they come from different ecosystems. CLAUDE.md is the memory file Claude Code reads automatically, while AGENTS.md is a tool-agnostic convention adopted across many agents. In practice you can support both, and often one is a thin pointer to the other.
Open a modern repository and you increasingly find a file whose only reader is a machine. AGENTS.md and CLAUDE.md are both that file: a place to tell an AI coding agent how your project builds, tests, and expects to be treated. The confusion is that two conventions now compete for the same job.
They are more alike than different. Both are plain Markdown, both live at the repository root, and both exist because pasting the same context into every session is a waste. What differs is who reads them and how widely they are understood. This comparison covers where each came from, how tools treat them, and how to run both without maintaining two copies.
| Aspect | AGENTS.md | CLAUDE.md |
|---|---|---|
| Origin | Cross-tool convention popularized across many agents | Claude Code memory file from Anthropic |
| Primary readers | Codex, Cursor, and other agents that adopted it | Claude Code, loaded automatically each session |
| Location | Repo root, with optional nested files per directory | Repo root, user home, and nested subdirectories |
| Format | Plain Markdown, no required schema | Plain Markdown, supports file imports |
| Scope signal | Portable across tools that recognize the name | Claude-specific, richest inside Claude Code |
CLAUDE.md is Claude Code's memory file. When a session starts, Claude Code reads it automatically and treats its contents as standing context: build commands, conventions, architecture notes, and rules you never want to repeat. It supports nesting, so a subdirectory can carry its own file, and it can import other files to keep the main document short.
AGENTS.md grew out of a desire for a neutral name that any agent could adopt, rather than one file per vendor. The content is the same kind of thing, but the promise is portability. A few points capture the split:
Whichever name you pick, the good content is identical. Keep it short and factual: how to install, how to run tests, the conventions that matter, and the things the agent must not do. Long essays get skimmed and diluted, so favor terse, high-signal lines over prose.
A minimal file for either convention looks like this:
# AGENTS.md
## Build & test
- Install: npm install
- Run tests: npm test
- Lint: npm run lint
## Conventions
- TypeScript strict; no default exports
- Keep functions small and pure
## Do not
- Do not edit files under generated/Do not maintain two full copies. Put the real content in one file and make the other a one-line pointer to it, or symlink them where your tooling allows. Duplicated instructions drift apart, and a stale agent file is worse than none because the agent trusts it.
Most teams do not have to choose. A pragmatic setup keeps a single source of truth and satisfies both conventions:
An agent context file is only as trustworthy as its last update. Because the agent follows it literally, an outdated build command or a removed convention actively misleads it. Review these files in pull requests the same way you review code, and delete guidance that no longer holds.
If your team standardizes on Claude Code, lead with CLAUDE.md, because you get automatic loading, imports, and the deepest understanding. If contributors use a mix of agents, add AGENTS.md so nobody is left without context, and point it at the same content.
The decision is less about picking a winner and more about reach. CLAUDE.md maximizes depth inside one tool; AGENTS.md maximizes breadth across many. Supporting both, backed by a single source, costs almost nothing and hedges against whichever convention your next teammate expects.
AGENTS.md and CLAUDE.md are the same good habit wearing two labels: write your project's context down so the agent stops guessing. Keep one authoritative file, mirror it to the other name, and treat both as living documentation that earns its place only while it stays true.