"It’s time for documentation to stop being a record of decisions and start being treated as infrastructure."
Many teams chasing better AI coding agent performance are looking in the wrong place. They're tweaking prompts, upgrading models, experimenting with new tools. The gap far fewer are closing is documentation.
Not documentation as in a Confluence page nobody reads. Documentation as working memory. The shared understanding of how your systems actually behave, written down in a place where both your developers and your AI agents can find it.
When that's missing, every AI-assisted task starts from scratch. The model can't orient. It makes assumptions. It duplicates work that's already been done. It solves problems that aren't the real problem. And the developer sitting alongside it pays the tax, every single time.
We've been watching this pattern emerge across teams working in very different contexts the past few months. A greenfields mobile application. A legacy migration inherited without documentation, tests, or clear requirements. A large hybrid codebase, part heritage, part newly migrated stack. Three completely different situations. The same underlying constraint.
AI performs to the quality of its context
An AI coding agent is only as useful as what it knows about your system. When it doesn't know, it guesses. Guesses cost tokens. Worse, they cost the developer's attention, which is an essential thing to try to protect.
The teams doing the most effective AI-assisted work right now aren't the ones with the best prompts. They're the ones who have invested in making their systems legible. Component registries that tell the agent what already exists before it creates something new. Data model schema documents that stay current with the codebase. Technical documentation built not from what you planned to build, but from what you actually built.
We explored this tension recently when we brought our crews together for a day of working on real in-flight problems alongside Josh Vial, Director and AI Educator. One team spent a morning building a pre-commit hook that automatically flags when database migrations change without a corresponding update to the documentation. Twenty minutes to build. From that point on, documentation drift is a commit-level problem rather than a quarterly wash-up.
That's the shift. Documentation stops being a record of decisions and starts being infrastructure.
The hidden documentation debt in legacy systems
Legacy systems are the clearest case. When the code is yours and the team has been working in it for years, there's a kind of ambient knowledge that makes up for what isn't written down. Developers fill in the gaps because they've seen the patterns before.
AI agents can't do that. They read what's there.
When the documentation is missing, broken, or out of date, the model works harder and delivers less. It will still produce an answer, and honestly, that’s the insidious part. The answer will be wrong in ways, some quite subtle and hard to spot. Not obviously wrong, where you catch the error immediately. Quietly wrong, where the problem surfaces later, after you’ve invested time and effort - and costs more to fix.
Our teams navigating legacy codebases most effectively aren't trying to document everything at once. They're identifying hotspots: the parts of the system where AI consistently underperforms, where developers lose time, where the same questions keep getting asked. They document those first, then the next, then the next. The investment compounds because you're only ever doing the work once.
What good documentation looks like for AI-assisted development
It's not the same as documentation written for humans. Human documentation manages attention. It summarises, contextualises, provides background. AI documentation needs to be accurate and specific. Smaller than the code it describes. Faster to read than navigating the codebase directly.
It should describe the current state of the system as fact, not intent. "This is how authentication works" not "this is how we plan to handle authentication." When the system changes, the documentation changes with it. That's a discipline, and it requires someone to own it, not assume it will happen.
The most practical version of this showed up with our team working on a greenfields mobile app: a component registry that agents check before creating anything new; a data model document that updates when schema migrations run; technical notes for any open-source dependencies where the original documentation is incomplete or outdated. None of these are large documents. All of them pay for themselves quickly.
This is where strong software engineering support matters, not just to write better code, but to make the whole codebase easier for both people and AI agents to understand, maintain and improve.
Before changing the model, check the context
Before you change your model, change your prompt, or add another tool to the stack, ask what your AI agent actually knows about the system it's working in. Not in theory. In practice. What has it got access to? What has it been told?
If the answer is mostly the code itself, you're making the model do expensive archaeology every session. The code tells the AI what exists. Documentation tells it what it means.
That's not a tools problem. It's a foundations problem. And it's entirely within your technical team’s control to fix.
FAQs about AI coding agents and documentation:
Why does AI perform badly on legacy code?
Legacy codebases often lack the documentation that AI coding agents rely on to orient themselves. Without it, the model falls back on assumptions based on what it can read directly in the code. It will still produce answers, but they're more likely to be wrong in ways that are hard to catch. The problem isn't the model's capability - it's the absence of the type of context the model needs to apply that capability accurately.
What documentation do AI coding agents actually need?
The most useful documentation for AI-assisted development is accurate, specific, and current. It describes how the system actually works, not how it was planned to work. Practically, that means a component registry agents can check before creating new elements, a data model document that stays in sync with schema changes, and technical notes for any dependencies where public documentation is incomplete. It should be smaller and faster to read than the code itself.
How do you keep documentation up to date when a codebase is changing fast?
The most reliable approach is to make documentation drift a commit-level problem. Pre-commit hooks can detect when code changes in a given area and flag whether corresponding documentation has been updated. This shifts the responsibility from periodic review (which tends not to happen) to a natural part of the development workflow. It doesn't require perfect documentation from the start, it just requires that documentation and code stay in sync from here.
Does better documentation help human developers as well as AI agents?
Yes, and the overlap is significant. Documentation that helps an AI agent orient in a codebase tends to help a new developer do the same thing. The formats are slightly different, human documentation manages attention and provides context, AI documentation prioritises accuracy and brevity… but the underlying investment benefits both. Teams that treat documentation as infrastructure rather than overhead tend to move faster, regardless of how much AI they're using.
