Skip to content
RuleSellBeta
Sign up

Comparison

AGENTS.md vs CLAUDE.md (May 2026): Cross-Tool Format Decision

AGENTS.md wins for teams using 2+ tools — it's read by Codex, Cursor, opencode, Windsurf, Gemini CLI, Copilot, and 60k+ projects. CLAUDE.md wins for Claude-Code-exclusive teams that want Claude-specific features. Honest decision guide.

Who wins at what

Cross-tool portability
AGENTS.md
Claude-specific features (sub-agent hints, skill triggers)
CLAUDE.md
Standards-body backing
AGENTS.md (Linux Foundation AAIF)
Documentation depth
CLAUDE.md (HumanLayer, Boris Cherny, Karpathy)
Native support in Claude Code
CLAUDE.md
Native support in Codex/Cursor/opencode/Windsurf
AGENTS.md
Single source of truth for multi-tool teams
AGENTS.md
Hierarchical user/project/managed loading
CLAUDE.md

The Medium and DEV answer to "which should I use" is mealy: "use both." That's wrong for most teams. This page is opinionated and honest about which file wins at which job, with the explicit recommendation that most teams not currently using AGENTS.md should be.

Who wins at what

AGENTS.md wins on cross-tool portability, standards-body backing (Linux Foundation), and being the single source of truth for multi-tool teams. CLAUDE.md wins on Claude-specific features (sub-agent delegation hints, skill triggers, permission instructions), documentation depth from the Claude Code community (HumanLayer, Boris Cherny, Karpathy), native support in Claude Code, and hierarchical user/project/managed loading.

If you use only Claude Code, CLAUDE.md is fine. If you use anything else alongside it, AGENTS.md is the answer — and a tiny CLAUDE.md that points to AGENTS.md is the bridge.

What each one actually is

CLAUDE.md is Claude Code's repo-level context file. Claude reads it at session start and includes it in every prompt. It can layer: managed enterprise → user-global (~/.claude/CLAUDE.md) → project-root (./CLAUDE.md) → local override (./CLAUDE.local.md). Parent directories also contribute — Claude walks UP the tree. AGENTS.md is the tool-agnostic equivalent. Adopted by Codex CLI in August 2025 (OpenAI docs), standardized at agents.md, now stewarded by the Linux Foundation's Agentic AI Foundation (press release). Codex's loading model walks DOWN — root → cwd, layered.

Both want the same content roughly: project conventions, anchor files to read, rules the agent should follow, anti-patterns to avoid. The difference is who reads it.

Where AGENTS.md wins

Cross-tool portability. The full list of tools reading AGENTS.md as of May 2026: Codex CLI, Cursor, Gemini CLI, GitHub Copilot, opencode, Windsurf, Cline, RooCode, Kilo Code, Amp, Warp, Zed, Jules, Factory, Devin. Plus 60,000+ open-source projects per agents.md. If your team uses two or more of these tools, AGENTS.md is the only file you should be maintaining as the source of truth. Maintaining two is duplicate work that will drift. Standards-body backing. The Linux Foundation's Agentic AI Foundation (AAIF) was formed in December 2025 specifically to steward agentic-AI standards including AGENTS.md. This is the kind of institutional signal that matters for long-term betting. CLAUDE.md is a de facto Anthropic standard with no formal spec — and Anthropic hasn't published one. Single source of truth. The pattern that holds up in production: AGENTS.md is the authoritative file. CLAUDE.md is a 5-line pointer that says "see AGENTS.md" — or it's a symlink. This means your conventions, your anti-patterns, your anchor files are written once and consumed by every tool your team uses. The alternative — copy-paste between CLAUDE.md and AGENTS.md and .cursorrules and .windsurfrules — guarantees drift. Already what Karpathy uses for non-Claude-only projects. The cross-tool norm is real and growing. Watching it form on HN in real time: "Can't we standardize on AGENTS.md instead of all these specific CLAUDE.md..." — the frustration was the demand signal. The community delivered the standard.

Where CLAUDE.md wins

