Who it's for
Engineering leaders deciding whether a codebase is ready for AI agents.
You'll be able to
Score a codebase in five areas, and read the score without fooling yourself.
Agents do best in a codebase that tells them what is right. A readiness score asks whether yours does, and gives a reason for every point it takes away.
Five areas, a reason for every lost point
A readiness score reads a repository and prints a number out of 100. It is advice. It changes nothing in the code it reads, and it is not part of the gate. Each area is worth 20 points.
| Area | What it looks for |
|---|---|
| Setup works | The install check is green in CI, an example settings file exists, every dependency list has a lock file |
| Tests can be trusted | Tests exist, they pass, unit tests run within a time limit, coverage of changed lines is reported |
| Rules are written | The agents' rules file is short, guides exist, lint and format settings exist |
| Docs exist | An architecture page, a developer guide and a user guide, each written over its template |
| Safety | The secret scan and package audit are required, control files have a named owner, the main branch is protected |
Every check answers pass, fail or unknown. A fail always comes with a reason, so the score is also a to-do list.
An example score for an imaginary codebase, 75 out of 100. Each area is worth 20 points.
- Setup works: 20 out of 20.
- Tests can be trusted: 15 out of 20. 5 points lost: Coverage of changed lines is not reported.
- Rules are written: 13 out of 20. 7 points lost: The agents' rules file is too long.
- Docs exist: 7 out of 20. 7 points lost: The developer guide is still its template. 6 points lost: There is no user guide.
- Safety: 20 out of 20. One check is unknown: No rights to ask the code host whether the main branch is protected. It costs nothing.
A number on its own tells you little. The reasons behind each lost point tell you what to fix next.
Unknown is not the same as fail
Some things the score can't read. It may have no rights to ask the code host whether the main branch is protected. A test run may time out. Then the check is unknown: it costs nothing and adds nothing.
If every check in an area is unknown, that area is left out. So a score can read 72 out of 80, not out of 100. Those are two different measures. Before you compare two scores, read the unknown lines.
Running someone else's tests runs their code
Two checks need the tests to run. Running a repository's tests runs its code. So for any repository other than your own, the tests run only when you ask. Ask only for a repository you trust.
The time limit for unit tests was measured on one machine. On a slower machine the check can fail with nothing wrong. Set the limit for your own machines.
Try it
Take one repository your team wants agents to work in. Go through the five areas as a list, and for each check write pass, fail or unknown, with one line of reason.
- Fix the cheapest fail first.
- Turn each unknown into a pass or a fail, by finding out.
- Do it again in a month, and compare the reasons, not just the number.