Your codebase was written for humans.
Agents noticed.
God files, tribal knowledge, missing docs, no guardrails — humans route around these every day. AI agents can't. Making your code agent-ready is the highest-leverage engineering investment of the next five years.
$ agent --audit .
scanning 1,284 files …
✓ tests present — agents can verify their own work
✓ CLAUDE.md found — context loads before code
⚠ 14 files > 800 lines — context windows suffer
⚠ 3 modules only Dave understands
✗ README last touched 2 years ago
readiness: AGENTS SURVIVE — could be so much more
// 01
What agent-legible code looks like
None of it is exotic. It's engineering hygiene with a new payoff attached.
Small, well-named files
A 2,000-line god file defeats an agent the same way it defeats a new hire — except the agent won't tap a shoulder to ask. Files that do one nameable thing are files agents navigate correctly on the first try.
Docs that state intent
Agents read fast and believe what they read. Documentation that says why — constraints, invariants, the bug that forced the weird design — turns an agent from a guesser into a collaborator.
Guardrails that catch mistakes
Linters, type checks, tests, CI. Every automated check you have is a mistake an agent can catch in itself before you ever see the diff. No guardrails means you're the guardrail.
Context files that orient
CLAUDE.md, AGENTS.md, and friends are the difference between an agent that knows your conventions and one that confidently invents its own. Cheap to write, compounding returns.
The 30-minute upgrade: a real context file
This is the whole trick. State what the repo is, the conventions that matter, the landmines, and how to verify work. An agent reading this file skips a hundred wrong guesses — so does the engineer who joins next month.
# payments-service Rails service handling checkout + refunds. All money amounts are integer cents — never floats. ## Conventions - Service objects in app/services, one public `call` method - Feature flags via `Flipper`, never env vars - DO NOT touch app/legacy/* — scheduled for deletion, has no tests, breaks silently ## Verify your work - bin/rspec spec/services — must stay green - bin/rubocop — zero new offenses
// 02
Why it pays twice
Every change that helps agents navigate your code helps your human engineers too. Smaller files review faster. Intent-stating docs onboard people quicker. Guardrails catch everyone's mistakes. Agent-readiness work is the refactoring you should have done anyway — the difference is now it has a multiplier attached.
// 03
Where to start: don't boil the repo
- [1]
measure
Point an agent at a real task and watch where it struggles. Those friction points are your blockers — not a rewrite wishlist, a ranked queue.
- [2]
fix the top blockers
Split the god files agents keep misreading. Write the context file. Turn tribal knowledge into text. Highest-leverage items first, nothing speculative.
- [3]
re-measure
Same tasks, same agent, new score. Keep what moved the needle, drop what didn't, repeat. Agent-readiness is a loop, not a project.
I help engineering teams run exactly that loop — assessment, prioritized fixes, and the habits to keep the score climbing after I'm gone.
$ make agent-ready