# AI Readiness

> The AI Readiness badge — how well a repository supports AI coding agents: agent context, verify loop, code legibility, machine-readable interfaces.


**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](/wiki/health-index), 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](/wiki/ai-verify-loop) | 40% |
| [AI agent context](/wiki/ai-agent-context) | 30% |
| [AI code legibility](/wiki/ai-code-legibility) | 15% |
| [AI interfaces](/wiki/ai-interfaces) | 15% |

The [verify loop](/wiki/ai-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](/wiki/ai-agent-context) covers instruction files
(`CLAUDE.md`, `AGENTS.md`, …) and machine-readable docs (`llms.txt`).
[Code legibility](/wiki/ai-code-legibility) measures type-checkability and
manageable file sizes. [Interfaces](/wiki/ai-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.md` or `AGENTS.md` and an `llms.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](/wiki/engineering-quality) ·
[methodology versions](/wiki/methodology-versions)