AIDLC on Legacy Code

An agent working in an old codebase needs a map before it needs a task. Have an agent draft architecture notes: the main modules, how data flows between them, the entry points, the jobs that run on a schedule, and the parts it could not understand. Then have people who know the system review and correct those notes. The agent is fast at the survey; the people supply what the code cannot say, such as why a strange branch exists or which customer depends on it.

Keep the reviewed notes in the repository next to the code, where the agent loads them on every run, and link them to tickets, incident history, and design documents through a context graph. Treat the notes as living files, because a stale map is worse than none: the agent follows it anyway. One rule matters above the rest. Never trust an agent's summary of code that no person has read. A summary is a hypothesis until someone who knows the system has checked it.

A characterization test, a technique Feathers describes in the same book, records what the code actually does today, not what it should do. You call the code, observe the result, and assert that result. The suite becomes a net: if a later change alters behavior, a test fails and shows exactly where.

Agents are well suited to producing these. Point one at a module, have it exercise real inputs and write down the outputs, then have a person sample the tests for quality. Check that they would fail if the behavior changed; the mutation-testing advice under tests first applies fully, because a generated test that asserts nothing gives false comfort. The result is a characterization suite that later gates every agent change in this area.

Martin Fowler's "Strangler Fig" (martinfowler.com, 08-22-2024) describes modernizing a legacy system gradually: build new components alongside the old system and move functionality over piece by piece, instead of attempting a risky full replacement. The old system keeps serving traffic the whole time, and it shrinks until it can be retired.

The pattern suits agents because each slice is a bounded task with a clear finish line. Route one capability to the new implementation, compare its output against the old one on real traffic or the characterization suite, and only then take the next slice. If a slice goes wrong, the old path is still there. This is small batches applied at the architecture level, and each slice can be assigned a risk tier: a read-only report moves with light review, a payment path moves with the heaviest.

The most valuable context in an old system lives in the heads of the people who built it, and it leaves when they do. Use the agent to make capture cheap. Have it prepare questions from the code: why does this function special-case that value, what does this job do on the last day of the month. Record the interview, have the agent turn the answers into notes, and let the expert correct the notes. File each answer against the code it explains, in the architecture notes, so the next agent run inherits it. A short, structured conversation before a departure is worth far more than a handover document written afterward, and the team side of this work is part of upskilling the people who stay.

Code can be rolled back; data often cannot. Danilo Sato's "Parallel Change" (martinfowler.com, 05-13-2014), also called expand and contract, gives the safe shape: add the new version beside the old, move clients across, then remove the old. For a schema change that means add the new column or table, write to both, backfill, switch reads, and only later drop the old structure. Each step is small, reversible, and deployable alone.

Let agents draft the migration scripts and the backfill, but put the production run behind a human gate, a rehearsal on a copy of real data, and a written rollback. This is the highest tier of risk-tiered review, and it is not a place for unattended agents.