A repo an agent can actually work in, and the choices that decide it

Give an agent the same task in two codebases and the results diverge sharply. In one it locates the right file, follows the conventions and produces something that fits. In the other it invents a new pattern, misses a required step and edits the wrong layer.

What separates them is not size or complexity. It is whether the codebase explains itself to a reader who arrives with no history — which is also what makes it workable for a new colleague, or for you in a year.

The useful framing: an agent is a capable reader with no memory. Everything that helps such a reader helps it, and nothing else does.

The single highest-return change in most codebases is naming. Files, functions and directories whose names state their responsibility mean the right location is found by reading a listing rather than by opening things.

Specifically:

• No abbreviations that are not universal in the domain.
• Directory names that describe responsibility, not layer — billing/ beats services/.
• Consistent verbs for consistent operations. If it is fetch in one place it is not get in another.

This is unglamorous and it does more than any amount of documentation, because it cannot go stale.

Where a codebase has three approaches to the same problem — three ways of handling errors, two patterns for data access, several test styles — a reader cannot tell which is current. It will follow whichever it encountered, which is often the oldest.

Pick one for each and migrate deliberately. Where migration is incomplete, say so explicitly in the project instructions: which pattern is current, which is legacy, and that new code follows the first.

The cost of inconsistency is paid on every task, by every reader, indefinitely. It is one of the few things worth stopping feature work to fix.

Every mature codebase has deliberate strangeness: a workaround for a platform bug, an ordering that matters for a non-obvious reason, a duplication that exists because the alternative broke something.

To a reader with no history these look like defects, and a capable reader will fix them.

Mark them where they are, briefly and specifically:

# Deliberate: must run before the config load,
# otherwise the cache initialises with stale paths.
# Do not reorder.

The comment needs the reason, not just the instruction. 'Do not change' invites a change the moment someone believes they understand better.

The most valuable thing a repository can offer a working agent is a way to find out whether a change is correct — a test suite, a type check, a build — that runs quickly and fails clearly.

With one, work becomes iterative: change, check, correct. Without one, everything is submitted on the basis of it looking right, and the errors surface later.

Speed matters as much as coverage here. A suite taking ten minutes will not be run between changes; one taking ten seconds will be run constantly. If yours is slow, a fast subset that covers the common paths is worth more than complete coverage nobody waits for.

Do not document the directory layout, the dependency list or the general architecture. All of it is visible, and written down it goes stale and becomes actively misleading.

Document the reasoning: why this approach rather than the obvious alternative, what was tried and rejected, what constraint from outside the code shapes a decision.

That is the category no reader can reconstruct, and it is what turns a codebase from something an agent can edit into something it can be trusted in.