Native support in Claude Code. This is the load-bearing reason CLAUDE.md persists. Claude Code reads CLAUDE.md without configuration. AGENTS.md requires a workaround (symlink, or wait for GitHub issue #34235 to land). For teams that only use Claude Code, the workaround tax isn't worth it. Claude-specific features. CLAUDE.md can contain Claude-Code-specific instructions: sub-agent delegation hints ("for code review, dispatch the reviewer agent"), skill triggers ("when the user says X, run the Y skill"), permission instructions ("never run rm -rf without confirmation"). AGENTS.md is supposed to be tool-neutral — putting Claude-only directives in it violates the spirit of the standard. Hierarchical loading. CLAUDE.md's user/project/managed hierarchy is genuinely useful for enterprise. Managed enterprise settings live at /etc/claude/CLAUDE.md (or platform equivalent); user-global at ~/.claude/CLAUDE.md; project at ./CLAUDE.md; local at ./CLAUDE.local.md. Each layer overrides. AGENTS.md's model is simpler but less expressive for org-wide policy. Documentation depth. The CLAUDE.md ecosystem has more public writing: HumanLayer's writing-a-good-claude-md, Boris Cherny's annotated examples, Karpathy's 109k-star gist, josix/awesome-claude-md as a gallery, and the broader Claude Code community. AGENTS.md is younger; the canonical references are still being written. Skill triggers and the description budget. CLAUDE.md interacts with Claude Code's skill listing budget (1% of context window by default). Skills with strong descriptions in CLAUDE.md trigger correctly; vague descriptions get ignored. The pattern documented in Obra's debugging post is Claude-Code-specific and lives naturally in CLAUDE.md.

Where the comparison gets uncomfortable

The "use both" answer is technically right but operationally wrong. Two files mean two places to update, two places to forget to update, two sources of drift. The honest answer is one canonical file (AGENTS.md for multi-tool teams, CLAUDE.md for Claude-only teams) and a pointer/symlink for the other. HN's AGENTS.md eval thread is worth reading. "AGENTS.md outperforms skills in our agent evals" — counter-narrative to Anthropic's SKILL.md push. The author argues AGENTS.md beats triggered skills on some workflows because the agent doesn't have to guess when to load context. We treat this as one team's eval, not a generalization, but it's worth knowing the contrarian case exists. AGENTS.md being tool-neutral cuts both ways. It can't tell Claude Code "dispatch the reviewer subagent for this task" without referencing a Claude-Code-only concept. The practical workaround: keep AGENTS.md focused on universal conventions (style, anchor files, anti-patterns) and put tool-specific glue in CLAUDE.md or .cursor/rules/. This works but adds maintenance overhead — exactly the thing AGENTS.md was supposed to solve. Both files have a length problem. HumanLayer's 60-line standard is widely cited because it works — frontier models handle ~150-200 instructions reliably; beyond that, retrieval degrades. A 400-line CLAUDE.md isn't a feature; it's a smell. Whichever file you use, keep it under 100 lines and move detail into skills, conventions/, or docs/.

When to use both together (the working pattern)

The pattern most senior multi-tool teams converge on:

AGENTS.md       (50-line source of truth, tool-neutral conventions)
CLAUDE.md       (5-line "see AGENTS.md" pointer, or symlink)
.cursor/rules/  (stack-specific .mdc files for Cursor's MDC system)

Or even simpler:

AGENTS.md       (everything)
ln -s AGENTS.md CLAUDE.md

The skills/rules content travels separately. RuleSell's catalog tags every entry by which file format it targets — AGENTS.md sections, CLAUDE.md sections, SKILL.md skills, Cursor .mdc rules. Buy a convention pack once; deploy it where your tool reads it.

Where this comparison fails / what we don't know

We don't know when (or whether) Claude Code adds native AGENTS.md support. GitHub issue #34235 has been open with strong community interest; Anthropic has not committed. If/when it lands, the symlink workaround stops being needed and AGENTS.md becomes the default for most teams.

We also don't know how the multi-tool ecosystem fragments further. AGENTS.md is winning the standardization race for now, but new tools could ship with new file conventions (e.g., Roo Code's .roomodes, opencode's opencode.json instructions:). The "one file to rule them all" story is plausible but not guaranteed.

What to read next

Sources

Frequently asked

Can I use both AGENTS.md and CLAUDE.md?
Yes, and the cleanest pattern is AGENTS.md as the team-shared source of truth plus a tiny CLAUDE.md that says 'see AGENTS.md' (literally five lines). Never let them drift — duplicating content across files guarantees they will fall out of sync within weeks. The other working pattern: ln -s AGENTS.md CLAUDE.md, so Claude Code reads AGENTS.md directly. This is the symlink workaround documented in [GitHub issue #34235](https://github.com/anthropics/claude-code/issues/34235).
Does Claude Code read AGENTS.md natively yet?
Not as of May 2026. Claude Code reads CLAUDE.md only. The open feature request is [GitHub issue #34235](https://github.com/anthropics/claude-code/issues/34235) (also #6235). The symlink workaround is widely used. Anthropic has not committed to a timeline, though community pressure is real — every major alternative tool (Codex, Cursor, Gemini CLI, opencode, Windsurf, RooCode, Warp, Zed, Amp) now reads AGENTS.md natively.
Who maintains AGENTS.md?
The Linux Foundation's Agentic AI Foundation (AAIF), formed December 2025. Originally introduced by OpenAI Codex docs in August 2025, AGENTS.md was adopted as a cross-vendor standard within months. Founding members include OpenAI, Block, and Google — plus the original Goose team (donated by Block). Source: [Linux Foundation press release](https://www.linuxfoundation.org/press/linux-foundation-announces-the-formation-of-the-agentic-ai-foundation).
Which tools read AGENTS.md today?
Codex CLI, Cursor (since 2025-08), Gemini CLI, GitHub Copilot, opencode, Windsurf, Cline, RooCode, Kilo Code, Amp, Warp, Zed, Jules, Factory, Devin, Aider (via /read flag; native support tracked in [issue #4363](https://github.com/Aider-AI/aider/issues/4363)), and 60,000+ open-source projects per [agents.md](https://agents.md/). Claude Code is the notable holdout.
How long should AGENTS.md or CLAUDE.md be?
Under 60 lines, per the HumanLayer standard widely cited in the Claude Code ecosystem. Anthropic's own tip in [code.claude.com/docs/en/skills](https://code.claude.com/docs/en/skills) is similar for skills: 'Keep SKILL.md under 500 lines.' The rationale is the same — every line is a recurring token cost. Karpathy's CLAUDE.md (109k stars on the gist) is 4 lines. The 400-line CLAUDE.md is a smell.
What's the difference between AGENTS.md and SKILL.md?
AGENTS.md is repo-level always-loaded context — every conversation starts with it. SKILL.md is a triggered skill — Claude loads only the description into context at startup, the full body only when the skill matches the task. AGENTS.md is for 'this is how this codebase works' (rules, conventions, anchors). SKILL.md is for 'when the task is X, do Y' (procedure). They're complementary, not competing.

Related topics