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.
The category carries a deliberately small weight of 4% in the overall health index. Agent tooling has become a real maintenance signal — but the weight is sized, together with the index's calibration curve, so that its absence never gates the top of the scale: a solid pre-AI-era project with zero AI Readiness signals can still reach 100/100. A project that invests in agent tooling earns a visible distinction and a few index points; one that does not is never pushed out of any band's reach by that fact alone.
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.
- At 4% of the raw weight — inside a calibration curve that saturates at raw 91 — AI Readiness can nudge the health index but can neither make nor break a rating: every band, including a 100/100, remains reachable with the category at zero.
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