Use AI to shorten investigation, not to skip verification
A plausible architecture explanation is useful as a map of where to look next. It is not proof of production behavior.
Legacy systems are hard to modernize because knowledge is fragmented. The code shows implementation but not always intent. Documentation reflects an earlier state. Production configuration lives elsewhere. Critical workflows may depend on scheduled jobs, support procedures, or consumers the application team cannot see.
AI tools can help connect these fragments. They can summarize modules, trace callers, compare configurations, draft diagrams, and identify likely migration seams. Used carelessly, they can also turn an incomplete repository view into a confident but false system narrative.
Begin with questions that produce verifiable artifacts
Good discovery tasks have outputs a team can inspect:
- List the entry points that call a specific business operation.
- Trace the packages involved in creating an order.
- Compare environment configuration keys with typed property classes.
- Identify direct writes to a table owned by another capability.
- Summarize external HTTP clients and their timeout behavior.
- Locate scheduled jobs and the state they modify.
- Draft a dependency map from build files and source imports.
- Find tests that describe a public API contract.
These tasks are narrower than “explain the architecture.” They also produce file paths, symbols, and relationships that a developer can confirm.
Control the context boundary
Before giving a tool access to source, tickets, logs, or documents, confirm that the approved service may process that data. Exclude secrets, production records, customer information, and unrelated repositories.
Read-only access is a good starting point for discovery. The tool does not need write, deployment, cloud, or database permissions to explain a code path.
Repository instructions should state module boundaries, build commands, supported versions, generated paths, and terminology. This context helps the AI distinguish intentional architecture from an accident it should recommend removing.
Ask the tool to separate evidence from inference
A useful analysis identifies:
- What is directly observed in the repository.
- What is inferred from naming or common framework behavior.
- Which relevant inputs are unavailable.
- Which claims need runtime or owner confirmation.
For example, finding an interface named PaymentGateway proves the interface
exists. It does not prove which implementation production uses, whether calls
are retried by infrastructure, or how operators repair partial failures.
Requiring file references and uncertainty notes makes review faster and reduces the chance that a polished explanation becomes accepted folklore.
Combine static analysis with runtime evidence
Code reveals possible paths. Telemetry reveals exercised paths.
Compare AI-assisted source analysis with:
- Distributed traces and request logs.
- Database query and connection telemetry.
- Message topics, consumer groups, and dead-letter queues.
- Deployment manifests and environment configuration.
- Network flow and dependency maps.
- Job schedules and execution history.
- Incident reviews and support escalation patterns.
A supposedly unused endpoint may serve an infrequent but critical month-end workflow. A static dependency may be unreachable in production. Modernization decisions need both views.
Generate characterization tests before major changes
AI can help draft tests around observed behavior, especially repetitive input combinations and serialization contracts. A human should confirm that each test captures behavior worth preserving rather than an incidental implementation detail.
Prioritize tests around:
- Public APIs and message formats.
- Financial, authorization, and state-transition rules.
- Historical edge cases found in incidents.
- Data migration and reconciliation behavior.
- Provider failure and timeout handling.
- Jobs that are difficult to exercise manually.
These tests become an executable record for the modernization step. They also expose areas where nobody can state the expected outcome.
Use multiple passes with different purposes
One large analysis tends to blur discovery, design, and implementation. Separate the work:
- Inventory components and dependencies.
- Trace selected business journeys.
- Identify risks and unknowns.
- Propose candidate boundaries.
- Challenge each proposal with counterexamples.
- Build a small migration plan with validation.
The challenge pass is important. Ask what would make a proposed extraction unsafe, which shared transactions cross the boundary, and which hidden consumers might exist. The goal is not to have the AI approve its first suggestion.
Keep an evidence-backed modernization notebook
Store confirmed findings in versioned documentation close to the system. Record the source, date, owner, uncertainty, and decision that followed. Do not rely on chat history as the only architecture record.
A useful entry might include:
- Capability or workflow being examined.
- Confirmed code and runtime dependencies.
- Data owner and consumers.
- Operational failure modes.
- Unknowns and responsible contacts.
- Candidate modernization seam.
- Tests and telemetry required before movement.
This notebook lets later investigations build on verified knowledge rather than regenerate the same summary from scratch.
Closing view
AI is valuable in legacy modernization because it lowers the cost of asking more questions. It can search broadly, explain unfamiliar patterns, and turn scattered evidence into a reviewable first draft.
The team still has to establish truth. Code references, deterministic tools, runtime signals, characterization tests, and operator knowledge convert AI hypotheses into engineering evidence. Used that way, AI improves the speed of understanding without making confidence cheaper than accuracy.