AI Readiness measures how well a repository is equipped to be developed and maintained with AI coding agents: whether an agent arriving in the codebase finds guidance, can set up and verify its own changes, can read the code within model constraints, and can discover machine-readable interfaces.
It is an independent, additive badge. The category carries weight 0.0 in the overall health index — computed and displayed on its own, it never changes the health number. A solid pre-AI-era project is not marked down for lacking agent tooling; a project that invests in it earns a visible, separate distinction.
Metrics in this category
| Metric | Weight in category |
|---|---|
| AI verify loop | 40% |
| AI agent context | 30% |
| AI code legibility | 15% |
| AI interfaces | 15% |
The verify loop carries the heaviest weight because it is the crux of autonomous work: an agent that can bootstrap the project, run the tests, and check its own change is categorically more useful than one that cannot. Agent context covers instruction files (CLAUDE.md, AGENTS.md, …) and machine-readable docs (llms.txt). Code legibility measures type-checkability and manageable file sizes. Interfaces looks for API schemas, MCP servers, and runnable examples.
Measurement honesty
Signals are presence- and size-based heuristics from the file tree — no file contents are graded. They show that the infrastructure exists, not how good it is. Substance is weighted where it is cheap to detect: an instruction file below ~200 bytes registers as a stub and earns partial credit, a specific defense against gaming the badge.
Metrics that do not apply produce null, never a penalty: a docs-only repository is not judged on code legibility, and a plain library with no API surface is not judged on interface schemas.
Reading the badge
- The badge answers a genuinely new procurement question — can a team point agents at this codebase productively? — that the classic health signals were never designed to capture.
- Because the weight is 0.0, comparisons of the health index across repositories are unaffected by AI Readiness entirely.
Improving AI Readiness
- Add a substantive
CLAUDE.mdorAGENTS.mdand anllms.txt. - Provide a one-command bootstrap (Makefile, justfile, …), automated tests, lint config, and type checking — the verify loop.
- Keep source files below ~1,500 lines and adopt type checking.
- Ship OpenAPI/GraphQL/protobuf schemas, an MCP server, or runnable examples where they fit the project's nature.
Related: engineering quality · methodology versions