Why AI Coding Agents Are Creating a New Documentation Crisis
It is a Saturday night, and your phone buzzes with a production alert. The payment service is throwing 500 errors. You open the repository and stare at the failing function. You merged this code three months ago. The tests passed, the pull request was approved, and the feature shipped ahead of schedule.
But you did not write it. Your AI coding assistant generated it.
Now you are sitting there trying to reverse-engineer the thought process of a statistical model that does not have thoughts. The code is clean, the variables are named well, and the logic appears sound. Yet it is failing, and you have no idea why the original implementation decisions were made. The institutional knowledge is completely absent.
This is the operational reality of modern software development. AI coding agents like Cursor, GitHub Copilot, and Windsurf are standard tools. They accelerate shipping velocity, handle repetitive code generation reliably, and deliver measurable productivity gains. A controlled experiment at GitHub found developers using Copilot completed tasks 55% faster than those working without it. Adoption is now near-universal: 90% of software development professionals had adopted AI tools at work by 2025, with developers spending a median two hours per day on AI-assisted work.
But every sprint that ships faster without a parallel documentation process creates compound documentation debt. The problem is not that AI writes bad code. The problem is that AI-written code ships without the context trail human-written code used to leave behind.
The New Kind of Technical Debt
Traditional development left artifacts. A developer writing a complex feature would leave commit messages explaining their reasoning. They would have discussions in pull requests. They might even write a design document before implementation. Even messy code had a trail of human intent attached to it.
AI coding agents collapse that timeline. Code appears fast, and it is often good enough to merge immediately. The review discussion is minimal, and the commit history is thin. The engineer using the agent often understands what the code does in the moment, but they do not write it down because they did not have to think it through the same way. AWS's developer blog calls this the hidden cost of AI coding.
Six months later, when someone else needs to understand, extend, or debug that code, the institutional knowledge is gone. The code itself is often well-structured and functional, but the "why this approach" and "what trade-offs were considered" are missing.
This is worse than traditional technical debt. With traditional debt, you could often ask the original author. With AI-generated code, the original engineer may not remember the reasoning, because the agent did the implementation. ACM Queue describes this as "comprehension debt", where teams possess functional systems they incompletely understand. A study of indie development teams found that AI helped them build systems more sophisticated than their independent skill level could create or maintain, creating fragility and AI dependency distinct from traditional code quality debt.
Research on AI-generated pull requests reinforces the pattern. A large-scale analysis of over 456,000 pull requests by AI coding agents found that while agents accelerate code submission, their PRs are accepted less frequently than human-authored ones, and commit messages frequently omit the "why" behind a change. Prior research shows that about 44% of commit messages omit either the "what" or the "why" even in human-authored code. AI agents tend to make this worse, not better.
Why the Context Disappears
Documentation traditionally lagged engineering. It was a known friction point. But documentation teams could catch up by interviewing engineers, reviewing design artifacts, and reading detailed commit logs.
When AI agents ship code without those artifacts, there is nothing to reverse-engineer from. Technical writers are now being asked to document systems where even the engineers cannot fully explain the implementation path. The faster code ships, the wider the documentation gap becomes, and the more expensive it is to close later.
The data reflects this shift. GitClear's analysis of 211 million lines of code found that traditional refactoring rates collapsed from 25% of changed lines in 2021 to less than 10% in 2024, while the frequency of duplicated code blocks increased roughly eightfold during the same period. The volume of code is expanding rapidly, but the understanding of that code is not keeping pace.
Salesforce documented this problem directly. AI-assisted development caused code volume to increase by approximately 30%, with pull requests regularly expanding beyond 20 files and 1,000 lines of change. Review latency rose quarter over quarter, and review time for the largest pull requests began to plateau, indicating that reviewers were no longer meaningfully engaging with changes. When review stops scaling, the context that documentation teams depend on stops existing.
When the Documentation Team Leaves
Organizations that reduced documentation headcount during AI adoption are now discovering a difficult truth. They cannot reconstruct what was built.
Companies have eliminated entire technical writing teams, assuming AI could simply read the code and generate the manuals. Snowflake eliminated its technical writing team in March 2026, a cut of roughly 47 to 70 roles, while simultaneously reporting 30% product revenue growth. Canva laid off 10 of its 12 technical writers in early 2025, framing the decision as "empowering engineers to take greater ownership of documentation." Amazon followed with similar cuts. These were strategic decisions made from positions of financial strength, not desperation.
But AI models perform to the quality of their context. When the documentation is missing, broken, or out of date, the model works harder and delivers less. It guesses. A large-scale study found that approximately 90–93% of issues in AI-generated code are code smells rather than outright bugs, meaning the problems are subtle and hard to catch without deep contextual knowledge. That is exactly the kind of knowledge documentation teams used to hold.
The right path is not to rebuild large headcount. It is to redirect strong technical writers into documentation system management. A senior writer who understands the product can run validation workflows, manage AI-generated output, and maintain institutional knowledge in a way pure automation cannot. The role shifts from writing every page to ensuring the system produces accurate, complete, and useful documentation. This is a humane and operationally smart path for companies that still need documentation but cannot afford the old headcount model.
A System That Actually Scales
The solution requires three things working together.
Documentation must happen at generation time. Organizations need to capture context as AI-generated code is written, not after it ships. This means tooling that extracts intent from the coding session, the agent prompt, the conversation, the decisions made during generation, and converts that into structured documentation automatically. Waiting until post-release to document AI-generated code is already too late.
A validation layer is also required. A skilled technical writer or engineer needs to review AI-generated documentation against what actually shipped. They correct gaps and add the institutional context only humans hold. The goal is not to rewrite everything. The goal is to catch errors, add edge cases, and confirm the output matches reality. This is closer to QA and editorial oversight than traditional documentation writing.
Finally, documentation must stay tied to the codebase as it evolves. AI coding agents ship changes fast. Documentation systems need to detect drift and regenerate outdated sections automatically. Static documentation becomes obsolete the moment the next AI-assisted sprint ships.
Organizations that adopted AI coding agents are now dealing with the documentation gap they created. The fix is a system that documents as fast as your agents ship code, with a validation layer that keeps it trustworthy.
Doc Holiday is a documentation engine that generates output directly from engineering workflows. It builds release notes, API references, and changelogs automatically from code commits and pull requests. It gives lean teams the structure to validate, manage, and scale that output without rebuilding a large headcount. If your organization adopted AI coding agents and is now discovering the documentation gap they left behind, this is the system designed to close it.
