Legacy System Documentation with AI: A Practical Guide

Legacy system documentation with AI is the use of coding agents and large language models to reverse-engineer what an undocumented system actually does — business rules, architecture, data flows, integration contracts — into artifacts that domain experts can review, correct, and sign off. It turns the work everyone skips because it never fits the budget into a supervised agent workstream measured in weeks, not years. This guide is for CIOs, CTOs, and VPs of Engineering who own systems the original authors left behind: which artifacts are worth generating, how the recovery workflow runs, where AI-generated documentation goes wrong, and how to keep the output from rotting the way the last set of docs did.

One framing up front: documentation recovery is not an end in itself. It is Phase 2 of the larger program in our AI-powered legacy modernization roadmap — the phase that de-risks every phase after it, and the highest-leverage, lowest-risk place to start agentic work, because the output is reviewable text, diagrams, and tests rather than production code.

Why legacy documentation is the bottleneck nobody budgets for

The defining problem of a legacy estate is not old code — it is lost knowledge. The engineers who wrote the system are gone, the design decks describe a system that no longer exists, and the only accurate specification is the code itself, usually in its least readable corners. Thoughtworks identifies loss of historical context and thin automated test coverage as the two constraints that make legacy work slow regardless of team skill. Both are documentation problems: context that was never written down, and behavior that was never pinned down.

Manual documentation recovery has always been technically possible and economically irrational. Reading a large module, reconstructing its business rules, and writing them up is weeks of senior-engineer time per module — time that never competes successfully against roadmap work, which is why the documentation backlog only grows. The consequences compound quietly: every new hire onboards by archaeology, every change starts with re-derivation of what the code does, and every departure of a long-tenured engineer converts institutional knowledge into key-person risk.

What changed is the economics of the reading. Pattern extraction from large volumes of code is precisely the task language models are best at, and the industry has noticed: in Google Cloud's 2025 DORA research, 64 percent of surveyed software professionals reported using AI for writing documentation, and Stack Overflow's 2025 developer survey found roughly half of developers using AI at least partially for creating or maintaining docs. The open question for an engineering leader is no longer whether AI can draft documentation — it is which artifacts to generate, how to validate them, and how to stop them going stale.

What AI can actually generate from a legacy codebase

Not all documentation is equally valuable, and agent time — plus, more scarce, expert review time — should go where the leverage is. Six artifact types, ranked by what they de-risk:

Artifact	What it contains	What it de-risks
Plain-English business rules	The decisions the code makes, extracted per module and stated in domain language	Migrating behavior nobody understands; disputes about "intended vs. accidental"
Architecture and dependency maps	Current-state diagrams generated from code: modules, call graphs, shared data, integration points	Big-bang surprises; wrong service boundaries; hidden coupling
Data-flow documentation	Where data originates, how it transforms, where it lands — including the undocumented side channels	Data migration failures; compliance blind spots
Characterization tests	Executable documentation: tests that pin down what the system does today, correct or not	Silent behavior changes during migration; regression without detection
Integration contracts	The de facto API: formats, timings, retries, and quirks that downstream consumers depend on	Breaking consumers who depend on undocumented behavior
Operational runbooks	How the system is deployed, monitored, recovered — reconstructed from scripts, configs, and incident history	Key-person risk; on-call escalation dead ends

Two of these deserve emphasis because most coverage of AI documentation tools skips them.

Characterization tests are documentation. Michael Feathers defined legacy code as code without tests, and his remedy — characterization tests that capture current behavior before anyone changes it — has always been the highest-value documentation a legacy system can have, because it is the only kind that executes. Hand-writing them never fit the budget either. Agents generate them at scale from observed behavior and code paths; humans curate the suite down to the cases that matter. A module with validated characterization tests is a module you can migrate with a safety net.

Dependency maps must come from the code, not the wiki. Microsoft's mainframe modernization work is explicit about this: its agent pipeline builds dependency graphs directly from COBOL call and copy relationships and extracts business logic into human-readable documentation before any conversion is attempted. The generated map is checkable against the running system — which is exactly what makes agent output trustworthy where tribal memory is not.

The recovery workflow: five steps from undocumented to governed

