Your agent is only as good as your repo

A pattern from this year's consulting-adjacent inbox: team tries coding agent, agent flails, team concludes the model is overhyped. Then you look at the repo. No README that matches reality, tests that fail on main, build steps that live in one engineer's shell history, and a directory named utils2. The agent didn't fail the codebase. The codebase failed its onboarding.

The cleanest statement of this I have read is why AI tooling rewards a well-kept repo, which frames the payoff structurally: assistants multiply the quality of the context you hand them, so the prep work you always owed your human hires suddenly pays out on every model call too. Same thesis, my numbers: on a well-groomed repo I watch agents one-shot changes that take three retries on a messy one. The model is identical. The substrate moved.

The checklist I run before blaming any model, in order of payoff per hour spent:

Make main build and test clean, from one documented command. An agent, like a contractor, will run your tests to check its own work; if the suite was already red, you have removed its only feedback loop and yours.

Write the CLAUDE.md / agents file honestly: how to build, how to test, where things live, what not to touch. Twenty minutes. It is a system prompt for your repo, and the same rules apply: stable, specific, no folklore.

Delete the dead code. Agents read utils2 with the same confidence as utils; every abandoned path is a trap you set for a reader who trusts you. (Humans fell in it too. They just stopped telling you.)

Name things what they are. The agent navigates by grep and embedding, which means your naming is its map. handleData2 is a lie in both directions.

The punchline the essay gets right and teams keep missing: none of this is AI work. It is the hygiene your team deferred, now carrying a measurable exchange rate. The agent just printed the invoice.