# AI code legibility

> How inspect.software measures code legibility for AI models — type-checkable code and manageable file sizes. Part of the AI Readiness badge.


**AI code legibility** measures whether a codebase is legible to a language
model: whether the code carries machine-checkable type information and
whether files fit comfortably in a model's working context. The same
properties that help a human navigate an unfamiliar codebase help a model —
but for models, oversized files are a hard constraint rather than an
annoyance.

- **Category:** [AI Readiness](/wiki/ai-readiness) (15% within category)
- **Weight in overall index:** 0% — part of the independent AI Readiness badge
- **Metric key:** `ai_code_legibility`
- **`null`** for repositories with no detectable source files — docs-only projects are not penalized

## How the value is computed

| Component | Weight | Criteria |
| --------- | ------ | -------- |
| Type-checkable code | 45 | statically typed language → 45 pts; dynamically typed with a type-check configuration → 27; neither → 0 |
| Manageable file sizes | 55 | `(1 − oversized / total) × 55`, where a source file over ~60 KB (~1,500 lines) counts as oversized; vendored and generated paths are excluded |

## Why these two signals

- **Types are compressed documentation.** A typed signature tells a model
  what a function accepts and returns without reading its body — and a
  type-checker turns the model's misunderstandings into immediate, mechanical
  errors instead of latent bugs. Partial credit for dynamically typed
  projects with a checker (mypy, pyright, tsconfig) reflects that gradual
  typing captures much of the benefit.
- **File size distribution** determines whether a model can hold a unit of
  code in context whole. A codebase of focused modules can be read
  piecewise; a 5,000-line file forces truncation, and truncation is where
  agent errors concentrate.

Vendored and generated code is excluded so that a committed `vendor/` tree or
generated bindings do not distort the measurement.

## Reading the result

- The metric reads structure, not style — naming, comments, and
  architecture are not graded (see the honesty rules in
  [AI Readiness](/wiki/ai-readiness)).
- The file-size component is proportional: one oversized file among fifty
  costs little; a codebase of monoliths reads accordingly.

## Improving the value

- Adopt a type checker; in dynamic languages, even a permissive initial
  configuration earns the partial credit and creates the ratchet.
- Split files approaching ~1,500 lines along their natural seams.
- Keep generated and vendored code in conventionally named paths so it is
  excluded from measurement.

Related: [AI verify loop](/wiki/ai-verify-loop) ·
[AI interfaces](/wiki/ai-interfaces)