Quick answer: AGENTS.md is an open, cross-tool standard for giving any AI coding agent (Codex, Cursor, Copilot, Gemini CLI, Aider, Windsurf, Zed, and more) repo-level instructions in one shared Markdown file. CLAUDE.md is Anthropic's own, richer instruction format built specifically for Claude Code, with features AGENTS.md doesn't have — imports, path-scoped rules, and personal local overrides. Claude Code does not read AGENTS.md automatically, so the recommended setup for most teams is both files together: AGENTS.md as the shared source of truth, CLAUDE.md as a thin layer that imports it.
What is AGENTS.md?
AGENTS.md is a plain-Markdown file, placed at the repo root, that emerged from collaboration between Sourcegraph, OpenAI, Google, Cursor, and Factory, and is now stewarded by the Agentic AI Foundation under the Linux Foundation. It has no formal schema — just headers for things like code style, build/test commands, and project structure — and it's already in over 60,000 GitHub repositories, including projects like n8n and awesome-go. The entire point is portability: write it once, and Codex, Cursor, Copilot, Gemini CLI, Aider, Windsurf, and Zed all read it the same way.
What is CLAUDE.md?
CLAUDE.md is Anthropic's own instruction file format, and Claude Code is its primary (effectively only)
consumer. It uses Markdown too, but layers on features AGENTS.md doesn't have: a hierarchical configuration
system (managed policy, user global settings, project root, subdirectory rules, path-scoped rules), an
@import syntax for composing multiple files together, and a CLAUDE.local.md
variant for personal, gitignored settings that shouldn't be committed.
The 5 real differences
1. Tool compatibility
AGENTS.md works across essentially every major agent except Claude Code by default. CLAUDE.md is read by Claude Code specifically — that's its primary consumer, full stop.
2. Configuration hierarchy
CLAUDE.md supports layered configuration across managed policy, user-global, project-root, and subdirectory levels. AGENTS.md supports subdirectory placement for coarse scoping but has no user-level or local-override equivalents.
3. Import system
CLAUDE.md's @import syntax lets Claude pull in referenced content from other files when
relevant, so you can compose instructions from multiple sources. AGENTS.md has no equivalent mechanism.
4. Path-scoped rules
CLAUDE.md can activate rules only for specific file patterns using YAML frontmatter — a rule that
only applies inside /api, for example. AGENTS.md's scoping is coarser: subdirectory placement
only.
5. Local overrides
CLAUDE.md supports CLAUDE.local.md for personal settings you don't want committed to the
repo. AGENTS.md is designed to be committed and shared team-wide, with no built-in personal-override
mechanism.
Does Claude Code read AGENTS.md automatically?
No — this is the detail that trips people up. As confirmed in Anthropic's own May 2026
documentation, Claude Code does not read AGENTS.md on its own. If you already have an AGENTS.md file (very
likely, given its adoption) and want Claude Code to respect it, you need to either reference it explicitly
with an @import inside CLAUDE.md, or symlink the two files together.
The recommended setup: use both together
Put universal, tool-agnostic rules — code style, build/test commands, project structure, boundaries — in AGENTS.md. Put Claude-specific configuration in CLAUDE.md, and have it import the shared file instead of duplicating content:
# CLAUDE.md
See @AGENTS.md for base project rules, commands, and code style.
## Claude Code-specific
- Prefer editing existing files over creating new ones.
- Use the project's existing test runner; never invent a new one.
This keeps one primary source of truth (AGENTS.md) for every tool, while Claude Code still gets its extra features — imports, path-scoped rules, local overrides — through the thin CLAUDE.md layer on top.
Quick comparison table
| Dimension | AGENTS.md | CLAUDE.md |
|---|---|---|
| Origin | Sourcegraph, OpenAI, Google, Cursor, Factory — now Linux Foundation | Anthropic, built for Claude Code |
| Tool support | Codex, Cursor, Copilot, Gemini CLI, Aider, Windsurf, Zed, more | Claude Code (primary consumer) |
| Config hierarchy | Repo root + subdirectories | Managed / user / project / subdirectory / path-scoped |
| Imports | None | @import syntax |
| Path-scoped rules | No (subdirectory only) | Yes, via YAML frontmatter |
| Personal overrides | Not designed for this | CLAUDE.local.md (gitignored) |
| Adoption (2026) | 60,000+ GitHub repos | Widespread among Claude Code users (Next.js, LangChain, Excalidraw, etc.) |
FAQ
Do I need both files, or can I just pick one?
If your team only uses Claude Code, CLAUDE.md alone is fine. If your team mixes tools (Cursor, Copilot, Codex, etc.) or might in the future, AGENTS.md is the safer single source of truth, with a thin CLAUDE.md importing it for Claude-specific extras.
Will Claude Code break if I only have AGENTS.md and no CLAUDE.md?
It won't break, but it also won't read AGENTS.md automatically — Claude Code will simply have no project instructions at all unless you add a CLAUDE.md that imports or symlinks to it.
What happens if AGENTS.md and CLAUDE.md contradict each other?
Avoid this by design rather than relying on any specific precedence rule: keep universal rules in AGENTS.md only, and use CLAUDE.md exclusively for Claude-specific additions that don't overlap or conflict with it.
Is AGENTS.md likely to become the permanent universal standard?
Its trajectory points that way — Linux Foundation stewardship, 60,000+ repos, and support from essentially every major agent vendor except native Claude Code — but treat any single-vendor format as a moving target and check current docs before locking in a long-term setup.
Can I put secrets or personal preferences in these files?
Never put secrets in either — both are typically committed to version control. For personal
preferences that shouldn't be shared with the team, use CLAUDE.local.md, which is designed to
be gitignored.
Does having both files bloat the agent's context unnecessarily?
Not if you avoid duplication: keep AGENTS.md and CLAUDE.md non-overlapping (shared rules in one, Claude extras in the other via import) rather than repeating the same instructions in both files.
What exactly should go in AGENTS.md vs. CLAUDE.md?
AGENTS.md: code style, build/test/lint commands, project structure, architectural boundaries —
anything a human or any AI tool needs to know. CLAUDE.md: Claude Code-specific workflow preferences,
path-scoped rules for particular directories, and anything that uses Claude-only features like
@import.
Further reading:
No comments
Post a Comment