← all checks

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.md and .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?

Pass rate by language

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

Popular repos that fail it

Every check, grouped into what to do first: how to make your repo ready for AI coding agents.