Agent Friendly Code

How to make your codebase agent-friendly for AI agents

An agent-friendly codebase writes down what the code doesn't say and gives the agent a way to check its work: an AGENTS.md with your exact commands, tests it can run, and CI and lint config that show what a change must pass.

Of 401 popular repos on our leaderboard, 55% have an AGENTS.md or CLAUDE.md (how that has grown), 52% pass our tests check and 96% our CI check. Below are the 17 checks we score, grouped by what they do for an agent; the 3 marked count most across agents.

Tell the agent what it can't read from the code

An agent starts every session knowing nothing. These files are what it reads first.

  • AGENTS.md / CLAUDE.mdstart hereWrite an AGENTS.md: exact commands, rules a reviewer would repeat, what never to touch.55% of repos have one
  • READMESay what the project does, how to install it and where the main code lives.96% of repos pass
  • CONTRIBUTING guideWrite down branch, commit and review rules; link it from AGENTS.md.86% of repos pass
  • License fileAdd a LICENSE file at the root, so it's clear what the code may be used for.92% of repos pass

Let it check its own work

An agent that can run the checks fixes its own mistakes before you see them.

  • Test suitestart hereKeep tests in a conventional directory, and put the command that runs one file in AGENTS.md.52% of repos pass
  • CI configurationDefine CI in the repo, so the agent can see and run what a change must pass.96% of repos pass
  • Linter / formatter configCommit the linter config, so style is checked rather than copied from nearby files.65% of repos pass
  • Type configurationCommit a type-checker config: a wrong argument fails before the tests run.68% of repos pass
  • Pre-commit / git hooksRun the formatter and linter on commit, so problems show in seconds, not after CI.29% of repos pass

Make setup one command

Cloud agents start in a fresh machine and must install everything before they can run a test.

  • Dependency manifeststart hereCommit the manifest and its lockfile, so the agent installs the versions you do.92% of repos pass
  • Reproducible dev envAdd a Makefile or justfile with setup, test and lint targets, and a devcontainer or Dockerfile.22% of repos pass
  • .openhands/setup.shFor OpenHands: put the one-time install steps in .openhands/setup.sh.0.5% of repos have one

Add the files your agents read

AGENTS.md reaches most agents. A few read their own file, or need one to find AGENTS.md.

  • Cursor rules (.cursor/rules)For Cursor: scoped rules in .cursor/rules/*.mdc.5% of repos have one
  • GEMINI.mdFor Gemini CLI: a GEMINI.md, which can be a single @AGENTS.md line.2% of repos have one
  • .aider.conf.ymlFor Aider: .aider.conf.yml with your test and lint commands, reading AGENTS.md.0.2% of repos have one
  • Skills (.agents/skills)Move long, task-specific steps out of AGENTS.md into .agents/skills/.17% of repos have one

Point it at the right code

Size isn't something to fix, but a large repo needs directions.

  • Manageable sizeName the entry points in AGENTS.md, and give each monorepo package its own.16% of repos pass

Which file does my agent read?

How ready is my repo?

AGENTS.md examples to copy

All 221 on the leaderboard, or by language and framework:

Shares are of the 401 leaderboard repos; empty files don't count. How each agent weighs the checks: methodology.