An AI-legible repository makes its structure and intent easy for an assistant to discover. It has:
clear names
small focused modules
typed interfaces
current docs
reliable tests
standard commands
Important behavior is written down instead of living only in team memory.
In such a repository, an agent can find the owning module and inspect a nearby example. It can run one documented test command and understand what success means. Hidden setup and duplicate patterns force it to guess. Vague names and stale docs do the same.
Improve legibility by making boundaries explicit, removing dead code and documenting unusual decisions. Keep examples current. The goal is to make project knowledge visible and verifiable, which helps human developers too.
Rewriting in plainer words…
This answer doesn't lend itself to a diagram - it reads best . No credits were charged.
How can a test suite act as documentation for an agent?Tests show expected behavior on concrete inputs, and a fast, reliable run tells the agent if it succeeded. A flaky test gives a signal it can't trust.
Can a good CLAUDE.md make up for a hard-to-read codebase?It can document commands and unusual decisions, but it can't fix vague names or duplicate patterns, and it goes stale like any other doc.
If you could fix one thing in a messy repo before adding agents, what would it be and why?Commit to one and justify it. A single documented, reliable test command is a strong pick, since it lets the agent check its own work.
What you can say
An AI-legible repository is one where an assistant can work out the structure and the intent from the repo itself, instead of from what the team happens to remember.
In practice that means clear names, small focused modules, typed interfaces, current docs, reliable tests and standard commands.
So an agent can find the module that owns a change, look at a nearby example, run one documented test command and know what passing means.
Hidden setup, duplicate patterns, vague names and stale docs all do the opposite, because each one forces the agent to guess.
I'd improve it by making boundaries explicit, removing dead code, writing down unusual decisions and keeping examples current.
The catch is upkeep, since a stale doc or example misleads the agent, but the same work makes the repo easier for human developers too.
Weak answers to avoid
Reduces it to writing a CLAUDE.mdAn instruction file helps, but most legibility lives in the code itself: names, module boundaries, types and tests. Say what the agent can find and check in the repo.
Lists traits without saying why they helpTie each trait to what the agent does with it, like finding the owning module or knowing what a passing test means. A bare list sounds memorized.
Skips how the agent checks its workCode the agent can find is half of it. Without one documented test command and a clear success signal, the agent can't tell whether its change worked.
Treats it as work done only for the AIThe same fixes help new hires and reviewers. Saying so shows you'd justify the effort as normal maintenance the whole team benefits from.
Interview lens
Likely follow-ups, what you can say, and the weak answers to avoid.
