agent-readable-code
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.