AI Coding
How to use AI to document legacy software
A practical workflow for using AI to document legacy software from code and operational evidence, including architecture, data flows, hidden business rules, dependencies, runbooks, and verification without guessing.
Legacy software is difficult to document because its real behavior is spread across code, database schemas, jobs, configuration, deployment scripts, support knowledge, and the memories of people who operate it. A generic architecture summary is rarely enough. Teams need to know what the system does, where important rules live, how data moves, what fails, and how to verify a change safely.
AI coding tools can help inspect large repositories and connect evidence across files. They can also produce plausible explanations that are wrong. The safe workflow is evidence first: every important statement should point to code, schema, configuration, telemetry, or a confirmed subject-matter expert.
Choose the documentation outcome
Decide who needs the documentation and what decision it should support. New engineers may need an orientation map. Operators need deployment, monitoring, recovery, and escalation procedures. A migration team needs system boundaries, data ownership, compatibility constraints, and hidden business rules. Auditors may need access control and data lineage.
Set a bounded first deliverable, such as one critical workflow and its dependencies. Trying to document an entire legacy estate in one pass encourages shallow descriptions and stale pages.
Protect secrets and production data
Use an AI environment approved for the repository. Exclude secret values, private keys, production exports, personal data, customer payloads, and confidential logs. Configuration names can be useful; values usually are not. Replace real identifiers with safe examples.
Give the tool read-only access for the discovery phase. Tell it not to install dependencies, run destructive commands, connect to production, rewrite files, or infer behavior from names alone.
Create an evidence-backed system inventory
Start with repository instructions, manifests, route definitions, entry points, schemas, migrations, service modules, jobs, integration clients, tests, deployment files, and operational scripts. The goal is to identify system parts before describing how they interact.
Use this English Prompt:
Act as a software archaeologist. Inspect the supplied repository evidence and create a system inventory covering entry points, services, data stores, queues, scheduled jobs, external integrations, authentication boundaries, configuration, deployment artifacts, and tests. For every statement, cite the file, symbol, schema, or command that supports it. Mark anything not proven by the repository as unknown. Do not change code.
Review the inventory with an engineer who has operated the system. Resolve renamed services, abandoned modules, generated files, and code paths that are deployed only in certain environments.
Map architecture and ownership boundaries
Create a context view showing users, the legacy system, external systems, and major data stores. Then create a container-level view of applications, APIs, workers, queues, scheduled tasks, and databases. Keep diagrams simple enough to update.
For each component, record its responsibility, owner, runtime, deployment unit, upstream inputs, downstream dependencies, data classification, health signal, and repository location. Mark ownership gaps explicitly instead of assigning them to the last person who touched a file.
Trace critical business workflows
Select workflows with high customer, revenue, compliance, or operational impact: account creation, order processing, invoicing, entitlement changes, refunds, data import, or month-end processing. Trace behavior from trigger to final state.
Trace this business workflow through the legacy system: [workflow]. Start at the user or system trigger and follow UI, API, validation, service logic, database reads and writes, background jobs, integrations, retries, and final user-visible state. List the exact files or symbols at every step, identify hidden business rules, and flag branches that require runtime verification.
Validate the trace with tests, controlled local execution, staging telemetry, or an operator walkthrough. Static code inspection may not reveal feature flags, runtime configuration, database triggers, external callbacks, or manually scheduled jobs.
Document data models and lineage
Map important entities, identifiers, relationships, lifecycle states, retention expectations, and systems of record. For each critical field, note where it is created, transformed, validated, stored, exposed, and deleted. Include database triggers, views, materialized data, caches, search indexes, and exports where they affect behavior.
Use representative schemas instead of real customer records. Confirm whether timestamps, currencies, time zones, null values, and historical rows have special meanings. These details frequently cause migration defects.
Record integrations and failure behavior
For every external integration, document authentication method without secret values, request and response contract, timeout, retry policy, idempotency behavior, rate limits, webhook validation, reconciliation, and failure ownership. Note which failures are visible to users and which become delayed operational work.
Ask AI to identify paths where an external call succeeds but the local write fails, or the reverse. Verify those paths in code and tests. Do not assume a retry is safe unless an idempotency rule is proven.
Build deployment and operations runbooks
Document how environments are created, configuration is supplied, releases are deployed, migrations are ordered, health is checked, alerts are routed, and rollback or forward recovery works. Include prerequisites, commands, expected output, stop conditions, and escalation contacts by role rather than personal details.
Test runbooks in a non-production environment. A runbook that has never been executed is a draft, not an operational control. Record the date and person or team that verified it.
Create an onboarding path
Turn the documentation into a sequence: system context, glossary, local setup, one read-only walkthrough, one critical workflow trace, common failure modes, and a small safe change. Link to authoritative pages instead of duplicating text across many documents.
Add a documentation map that states which page owns each kind of information. This reduces conflicts between a README, wiki, runbook, and migration plan.
Review every claim against evidence
Use AI for a final contradiction and freshness review.
Review this legacy system documentation against the supplied code and operational evidence. Find unsupported claims, stale names, missing failure paths, undocumented dependencies, secrets or personal data that should be removed, and instructions that cannot be reproduced. Return findings by severity with the evidence and the smallest documentation correction. Do not edit code.
Sample important claims manually. Check links, symbols, commands, and diagrams. Add an owner and review date to pages that can become operationally dangerous when stale.
Practical example
A team plans to replace a billing service. Initial documentation says invoices are created by a nightly job. Repository tracing finds three paths: nightly subscription invoices, immediate usage adjustments from a queue, and manual credit notes through an admin route. A database trigger also copies status changes into a ledger table.
By documenting all four behaviors with evidence, the migration team avoids moving only the obvious cron job and losing adjustments or ledger history. AI accelerated discovery, but tests and operator review established which paths were active.
Quality checklist
- Each important claim points to code, schema, configuration, telemetry, or confirmed expertise.
- Current behavior is separate from intended future behavior.
- Critical workflows include success, failure, retry, and recovery paths.
- Data lineage identifies systems of record and transformation points.
- Integration documentation covers idempotency and reconciliation.
- Runbooks have expected output, stop conditions, and verification dates.
- Secrets and personal data are absent.
- Pages have owners and a practical freshness policy.
Common mistakes
- Asking AI for an architecture summary without repository evidence
- Treating file and function names as proof of runtime behavior
- Documenting only happy paths
- Copying secret values or production records into prompts
- Ignoring database triggers, queues, feature flags, and manual operations
- Rewriting confusing rules instead of recording current behavior
- Generating a large wiki nobody owns or tests
- Mixing migration recommendations into the factual system baseline
FAQ
**Can AI automatically document an entire codebase?** It can create a useful first inventory, but broad automatic documentation becomes unreliable without scope, evidence requirements, and human verification.
**Should documentation live beside the code?** Stable technical contracts and runbooks often benefit from version control. Business context may live elsewhere. What matters is a clear owner and one authoritative location for each topic.
**How often should legacy documentation be reviewed?** Review critical pages when related code, infrastructure, integrations, or operations change. Also schedule periodic checks for runbooks and ownership.
**Can the same documentation support a migration?** Yes. Freeze an evidence-backed current-state baseline first, then create a separate target architecture, gap analysis, and migration plan.