reviewing-agent-legibility

Can an AI agent read, navigate, and safely change this within a context budget? Context economy, retrieval-friendly structure, scoped AGENTS.md/CLAUDE.md.

When to use

Reviews a change for agent-legibility — whether an AI agent can understand, navigate, and safely modify this code within a context budget. The mirror of reviewing-ai-authored-code (quality of code for AI readers, not by them): context economy and self-containment (a depth-first slice understandable without loading the whole repo — the "40% context rule"), retrieval-friendly and AST-navigable structure, local self-explanation at the edit site, agent-onboarding files (AGENTS.md / CLAUDE.md) present, accurate, and scoped with do-not-touch guardrails, an llms.txt-style index for agent-consumed repos, and no agent-hostile patterns (context-budget-blowing megafiles, bloated scaffolding, duplicated parallel copies). Use when reviewing a change to an AI-/agent-maintained codebase, to agent-onboarding files or repo structure an agent must navigate, or any large or scattered change whose context economy matters. Defers human readability to #5–#8, agent-operator parity to #24, and runtime tool-safety to #32.

Shape: diff. Written for concrete code; not meant for design docs or plans.

Reviewer discipline

Report only real problems. If the code correctly handles the case, reply "No findings" and stop — do not invent issues. This guards against false positives on correct code; still report every genuine issue you do find, with its full detail.

Defects are the default; improvements are opt-in. By default this lens is defect-only: do not suggest changes to code that is already correct. When the team has opted up into improvement suggestions, a finding on already-correct code is admissible only as nit-severity, route: implementer (the author applies, defers, or ignores), and must clear the non-configurable anti-churn floor: it must genuinely improve — never offer a merely equivalent alternative — and must converge (once a dimension is as good as you can confidently make it, stop; never oscillate A→B then B→A, never re-order to an equivalent state). Defects keep the strict bar above regardless of this setting.

Team preferences. If the reviewed repo has .code-quality-atlas/preferences.md, apply it before reporting: a repo's .code-quality-atlas/preferences.md may set/tune this lens's thresholds or selection, and — being preference-tier — may suppress one of its findings outright (it never surfaces). Its improvement-valence directive is also what decides whether the "opted up" improvement-suggestion behavior above is active for this review. Absent the file, apply this lens's defaults exactly as written above.

Pre-existing defects in touched code are surfaceable, not yours to fix. When you notice a genuine defect this change did not introduce but that sits in the code this PR actually touches — the edited function or immediately adjacent lines — you may surface it, tagged "pre-existing — not introduced by this change." Like improvements it is opt-in and default-quiet (off unless the team opts up), route: implementer, and non-blocking: it informs the author's fix-now / file-a-ticket / ignore call and never sets this PR's verdict, because the diff did not cause it. Stay scoped to code the change touches — a repo-wide hunt is the audits' job, not this review — and never let it expand the PR's scope.