Agent Friendly Code
← all checks

AGENTS.md and CLAUDE.md: what they are and how many repos have one

AGENTS.md is a markdown file at the top of a repo, written for AI coding agents instead of people. It says 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 idea under the name Claude Code looks for.

How many repos pass

Of the 371 repos on the leaderboard, 184 pass in full (50%), 14 pass in part (4%) and 173 fail (47%).

Why agents need it

It is the one file most agents load without being asked. Claude Code loads CLAUDE.md at the start of every conversation. GPT-5 Codex reads AGENTS.md before it does any work. Cursor, Kimi CLI, OpenHands and Pi read AGENTS.md too. Without it, an agent has to work out your build steps and conventions by reading code, and it guesses.

How we score it

  • Full pass: AGENTS.md, CLAUDE.md or AGENT.md at the repo root with 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.
  • Fail: none of the three files is at the repo root.

The methodology has the formula that turns checks into a score.

How to pass

Add an AGENTS.md at the repo root. Cover what the project does, the directory layout, the exact setup, test and lint commands, and the conventions a reviewer would otherwise have to point out. If you already keep a CLAUDE.md, that passes as it is. Cursor rule files do not count here; they have their own check.

Which agents count it most

Pass rate by language

Top-scoring repos that pass

Popular repos that fail it