Using Claude Code to Document a Legacy Codebase
Using Claude Code to Document a Legacy Codebase
Most people check their bank balance occasionally. Fewer look at the actual transactions. Even fewer run the numbers on what those transactions reveal: that 12 percent of monthly spending goes to one category, or that a particular line item has jumped 3 percent month over month for six consecutive months. The balance tells you whether the lights are still on. The transactions tell you what is actually happening. Legacy codebases work exactly the same way. Organizations know they work. They avoid looking too closely because looking closely feels like opening a door they cannot close again. Claude Code changes that calculation.
For the first time, a development team can walk into a decades-old codebase and ask it real questions — not just "what is this" but "how does it work" and "why was it built this way" — without committing to a rewrite, without a six-month audit engagement, and without needing the engineer who left in 2011. The what gives you the map. The how gives you the nervous system. The why, even imperfectly, gives you something that has been missing from these systems for a very long time: institutional memory.
The What: Taking Inventory
The first prompt most development teams think to ask is the most basic one. Describe the components of this codebase. Identify the compute layers, the input and output paths, the major modules and what they appear to do. It is the equivalent of walking into a building you have never entered and asking someone to show you around.
This alone is more than most legacy organizations have. Decades of attrition, missed documentation cycles, and the quiet assumption that someone else understands the system have left many codebases genuinely opaque to the teams responsible for maintaining them. Claude Code asked to document the what will produce a structured inventory: here is what the system takes in, here is what it produces, here is roughly how the pieces connect.
But the what prompt has a second, more important instruction built into it. Ask Claude Code not just to describe the components but to flag where the system looks robust and where it looks brittle. A module that has been touched hundreds of times over twenty years is not necessarily stable. It may be the most fragile thing in the entire system. An isolated component that nobody has modified in a decade may be rock solid. The what, done right, gives you a risk map alongside the inventory.
The what gives you the map. The how gives you the nervous system. The why gives you something missing for years: institutional memory.
The How: Reading the Nervous System
The second layer is where Claude Code starts earning its place in the workflow. The how prompt asks for a code map — specifically, how the system takes input and produces output, traced through its actual execution paths. Not a high-level summary. A functional account of what happens between the moment data enters the system and the moment a result comes out the other side.
This is the nervous system read. It reveals dependencies that no architecture diagram ever captured because nobody drew one, or because the diagram was accurate in 2004 and the code diverged from it over the following twenty years. It surfaces the workarounds, the patches applied to patches, the functions called in sequences that made sense to someone at the time and look inexplicable today.
Again, the brittle-versus-robust instruction applies here. Ask Claude Code to identify where the execution path looks solid and where it looks like it is held together by assumptions that may not age well. A system that breaks in production on an edge case nobody anticipated is almost always a system where the how was never fully understood. That gap is exactly what this prompt is designed to close.
The Why: Institutional Memory on Demand
The third layer is the most interesting one, and the most honest about its own limitations. Asking Claude Code why a system was designed the way it was is asking it to reason about intent from evidence. The code is the only witness. The engineers who made the original decisions are gone. The documentation, if it existed, is either lost or wrong.
Claude Code will hallucinate here. That is not a reason to skip the prompt. It is a reason to use the output carefully.
What the why prompt produces is a reasoned hypothesis. Based on the structure of this code, based on the patterns visible in how it handles edge cases, based on the apparent priorities baked into its architecture, here is what it looks like this system was trying to do and why it was built this way. That hypothesis goes to the development team. Someone on that team reads it and says that is wrong — and here is what actually happened. That correction is institutional knowledge that was locked in someone's head, possibly for decades. The hallucination was the prompt that unlocked it.
An imperfect why, stress-tested against the people who know the system, is infinitely more useful than no why at all.
The hallucination is not the failure mode. It is the conversation starter. Someone reads it, says that's wrong, and explains what actually happened. That is institutional knowledge finally on the record.
What to Do With the Picture
None of this is an argument for handing the codebase to an AI and walking away. The opposite, in fact. The value of the what, how, and why sequence is that it produces a picture — a complete, actionable picture of a system that was previously unknown, undocumented, and frankly a little scary. What a company does with that picture is proceed thoughtfully and carefully.
The forensic read is the prerequisite for everything that comes after. You cannot make a sound architectural decision about a system you do not understand. You cannot identify what is safe to modernize and what must be left alone without first knowing what each part does and why it exists. The organizations that have avoided touching their legacy systems have not been irrational. They have been operating without the information they needed to act with confidence. Claude Code, asked the right questions in the right sequence, provides that information.
The goal was never to hand the codebase to an AI and let it rewrite history. The goal was to finally see it clearly. The what tells you what you have. The how tells you how it holds together. The why, even imperfectly, tells you why it exists. That picture does not make the decisions for you. It makes the decisions possible.
Aaron Rose is a technology writer and publisher covering system architecture, cloud platforms, and AI tools.