# AGENTS.md vs CLAUDE.md: Which Context File Should Your Coding Agents Use in 2026? > Source: > Published: 2026-08-05 13:47:55+00:00 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](https://blume.codes), 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. **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. **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. **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 pattern that has become standard practice: `ln -sf AGENTS.md CLAUDE.md` ) or keep a tiny CLAUDE.md that imports AGENTS.md and adds only Claude-specific instructions below.This way there is exactly one source of truth for project knowledge, and each agent still gets its native extras. 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: That last one is tedious to do by hand, and it is the specific problem [Blume](https://blume.codes) 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. **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.