Legacy system documentation with AI works as a fixed-scope program, not an open-ended "let the AI document everything" gesture. The workflow we run:

1. Scope from the assessment. Documentation effort follows modernization priority. If you have run an AI legacy system assessment, its scored portfolio tells you which systems move first — document those to depth, and the rest to inventory level only. Documenting a system slated for retirement is waste.
2. Extract with agents, in parallel. Agents sweep the scoped codebase and produce first-draft artifacts: business-rule extractions per module, generated diagrams, data-flow traces, candidate characterization tests. This parallelizes across an estate — the same scoped-task-plus-human-review operating model that defines agentic engineering, applied to analysis instead of construction.
3. Run the expert triage gate. The non-negotiable human step, covered in depth below. Domain experts review each extracted rule and classify it before anything downstream depends on it.
4. Publish as docs-as-code. Validated artifacts live in the repository next to the code they describe — Markdown, diagram sources, test suites — versioned, reviewable in pull requests, and owned like code. Documentation that lives in a wiki nobody diffs is documentation that is already rotting.
5. Wire freshness into the pipeline. Regeneration and drift checks run in CI: when code changes in a documented module, the pipeline flags or re-drafts the affected artifacts for review. This is the step that separates a documentation program from a documentation event — the estate got undocumented once because docs were a one-time deliverable; don't rebuild that failure mode with better tooling.

In an enablement engagement, steps 2–5 are also where a team learns to run agent workstreams generally — documentation recovery is the training ground we recommend because a bad output is a wrong paragraph, not a production incident.

The validation gate: intended, tolerated, or obsolete

Agents can tell you what the code does. Only your people can tell you whether it should keep doing it. The gate that makes AI-generated documentation trustworthy is a forced classification: domain experts review each extracted business rule and mark it as one of three things.

• Intended behavior — a real rule the business depends on. It gets documented as specification and protected by characterization tests.
• Tolerated bug — behavior that is wrong but survivable, which users or downstream systems may have adapted to. It gets documented as a bug, with a decision recorded: preserve it through migration, or fix it deliberately with stakeholder sign-off.
• Obsolete — behavior serving a rule that no longer exists. It gets marked for exclusion, which is where documentation recovery starts paying for itself: McKinsey's LegacyX bank engagement had agents document embedded business logic in plain English precisely so experts could validate it before conversion — because faithfully migrating dead rules is pure cost.

Skipping this gate is the signature failure of documentation-free migration, and AI makes the failure faster: an agent will happily reimplement a tolerated bug as a well-documented feature. Budget roughly a third of program effort for expert review, and treat a disputed rule as a blocker, not a footnote.

Documentation as fuel: your agents are the second audience

Here is the angle most AI documentation tools coverage misses entirely: the documentation you recover is not just for humans. It is the operating context for every coding agent you will run against the estate afterward.

An agent asked to migrate a module in an undocumented system starts from the same archaeology a new hire does — except it cannot walk over to the one engineer who remembers. Validated business rules, dependency maps, and characterization tests are what convert a legacy codebase from hostile terrain into an environment where agents can work reliably. Research is converging on the same conclusion: the Reversa framework formalizes "reverse documentation engineering" as producing operational specifications for AI agents — documentation quality as a precondition for agent effectiveness, not an output of it.

This creates a flywheel worth designing for. Agent-generated, human-validated documentation makes the next agent workstream faster and safer; that workstream's outputs (new tests, updated diagrams) enrich the documentation further. It is also why documentation must capture runtime truth, not just static structure — what the system does under production traffic, which code paths are actually hot, which "dead" branches still fire monthly. Grounding agent work in observed production behavior is the discipline we cover in why production-safe AI-generated code depends on runtime context, and it applies to documentation with equal force: a data-flow diagram nobody checked against production is a hypothesis, not a document.

The payoff shows up in wave planning. Incremental modernization — the strangler-fig program that replaces a system without a big-bang rewrite — depends on knowing where the seams are. Validated dependency maps are how you draw waves that don't fork shared data; characterization tests are how each wave proves equivalence before cutover.

Where AI-generated documentation goes wrong

Honest constraints, because the failure modes are predictable:

