Make Your Code AI-Ready

For as long as I've written software, my code was written for the next engineer to read it. That reader is being replaced. The most important reader of your codebase is now an agent — it reads everything, remembers none of your hallway context, and can't lean over and ask what you meant. Making a codebase AI-ready is one thing: making it legible to that reader. And legibility is concrete, a handful of unglamorous chores you already know how to do.

Start with context, because the agent's whole briefing is what you wrote down. It never sat in the planning meeting. So the .MD files matter more than ever — a current README, a CLAUDE.md that says how the project is laid out and how to run it. Stale docs are worse than none: they send a confident machine confidently in the wrong direction.

Then delete your dead code. A human skims past the abandoned function; an agent can't tell dead from live. It reads every path as real, follows the branch nobody calls anymore, and burns turns going in circles around code that does nothing. The "just in case" helper you kept is a false lead you left lying around for a machine with no way to know it's a dead end.

Watch complexity, and don't overthink the metric — file size is a fine proxy you can act on today. A two-thousand-line file doesn't fit in the agent's head any better than yours, so it edits blind and breaks something three functions up that it never saw. Split the monster file into pieces small enough to hold whole.

And do the thing everyone defers: raise coverage and fix flaky tests. Tests are the agent's ground truth — a change with no test is one it can't verify. But a flaky test is worse than a missing one. It lies: the agent chases a failure that isn't real, or trusts a green that wasn't earned, poisoning the feedback loop it uses to correct itself.

None of this is new — write the docs, kill dead code, keep files small, keep tests honest. What changed is the price of neglect. On a new project these are nearly free: choose your constraints on day one and pick the language whose compiler is the strictest reviewer you'll ever have, which is the case for Rust in the agent era. On an old one you pay it back in renovation, one seam at a time, right where you're already working.

So treat legibility as a feature, not a chore. Write the map. Delete the dead code. Split the file you dread opening. Fix the flaky test instead of retrying it. The best codebases were always the ones a newcomer could read — the newcomer is just a machine now.