CLAUDE.md vs AGENTS.md: Which One Should You Pick for Your AI Repo?
60,000 repos use AGENTS.md. But CLAUDE.md dominates among Claude Code developers. Comparison, concrete examples, and a 2026 decision guide.
60,000 open source repositories now ship an AGENTS.md file at their root. Meanwhile, shanraisshan’s claude-code-best-practice repo has crossed 36,000 stars on GitHub in just a few weeks — powered by a single file: CLAUDE.md. And in December 2025, the Linux Foundation launched the Agentic AI Foundation (AAIF) to standardize all of this, with OpenAI, Anthropic, and Google at the table.
The message couldn’t be clearer: your most diligent “coworkers” on your codebase won’t be humans anymore. They’ll be AI agents. And a plain README no longer cuts it.
But between CLAUDE.md (powerful, Claude-specific) and AGENTS.md (open, universal), which one should you pick? Both? Neither? Here’s an honest comparison — with concrete examples and a strong opinion.
Why Your README Doesn’t Speak to AI Agents
When Andrej Karpathy announced in early 2026 that he had gone from 80% hand-written code to 80% agent-generated code, the dev world took notice. It’s no longer an edge case: according to Anthropic, developers using Claude Code spend 2 to 3 hours a day on average steering agents that read, edit, and test their code.
The catch? These agents don’t read your repo the way a human does. A developer joining a project opens the README, browses the file tree, reads a few key files, and builds a mental map. An AI agent has a limited context window — every file it reads burns tokens, and performance degrades past 60% capacity. It can’t “browse” — it needs to be told exactly what it needs to know.
A classic README explains what a project does. An AI context file explains how to work inside it: which commands to run, which patterns to follow, which files to never touch. It’s the difference between a tourist brochure and an operational briefing.
Columbia University researchers put it plainly in a March 2026 study: agents need to know “where things are, what rules to follow, and how to implement changes” — not a high-level summary of the project. READMEs speak to humans. Context files speak to machines.
CLAUDE.md: Claude Code’s Swiss Army Knife
CLAUDE.md is a Markdown file that Claude Code reads automatically at the start of every session. You put your build commands, code conventions, and workflow rules in there — everything Claude can’t infer from the code alone.
What Makes It Powerful
CLAUDE.md is tailor-made for Claude Code. It can tap into exclusive features: subagent delegation, permission levels, session management, direct references to Claude’s capabilities. That’s the upside of vendor lock-in — when you target a single tool, you can go much further.
The file also supports a directory hierarchy: a root CLAUDE.md for global rules, specific ones in /frontend or /api for local contexts. Claude automatically loads the closest file to the code it’s working on.
Another strength: the ecosystem. Skills (.skill files loaded on demand) keep your CLAUDE.md lean by offloading specific workflows. Hooks automate deterministic actions (lint after every edit, block commits on certain directories). And plugins add integrations in one click.
The andrej-karpathy-skills repo — a simple CLAUDE.md distilling four principles from Karpathy’s observations on recurring LLM failures — hit 17,000 stars. Proof that even a minimalist file can have outsized impact.
Where It Falls Short
Vendor lock-in. CLAUDE.md only serves Claude Code. If your team also uses Cursor, Copilot, Codex, or Gemini CLI, they all ignore it. You end up maintaining instructions in duplicate.
A tax on context. Every token in CLAUDE.md is a token you can’t use for your conversation. A bloated file measurably degrades performance — Anthropic recommends asking yourself: “If I delete this line, will Claude make mistakes?” If not, cut it.
The autogenerated trap. An ETH Zurich study (arxiv 2602.11988) on 138 repos showed that LLM-generated context files actually reduce agent success rates by 3% compared to… no file at all. Worse, they bump inference costs by 20%. Human-written files barely do better: +4% success. The takeaway is clear — a context file isn’t a README v2 you generate once and forget. It’s either a surgical tool, or it’s noise.
AGENTS.md: The Open Standard Unifying the Ecosystem
If CLAUDE.md is one vendor’s Swiss Army knife, AGENTS.md is the ISO standard everyone can read.
The Origins
Initially launched by Sourcegraph, AGENTS.md was quickly adopted across the industry. In December 2025, the Linux Foundation created the Agentic AI Foundation (AAIF) to oversee its governance, alongside two other founding projects: Anthropic’s Model Context Protocol (MCP) and Block’s goose.
AAIF platinum members? AWS, Anthropic, Bloomberg, Cloudflare, Google, Microsoft, and OpenAI. When your fiercest competitors sit at the same table around a standard, the topic is serious.
Who Supports It
The list keeps growing: GitHub Copilot, OpenAI Codex, Google Jules, Cursor, Gemini CLI, Amp, Factory, RooCode, Zed, Warp — and more. One notable absence: Claude Code, which doesn’t read AGENTS.md natively (despite community demand). It’s the irony of the decade: Anthropic is an AAIF platinum member, but its flagship tool doesn’t yet support the standard it co-governs.
What Actually Belongs in It
GitHub’s analysis of 2,500 repositories identified the 6 sections that move the needle:
- Commands — build, test, lint (with exact flags)
- Project structure — main modules, entry points
- Code style — one concrete example beats 3 paragraphs of description
- Git workflow — branches, commit conventions, PR process
- Tech stack — specific versions, not just “a React project”
- Boundaries — what the agent should never touch (secrets, prod configs, vendor)
The golden rule? Short and precise. OpenAI recommends a maximum of 100 lines. The ETH Zurich study confirms it: overlong files add noise that makes tasks harder for the agent. Five targeted lines consistently beat 2,000 generic words.
The Match: CLAUDE.md vs AGENTS.md in 2026
Here’s the factual comparison:
| Criterion | CLAUDE.md | AGENTS.md |
|---|---|---|
| Supported tools | Claude Code only | Copilot, Codex, Jules, Cursor, Gemini CLI, Zed, Warp… |
| Governance | Anthropic | Linux Foundation (AAIF) |
| Specific features | Skills, hooks, subagents, permissions | Plain Markdown, no special features |
| File hierarchy | Yes (root + subfolders) | Yes (root + subfolders) |
| Adoption | ~37k stars (best-practice repo) | 60,000+ repos |
| Portability | None | Full |
| Precision | Maximum (single-tool targeting) | Good (common denominator) |
When to Use What
AGENTS.md alone — you work in a team with mixed tools (Copilot + Cursor + Claude), or you maintain an open source project. It’s the right default. One file, every agent reads it.
CLAUDE.md alone — you’re solo, all-in on Claude Code, and you leverage skills, hooks, and subagents. No need for portability.
Both — this is the most robust setup for a serious project. AGENTS.md for universal instructions (commands, stack, boundaries). CLAUDE.md for Claude-specific pieces (skills to load, subagent workflows, @ imports to other files). Migration is trivial:
# Starting from CLAUDE.md and want to add AGENTS.md
cp CLAUDE.md AGENTS.md # Copy the baseline
# Then edit CLAUDE.md to keep only Claude-specific bitsMy Take
AGENTS.md should be the default file for every new repo. It’s the agent README — universal, lightweight, sufficient for 90% of cases. CLAUDE.md becomes a complement for teams pushing Claude Code to its limits, not a replacement.
The logic mirrors web standards: you write standard HTML, then add vendor-prefixed CSS when you want to go further on a specific browser. AGENTS.md is the standard. CLAUDE.md is the vendor prefix.
Starter Kit: Prep Your Repo in 10 Minutes
Minimal AGENTS.md Template
# AGENTS.md
## Stack
TypeScript 5.7, Next.js 15, PostgreSQL 16, pnpm
## Commands
- Install: `pnpm install`
- Dev: `pnpm dev`
- Test: `pnpm test -- --watch`
- Lint: `pnpm lint --fix`
- Build: `pnpm build`
## Code style
- ES modules, named exports
- Prefer `async/await` over `.then()`
- Example: see `src/lib/utils.ts` for patterns
## Git
- Branch: `feat/<description>`, `fix/<description>`
- Commits: conventional commits (`feat:`, `fix:`, `docs:`)
- Always run tests before committing
## Boundaries
- NEVER modify `.env*`, `prisma/migrations/`, or `public/`
- NEVER commit secrets or API keysComplementary CLAUDE.md Template
# CLAUDE.md
See @AGENTS.md for build commands and conventions.
## Claude-specific
- Use subagents for code review after implementation
- Run /compact after completing each feature
- When debugging, read error logs before exploring code
## Skills
- @.claude/skills/fix-issue/SKILL.md — GitHub issues workflow
- @.claude/skills/deploy/SKILL.md — deployment checklistThe 3 Mistakes That Ruin a Context File
-
The wall of text. A 500-line file that the agent ignores 60% of. Start with 20 lines. Only add what corrects a recurring behavior.
-
The “generate and forget” file.
/initcreates a skeleton, but it must be refined by hand. Autogenerated files degrade performance per ETH Zurich. -
Stating the obvious. If Claude already follows a convention without being told, the line is dead weight. Every instruction should correct a deviation, not confirm a default behavior.
Frequently Asked Questions
Will Claude Code support AGENTS.md?
Probably. Anthropic is a platinum member of the AAIF that governs the standard, and the community is actively pushing for it. In the meantime, Claude Code reads CLAUDE.md files at the root — you can import your AGENTS.md into it with the @AGENTS.md syntax.
Can a context file replace good documentation?
No. Context files are operational briefings, not documentation. They tell the agent how to work inside the code, not what the project does. A solid README is still essential for humans — and agents read it too when they need to understand the “why”.
How many lines for an effective context file?
As few as possible. OpenAI recommends a 100-line maximum for AGENTS.md. Anthropic says that if your CLAUDE.md is too long, Claude ignores half of it. The sweet spot sits between 20 and 80 lines — enough to cover commands, style, and boundaries, not enough to drown the agent.
Key takeaways:
- AGENTS.md is the new standard — governed by the Linux Foundation, supported by 15+ tools, adopted by 60,000 repos. It’s the right default for any project.
- CLAUDE.md still matters — but as a Claude Code-specific complement, not as a standalone file. Use it for skills, hooks, and Claude-specific workflows.
- Less is more — 20 targeted lines beat 500 generic ones. Every line should correct real behavior, not describe the obvious. The ETH Zurich research confirms it: overlong files make agents less effective.
If you want to dig deeper into how MCP connects every AI agent, that article pairs perfectly with this one.
