Most teams treat their AI coding problem as a tooling problem. Wrong model, wrong prompt, wrong workflow. But the real problem is one engineering teams have always understood. That agent walked into a codebase with no culture, or a culture nobody had bothered to write down, and did exactly what anyone does in that situation. It guessed.
Think about how culture actually spreads on a human team. If two thirds of the people have worked together for years, you don't need a handbook. Nobody explains "the way we do things here," because the way you do things here is just what happens when that many people who already agree keep working alongside each other. Drop a quarter of the team in as new hires and the maths changes right away. Now someone has to say the quiet part out loud. What we build first. What a good pull request looks like. What we'd never ship, no matter how much pressure we're under.
An AI agent is the most extreme version of that new hire. It has none of the corridor conversations, none of the "ask Steve, he was here when we made that call," none of the six months of absorbing a team's judgement by watching it get exercised. It walks in on day one, every single day. Even when it retains project context, it hasn't spent six months absorbing the team's judgement in the way a person has. If the codebase has a strong, explicit culture, exemplars, conventions, a clear record of why things are the way they are, the agent inherits it fast and works inside it convincingly. If the codebase doesn't have that, the agent doesn't fail loudly. It just quietly starts running on the dominant pattern it can find. On an undocumented legacy system, that might be the worst pattern in the file.
We're watching this play out in real time across two very different scenarios within the same engineering team. One is a greenfield mobile build, going well enough that the team now worries about being spoiled by it. The predominant experience, every time a developer comes back to that codebase after a few weeks away, is that it takes less instruction to get the result they want, not more. That's not the model getting smarter. It's the documentation, the shared terminology, the architecture decisions written down as they were made, doing more work than anyone gave it credit for at the time. From day one, this product has been built to be explicit about culture and expectations.
That clarity shows up in small, practical ways. If an agent encounters a form, for example, it can work out which validation approach, component pattern and error-handling convention to follow because those choices have names, examples and a clear precedent. It isn't choosing between three competing approaches and guessing which one the team still considers current.
The other scenario is what's coming next for that same team: a run of work across older applications that were never built with this rigour, never designed or delivered for the world we're in now. There's no shared component glossary. No record of why a particular workaround exists. These are sizable, business-critical apps that have been in production for five to ten years or more. The instinct is to assume the same skills and the same workflows will transfer across. They won't, not directly, because those workflows were never really "AI workflows." They were culture, encoded in small pieces, that agents happened to be able to read.
The useful move isn't documenting everything. It's working out which context the codebase actually fails to communicate before committing to a chunk of work. Can an agent interrogate this codebase and get a straight answer about what's in scope, what's a defect versus a change request, what pattern to follow when two examples disagree? Can it tell which architectural choices are deliberate, what "done" means beyond passing tests, and which patterns are historical accidents rather than precedents to copy? Where the answer is no, that's not a reason to avoid using AI on the legacy estate. It's a signal about where the first investment needs to go, and it needs to go in deliberately, in small chunks, the same way you'd define a culture for a team that's mostly new people rather than assume it'll form on its own.
There's a genuinely useful test in all this, and it has nothing to do with how clever the output looks on day one. Watch whether the codebase gets easier to work in every time someone touches it, or harder. Easier means the documentation and the patterns are actually holding. Harder means you're accumulating debt that will eventually land on whoever has to clean it up, human or agent.
None of this is really a story about AI. It's the same story engineering teams have always told about onboarding, about what happens when the people who hold a system's context in their heads move on or move over. The agents have just made the story visible faster than a slow-moving new hire ever would have. Most teams never find out how undocumented their culture really was until someone tries to follow it without already knowing it.
FAQs
Why does AI coding work better on some codebases than others?
The difference usually isn't the AI tool itself. It's whether the codebase has a clear, documented culture, conventions, decisions, and reasoning an agent can pick up quickly, or whether that knowledge only exists in people's heads.
Do you need special documentation for AI agents specifically?
Usually, no. The same clarity that helps a new team member ramp up quickly also helps an AI agent work inside your conventions instead of guessing at them. What agents often do, however, is expose where your existing documentation still relies on people already knowing the context.
How do you know if your codebase is ready for AI-assisted delivery on legacy systems?
Run a quick audit before committing to a large chunk of work. Ask whether an agent can get a straight answer from your existing documentation about scope, patterns, and past decisions. Where several examples conflict, can it tell which one is current and why? If not, that gap is where to invest first.
What's the real signal that AI-assisted development is working well?
Not how impressive the first output looks - but whether the codebase gets easier to work in every time someone touches it. That's the sign the documentation and patterns are holding.
