# 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.

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](/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.
- 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.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)