If you use more than one coding agent, you have probably ended up with a small pile of context files: CLAUDE.md for Claude Code, AGENTS.md for Codex, maybe leftover .cursorrules from an older Cursor setup. They all do the same conceptual job, which is giving the agent a persistent briefing that survives across sessions. The question is which one to maintain in 2026, and the answer is more nuanced than picking a winner.
Disclosure: I work on Blume, a desktop app that manages agent configuration across tools. This post stays practical and tool-agnostic; Blume appears once near the end where it is relevant.
The short version
- AGENTS.md is the closest thing to a universal standard. It is recognized by Codex CLI, Copilot CLI, Gemini CLI, Cursor, and Claude Code itself.
- CLAUDE.md is Claude Code's native file, and it still has capabilities AGENTS.md does not standardize, most notably hierarchical loading and imports.
- If you maintain only one file, make it AGENTS.md. If Claude Code is your primary agent, a two-line setup gives you both.
What the two files actually are
CLAUDE.md is project context that Claude Code injects into every conversation. It supports a hierarchy: a global file at ~/.claude/CLAUDE.md, a project root file, and per-directory files deeper in the tree that load when the agent works in those directories. It also supports importing other files by reference, so a short root file can point to detailed docs without pasting them.
AGENTS.md is the same idea, standardized across vendors. One markdown file at the repo root that any compliant agent reads on startup. Codex popularized it, and through 2025 and 2026 most major CLIs adopted it, including Claude Code.
Functionally, both are persistent project context. The difference is tooling compatibility and features around the edges.
Where AGENTS.md wins
Cross-tool coverage. One file, every agent. When a teammate uses Codex and you use Claude Code, AGENTS.md means you are maintaining shared institutional knowledge instead of per-tool copies that drift apart.
Team standardization. It is much easier to get a team to agree on one AGENTS.md than to keep four vendor files in sync. Drift between context files is one of the most common causes of agents behaving differently for different teammates on the same repo.
Longevity. Standards outlive tools. If you switch agents next year, AGENTS.md comes with you.
Where CLAUDE.md wins
Hierarchy. Claude Code loads directory-level CLAUDE.md files as it moves through the tree. A monorepo can have a lean root file plus focused files in apps/web and packages/api. AGENTS.md as commonly implemented is a single root file.
Imports. CLAUDE.md can reference other files and pull them in, which keeps the root file short while making detailed conventions reachable.
Claude-specific instructions. Guidance about Claude Code's own features (how to use its hooks, skills, subagents, or compaction behavior) belongs in a Claude-specific file, not in a cross-tool one where other agents will read it as noise.
One warning from teams who migrated: renaming your CLAUDE.md to AGENTS.md and calling it done leaves performance on the table. The files get read by different models with different instruction-following behavior, and content tuned for one agent does not automatically land the same way with another.
The setup that gives you both
The pattern that has become standard practice:
- Put all shared, tool-agnostic project context in AGENTS.md: build commands, architecture overview, conventions, testing rules.
- Make CLAUDE.md defer to it. Either symlink it (
ln -sf AGENTS.md CLAUDE.md) or keep a tiny CLAUDE.md that imports AGENTS.md and adds only Claude-specific instructions below. - Keep vendor-specific behavior (hooks, skills, model preferences) in each tool's own config, not in the shared file.
This way there is exactly one source of truth for project knowledge, and each agent still gets its native extras.
The maintenance problem nobody talks about
Whichever file you choose, the failure mode is the same: the file rots. Rules accumulate, some contradict each other, and some are silently ignored because the file grew past what the model reliably follows. Frontier models follow roughly 150 to 200 instructions before compliance starts dropping, and most long-lived context files blow past that without anyone noticing.
The symptom is subtle: the agent starts making mistakes it did not make three months ago, and nobody connects it to the context file.
A few ways to catch it:
- Review the file quarterly like you would review CI config
- Delete any rule the agent could infer from reading the code
- Convert rules that must always happen into hooks, which are deterministic, instead of instructions, which are suggestions
- Watch agent behavior for rules that are being ignored, which is a sign the file is too long or contradictory
That last one is tedious to do by hand, and it is the specific problem Blume automates: it watches how your agents actually behave across Claude Code, Codex, and Cursor, flags instructions your setup contradicts or ignores, and proposes edits you approve or reject. If your CLAUDE.md and AGENTS.md have been growing for a year, an automated second opinion tends to find things.
FAQ
Does Claude Code read AGENTS.md natively?
Yes. Claude Code recognizes AGENTS.md, so a symlinked or single-file setup works without duplication.
Should I keep .cursorrules?
Cursor has moved to .cursor/rules and also reads AGENTS.md. Treat legacy .cursorrules files as migration candidates.
Where do skills fit?
Skills (SKILL.md) are task-specific instructions loaded on demand, not persistent context. Keep always-true project facts in AGENTS.md and workflow recipes in skills.
What goes in neither file?
Anything a linter or formatter already enforces, anything derivable from the code in a few minutes of reading, and secrets of any kind.
If you have strong opinions on the single-file versus hierarchy trade-off, I would like to hear how you handle monorepos in particular.
Top comments (1)
The practical answer is probably less about the filename and more about the contract. The useful context file is the one the agent reliably loads, the team maintains, and the workflow can audit when behavior depends on it.