• Plausible fiction. LLMs generate confident descriptions of behavior that isn't there — hallucinated docs are worse than no docs because they carry false authority. Mitigations: ground extraction in the actual code and runtime traces, require evidence links from every documented rule back to source, and never publish an artifact that skipped the triage gate.
• Code-only truth. The code cannot tell you why. Rationale, regulatory constraints, and the history of what was tried and abandoned live only in people; agent output is the scaffold for those interviews, not a replacement. Systems whose behavior is dominated by configuration, data, or third-party quirks also document poorly from source alone.
• Volume without curation. Agents will cheerfully produce ten thousand pages nobody reads. The deliverable is a curated set of artifacts scoped to modernization priority — generation is cheap; review attention is the scarce resource, which is why scoping (step 1) matters more than tooling.
• One-time regeneration. Regenerating everything quarterly and re-reviewing from scratch doesn't scale. Drift detection must be incremental — re-review only what changed — or the program quietly stops after the second cycle.

Measuring whether documentation recovery paid off

Documentation is a means; measure the ends. Four signals an engineering leader can track, using the same baseline discipline as the rest of a modernization program:

1. Onboarding time. Days until a new engineer (or a newly provisioned agent workstream) ships a reviewed change in the documented system, before vs. after.
2. Key-person risk. Count of systems where operational knowledge has a single human point of failure — the number the assessment surfaced — trending down.
3. Change confidence. Characterization-test coverage on modules scheduled for migration waves, and escaped regressions per wave.
4. Modernization throughput. Wave planning and execution time once maps and tests exist; this is where the 40–60 percent time-to-market reduction we target at program level either shows up in the metrics or doesn't.

FAQ

How do you automatically generate documentation from legacy code?

Point coding agents or code-analysis tools at the repository to extract structure (call graphs, dependencies, data flows), then use LLM-based extraction to draft plain-English business rules and module documentation, and generate characterization tests from observed behavior. The generation is the easy half — the value comes from routing every draft through domain-expert review before it becomes the record.

Can AI fully replace manual documentation for legacy systems?

No. AI removes the reading-and-drafting labor that made documentation economically irrational, but it cannot supply intent, rationale, or business context, and it will confidently document behavior incorrectly if ungoverned. Every credible program pairs agent extraction with expert validation — plan for roughly a third of the effort to be senior human review.

What is the best way to understand an undocumented legacy system?

Run agents over the code to produce a first-draft map — modules, dependencies, extracted rules — then interview the people who operate the system using that map as the agenda. Agent output turns open-ended archaeology into a review exercise, which is faster and surfaces disagreements between what the code does and what people believe it does.

Why is legacy code documentation important for modernization?

Because every downstream decision — service boundaries, wave sequencing, cutover criteria — depends on knowing what the system actually does. Undocumented behavior is where migrations fail: either a real rule gets dropped or a dead one gets faithfully rebuilt. Validated documentation plus characterization tests is what makes incremental replacement provably safe.

How accurate is AI-generated documentation?

Draft accuracy varies with code quality, language, and how much behavior lives outside the code (configuration, data, integrations). Treat every generated artifact as a claim requiring evidence: link rules to source locations, check diagrams against the running system, and validate through the intended/tolerated/obsolete triage. Accuracy is a property of the workflow, not the model.

How do you keep documentation up to date after generating it?

Store it as docs-as-code in the repository, and wire drift detection into CI so changes to documented modules flag or re-draft the affected artifacts for incremental review. Documentation stays current only if freshness is enforced by the pipeline rather than by intention — that failure mode is how the estate became undocumented in the first place.

Recover the knowledge before you move the system

Legacy system documentation with AI converts the least fundable work in engineering into a short, supervised program: agents do the reading, experts do the judging, and the estate ends up with business rules you can defend, maps you can plan waves against, and tests that catch what migration would otherwise silently break. Done first, it de-risks everything that follows — and it is the safest possible first exercise in running agent workstreams.

If you are deciding where documentation recovery fits in your modernization sequence — or whether your estate is ready for agentic work at all — our AI readiness assessment benchmarks your systems, surfaces the knowledge and coverage gaps, and returns a prioritized plan. It is the fastest way to find out which of your systems are one departure away from being unmaintainable.