AGENTS.md and CLAUDE.md: what they are and how many repos have one
AGENTS.md is a markdown file at the repo root written for AI coding agents: what the project is, how it is laid out, which commands build and test it, and which rules to follow. CLAUDE.md is the same file under Claude Code's name.
How many repos have an AGENTS.md?
Of the 401 repos on the leaderboard, 206 pass in full (51%), 16 pass in part (4%) and 179 fail (45%).
Why do AI coding agents need an AGENTS.md?
It is the one file most agents load unasked. Claude Code loads CLAUDE.md at the start of every session, or AGENTS.md when there is no CLAUDE.md. Codex reads AGENTS.md before any work, and Cursor, Devin, Kimi Code CLI, OpenHands and Pi read it too. Without it, an agent guesses your build steps and conventions from the code.
What should I put in an AGENTS.md?
Whatever an agent can't work out from the code, kept short enough to read in full every session:
- What the project is. A sentence or two, plus languages, frameworks and package manager (
pnpm, not npm;uv, not pip). - Exact commands. Setup, build, test, lint and type check, copy-pasteable with flags. Include how to run one test file; an agent runs that most.
- Where things are. Only what a directory listing doesn't say: where generated code and fixtures live, which package is the entry point.
- Rules a reviewer would repeat. Conventions the linter doesn't enforce: naming, error handling, which module owns database access.
- Boundaries. What never to touch (generated files, lockfiles, secrets) and what to ask about first (migrations, new dependencies).
- When a change is done. The checks that must pass first, usually the ones CI runs.
What to leave out
- Style rules a linter or formatter already enforces.
- A full file tree: it goes stale, and the agent can list the directory.
- Secrets, tokens or internal URLs: the file is committed.
- Long how-tos for one part of the code. Link a doc, or put an AGENTS.md in that directory.
The median of the 222 on the leaderboard is 6,888 characters. Read them.
What makes a good AGENTS.md?
- Full pass: the first with content of AGENTS.md, CLAUDE.md and AGENT.md at the repo root, then
.claude/CLAUDE.mdand.claude/AGENTS.md, has 800 or more characters. - 80%: the file has 200 to 799 characters.
- 50%: the file has under 200 characters.
- 20%: the file exists but is empty, as is any other of the five.
- Fail: none of the five files exists.
How checks become a score: methodology.
How do I add an AGENTS.md to my repo?
Add an AGENTS.md at the repo root with the contents above. An existing CLAUDE.md passes as it is, but when a repo has both, Claude Code reads only CLAUDE.md unless it starts with @AGENTS.md. Cursor rule files have their own check.
Which AI agents read AGENTS.md?
- Pi13% of its score
- Kimi Code CLI13% of its score
- Claude Code13% of its score
- Codex11% of its score
- Cursor9% of its score
- Gemini CLI8% of its score
- Devin7% of its score
- OpenHands5% of its score
- Aider4% of its score
Pass rate by language
- TypeScript57 of 82 (70%)
- Java19 of 28 (68%)
- Ruby6 of 10 (60%)
- Clojure3 of 5 (60%)
- PHP7 of 12 (58%)
- JavaScript8 of 15 (53%)
- Go21 of 40 (53%)
- Rust23 of 45 (51%)
- Kotlin6 of 12 (50%)
- Scala3 of 6 (50%)
- Zig3 of 6 (50%)
- C++10 of 21 (48%)
- Python26 of 56 (46%)
- Swift3 of 10 (30%)
- C2 of 10 (20%)
- Dart1 of 7 (14%)
- Elixir1 of 7 (14%)
- Haskell1 of 7 (14%)
- C#1 of 8 (13%)
AGENTS.md examples: every one on the leaderboard, linked to its source. AGENTS.md vs CLAUDE.md: which to use. State of AGENTS.md adoption: how many repos have one, over time.
Top-scoring repos that pass
- Rust · 6.8k ★
- Ruby · 48.1k ★
- pingcap/tidb89.6Go · 40.7k ★
- gitlab-org/cli88.8Go · 1.1k ★
- apache/superset88.7Python · 75.4k ★
- axios/axios88.1JavaScript · 109.3k ★
- aio-libs/aiohttp88.1Python · 16.6k ★
- PostHog/posthog88.0Python · 40.7k ★
- C++ · 133.6k ★
- Python · 46.3k ★
- Rust · 33.3k ★
- TypeScript · 115 ★
Popular repos that fail it
- flutter/flutter55.0Dart · 181.1k ★
- Python · 165.3k ★
- Svelte · 158k ★
- golang/go29.9Go · 139.8k ★
- openai/codex60.2Rust · 133.5k ★
- shadcn-ui/ui61.9TypeScript · 127.6k ★
- C++ · 119.7k ★
- tauri-apps/tauri65.7Rust · 112.6k ★
Every check, grouped into what to do first: how to make your repo ready for AI coding agents.