Agent-Readable Code

Research-informed principles for writing code that AI coding agents comprehend and modify correctly, plus an advisory linter that flags the most common anti-patterns.

Humans get lost in complexity. Agents get lost in indirection. Classical principles like SOLID and DRY were calibrated for human readers juggling cognitive load; several of them invert when the reader is an agent with a limited context window navigating by grep and file reads alone.

The underlying heuristic: write so that someone grepping a single file can act correctly without reading the rest of the repo.

A note on evidence: some of these practices are well-supported by controlled studies (naming, accurate documentation, verification loops). Others are operational heuristics whose direction is well-motivated but whose thresholds are tunable. The evidence strength for each rule is documented in references/research.md so you can apply judgment rather than follow rules blindly.

For longer before/after examples, see references/patterns.md. For the linter, see scripts/README.md.

The six practices

Each practice lists the failure mode it prevents, the pattern to apply, and the lint rule that detects violations.

1. Name for localization (AR003)