When people picture adopting agentic tooling, they picture a capability problem: pick the most capable model, wire up the most advanced orchestration, and the quality of the work follows from the power of the tool. So the instinct is to start at the top of the capability ladder and point it at whatever codebase they happen to have.
That instinct gets the relationship backwards. An agent doesn't bring order to your project. It works inside the order that's already there, or inside the disorder that's already there. Point a capable agent at a clean, well-understood, well-tested codebase and it tends to do good work quickly. Point the same agent at a tangled codebase with no tests, no written conventions, and no review discipline, and it tends to produce more of that tangle, faster, with great confidence.
Don't automate a broken system
The mistake of trying to automate a broken system is nothing new. Long before any of this was built into agentic tooling, Bill Gates wrote in Business @ the Speed of Thought that automation applied to an efficient operation magnifies the efficiency, and automation applied to an inefficient operation magnifies the inefficiency.
A power tool works the same way. A circular saw doesn't have an opinion about your work. Hand it to someone who has measured twice, clamped the board, and marked a clean line, and it makes a fast, straight cut. Hand it to someone working from a rough guess on an unclamped board, and it makes a fast, ruined cut. The saw did not cause either outcome. It magnified the setup it was given, and it did so faster than a hand saw ever could. The speed is exactly why the setup matters more, not less.
If an agent is automation pointed at your development process, it won't put in place what's missing or fix what's broken. It only magnifies what's already there. So the right question isn't "what is the most capable agent I can run." It's "what does my project need to have in place so that a capable agent magnifies good work instead of bad."
What goes wrong when you skip ahead
The reason this mistake is so easy to make is that skipping the foundation feels fine at first. The early results look fast. The cost shows up later, and it shows up somewhere you weren't watching.
Generally speaking, the failure modes fall into a few buckets, and the research and the field reports point at the same ones:
- The work outruns your ability to check it. An agent can produce changes far faster than a person can read and understand them. Without automated tests and a real review habit, "it looks done" becomes the only signal you have, and "looks done" isn't the same as "is correct." Anthropic's own guidance for working with agentic coding tools makes this point directly: if the agent has no way to verify its work, you become the verification loop, by hand, forever.
- The codebase fills up with code nobody understands. Addy Osmani has called it comprehension debt - the growing gap between how much code exists in your system and how much of it any human on the team genuinely understands. Ordinary technical debt hurts while comprehension debt stays invisible until the day you need to change something and discover that no one can explain why it works.
- Review turns into rubber-stamping. When the volume of generated code climbs and the review capacity stays flat, something has to give, and what gives is the depth of the review. There is good evidence that people reviewing the output of a reliable-seeming automation catch far fewer of its mistakes than they would catch reviewing a peer, precisely because it usually looks right. Approval stops meaning "a human understood this" and starts meaning "a human glanced at this."
- The process you automated was the problem. If decisions live only in people's heads, if there's no agreed convention, if "how we do things here" is an oral tradition, an agent has nothing to follow and will invent its own answer every time. You haven't removed the ambiguity. You've handed it to something that resolves it confidently and inconsistently, at scale.
None of these show up in week one. They show up in month six as a slow rise in debugging time, a slow erosion of trust in the test suite, and a codebase that's hard to change. The 2025 DORA research on AI-assisted development lands on a useful way to say this: AI acts as an amplifier. For teams with solid foundations it accelerates results. For teams with dysfunctional ones it magnifies the dysfunction. The tooling did not decide which team you are. The foundation did.
The foundation, in plain terms
Here's the part that should be reassuring: The foundation is nothing new. It's the set of practices that make software healthy whether or not an agent ever touches it. Agents don't need a new discipline so much as they need the discipline we've always said mattered, now made real instead of aspirational. The difference is that agents raise the stakes - a weak foundation that a careful human team could paper over becomes a weak foundation that a fast agent will expose.
These apply to any human or agent working in your codebase, which is part of why they're worth doing regardless. In rough order of how much they matter:
- A verification loop the agent can run on its own. This is the first step, and the most important. Automated tests, a build that passes or fails, a linter, a type checker - anything that gives a clear, fast, objective signal of "this is correct" or "this is broken." Tests are what let an agent check itself instead of guessing, and they're what let you reverse a bad change with confidence. If you do one thing before adopting agents, add a robust set of verification loops.
- A codebase an agent can hold in its head. Clear module boundaries, low coupling, readable code, and a manageable size for any given task. An agent works from a sliced, partial view of a large codebase - it can't see all of it at once - and when it can't see something it needs, it tends to fill the gap with a confident guess rather than go find the truth. Clean boundaries shrink how much the agent has to guess. A tangled codebase widens it.
- Small, reviewable units of work. Small commits, small pull requests, one focused change at a time. Large, sprawling changes are hard for a person to review no matter who wrote them, and the evidence on agent-authored pull requests is consistent: the bigger the change, the less likely it is to be understood, reviewed, and merged. Small units keep reviews honest and keep a bad change easy to back out.
- Written context the agent can read. This is where the agent-specifics come in - a CLAUDE.md, an AGENTS.md, a rules file - documenting the things an agent can't infer from the code itself. Keep it small and specific: the build and test commands, the conventions that differ from the defaults, the handful of "never do this here" guardrails. The goal isn't to write the agent a novel. It's to tell it the non-obvious things a new teammate would have to be told, and nothing it could figure out by reading the code.
- The "why" written down, not only the "what." Code shows what you did. It almost never shows why you chose it over the alternative you rejected. Michael Nygard's architecture decision records were invented to solve this for human newcomers, who would otherwise either blindly accept a past decision or blindly overturn it. An agent is the ultimate newcomer. It was never in the room. Give it the minutes of the meeting, and it stops relitigating decisions you already settled.
- A plan before the code. Letting an agent jump straight from a request to an implementation is how you get code that solves the wrong problem confidently. The fix is the same one that works for human work: explore, then plan, then build, with a human reading and approving the plan before any code gets written. A vague request makes the agent guess at a dozen unstated assumptions. A reviewed plan resolves them up front, when they're cheap to change.
- If needed, review for understanding and corrections. Depending on the project, team, company, etc, you may need to spend some time reading and understanding the code that was produced by the agent. Not every agent-authored change needs a human to understand it, and it's up to the team/company/organization to determine where that line is drawn. However, a human review is often beneficial. This is where the opportunity to correct any mistakes that the agent made, lives. Human review can help to identify small coding and architecture patterns that need to be corrected before they get repeated. It also provides an opportunity to consolidate corrections into changes in the project or agent setup. Take the opportunity to improve the process when output issues are identified, measure the effect of the changes, and help the agent output improve during the next round of implementation.
Start where you are
If you read that list and thought "we don't have most of that," you're in the same spot as most teams, and it isn't a reason to stay away from agents. It's a map. You do not need the entire foundation poured before you touch any of this. The most sensible on-ramp I've seen is to put agents to work on the narrow, well-bounded, easily verified tasks - documentation, boilerplate, a contained migration, a well-specified bug fix - while you build the foundation underneath, and to expand what you delegate as the ground firms up.
The good news is that almost everything in the foundation is work you'd want done anyway. Tests, clean boundaries, small changes, written decisions, real review - none of that's overhead you take on for the agents. It's the same care that makes a codebase good to work in for the people, too. The agents make the difference between having it and not having it impossible to ignore. Build the bench, clamp the board, mark the line. Then pick up the powerful tool.
Need help laying the foundation?
If laying that foundation is the work you want help with, I recommend looking at Han as an option. Han is a suite of Claude Code skills that handles exactly this. It turns the work of laying a foundation into automated tools you can run:
- Write architectural decision records and coding standards straight into your repository
- Plan a feature and split it into small, demo-able slices before any code is written
- Stress-tests that plan through codebase-grounded review passes
- Review the resulting code with an adversarial eye instead of a rubber stamp
- and much more
Each skill leans on a team of specialist subagents and cites its evidence, and most of them write their output back into the repo, where the next planning or review run picks it up - which is how you keep an agent from repeating the same mistake on every new feature. It's open source and built for solo engineers and small teams. You can start with one skill and ignore the rest, or follow the advice it gives you on where to go next. There's no wrong way to use it.
River Lynn Bailey is a Senior Software Consultant at Test Double, and has experience in delivering production ready software with agentic tooling.
