IH Tech · Field Guide 001 · https://ihtech.ba/field-guides/agentic-legacy-modernization/
FG-001
Field Guide 001 · IH Tech
A control-loop strategy for AI-agent modernization: structure first, plans as reviewed prompts, machine-generated parity evidence, and a clear fit test.
Reading route Exec
You are responsible for a system the business still depends on every day, built on a stack that is now a liability: a framework past its support window, an architecture nobody fully remembers, a codebase where every change is priced in fear. AI coding agents are on the table. The question is not whether they can write the new code. They can. The question is whether an agent-driven modernization program will actually finish, or stall at 70% the way most rewrites do.
Reading route Exec
Run the modernization with AI agents if the legacy system can serve as the specification: the same product on a modern stack, not a new product inspired by the old one. Then invert the usual order of work.
Structure first, code last
Agents inventory, trace and score the legacy estate before anyone migrates anything.
Plans are the unit of review
Agents draft bounded migration plans; humans review plans, not piles of generated diffs. A reviewed plan is the best structured prompt your team will ever write, which is why nobody on the team needs to be a prompt engineer.
Parity is machine-generated evidence
not two developers reading two codebases side by side. Agents generate the checks; humans review the flags.
Contracts replace coordination
An agent cannot sit at the table in your standup. Every cross-team dependency you replace with a written, mocked contract is a dependency an agent can work against, and a meeting you no longer schedule.
Reading route Tech
Every modernization starts the same way, and the start is a trap.
Phase 01 · The honeymoon
The new codebase is clean. There is no technical debt, the tooling is modern, the first features land fast. It is genuinely easier to work in the new system, so early velocity is high and everyone extrapolates from it. Steering committees see the first demo in week three and pencil in a cutover date.
Phase 02 · The middle
Now two systems exist. Every legacy change made by the team still running the old system widens the gap. Feature parity stops being a list someone wrote once and becomes a moving target nobody owns. Developers spend their days reading both codebases side by side, trying to establish whether an edge case in a twelve-year-old service was intentional, load-bearing, or dead. The work that felt like building now feels like archaeology, and velocity decays exactly when the burn-down chart says it should be accelerating.
Phase 03 · The asymptote
The business asks the only question that matters — when can we switch the old one off? — and nobody can answer it with evidence. Parity is asserted, not proven. The last 20% of behavior costs more than the first 80%, the rewrite becomes a permanent second system, and the organization now maintains both. This is how rewrites die: not with a failed deploy, but with a parity question nobody can answer.
AI agents change this, but only if you aim them at the trap rather than at the honeymoon. Pointed at “write the new code faster,” agents accelerate you into the middle and leave you there with more unreviewed code. Pointed at evidence, planning and verification, they attack the three places rewrites actually die.
Reading route Tech
We run agent-driven modernization as a control loop with four stations. Work flows forward; evidence flows back. Humans own intent and exceptions; agents own bounded execution; plans carry the context; parity evidence closes the loop.
Station 01 · Evidence
Station 02 · Evaluation
Station 03 · Control
Station 04 · Operation
Before anything is migrated, the legacy estate is turned into something agents can reason over.
Ingestion. The legacy codebase is indexed locally, with embeddings and retrieval running inside your environment and zero data egress. For most enterprises this is not a nice-to-have: it is the difference between the security review approving the program and killing it.
Surface enumeration. Agents extract the real inventory: every endpoint, screen, scheduled job, integration and infrastructure resource. Not the architecture diagram from 2019, but the surface that actually exists in the code. This inventory is the denominator of every parity claim you will ever make.
Dependency tracing. Agents trace each unit of the surface through the coupling (static helpers, service locators, inline SQL, shared state) until its true blast radius is known. This is exactly the work that exhausts senior engineers when done by reading, and it is where retrieval-equipped agents are disproportionately strong.
The inventory is scored, not eyeballed. A composite score per unit weighs:
The scores sequence the work into waves: bounded batches, ordered so that early waves build the safety net and the reusable patterns that later, riskier waves depend on. Sequencing is a decision your architects review, and they review it holding a scored inventory rather than a hunch.
For each wave, agents draft a migration plan in plain Markdown: what moves, what it depends on, what the target shape is, what parity checks prove it, what is explicitly out of scope. Humans review the plan the way they review a pull request: asynchronously, in version control, with line-level comments.
This station is the answer to a question every engineering leader asks about AI adoption: does everyone now need to be a prompt engineer? No. The process develops the plans, and the plans are the prompts: structured, reviewed, versioned, reusable. The skill your developers exercise shifts from crafting clever instructions to judging whether a plan is correct, complete and safely bounded. They become process managers, leaders of an agent workforce, rather than authors of individual prompts. That is a role senior engineers already know how to do, because it is code review moved one level up.
A plan is only approved when a human signs it. This is not ceremony. It is the control in the control loop, and the moment it becomes rubber-stamping, you have automated your way back into the trap.
Agents execute approved plans, and only approved plans. Execution is bounded: one wave, one plan, one reviewable outcome.
Verification is layered, and machines generate it.
Response and rendering diffs. New implementation against old, same inputs, compared automatically: response payloads for services, rendered output for interfaces.
Contract tests. Agents generate parity tests from the enumerated surface itself (endpoint signatures, screen states), so coverage tracks the inventory instead of somebody's memory.
Shadow traffic. Where the risk justifies it, real production traffic is replayed against the new system before it owns anything.
Failures do not block the pipeline silently and do not get auto-fixed silently. Each flag routes to a human with the evidence and a proposed fix attached. Humans stop reading two codebases looking for differences; they adjudicate differences that machines already found.
The loop closes here: parity results feed the next wave's planning, scores get recalibrated, and, critically, the cutover question finally has an answer that is a dashboard, not an opinion.
Reading route Tech
The control loop works because of four decisions underneath it. Every gain we have seen in agent-driven modernization traces to one of these, not to a bigger model.
The instinct with agents is to start generating immediately, because generating is what they visibly do well. Resist it. Discovery, tracing and scoring before any code means every hour of agent execution lands inside a reviewed boundary. Weeks one and two of a structured program produce inventories, scores and plans rather than features. That is politically harder and structurally far cheaper than the alternative, because unreviewed early code is where rework compounds.
Context is the multiplier on everything an agent does, and it cuts both ways. An agent with retrieval over your indexed legacy code, your module library and your conventions produces work that fits your system. An agent without that context does not merely produce less useful work: it actively manufactures technical debt, regenerating from scratch what already exists and amplifying every duplication it finds. We have watched teams point a coding assistant at a migration without exposing their shared module repository; the assistant rebuilt the modules, badly, in every place it needed them.
Practically this means:
Cross-team dependencies are where both human throughput and agent throughput go to die. A frontend team blocked on a backend team loses days per handoff; an agent blocked on “ask the other team what the response looks like” is simply stuck, because an AI cannot sit at the table and talk about what's next.
The fix is old, and agents make it newly decisive: write the contract first and mock it. An interface specification with a mock server in front of it lets both sides, and both sides' agents, ship from day one against the same verifiable target. Handoff latency drops from days to minutes, and the teams align on a single goal instead of negotiating sequence. Reducing cross-team dependencies is not a reorg nicety here; it is what converts coordination into something automatable.
Parity is the currency of a modernization. If you cannot prove it, you cannot cut over, and everything else was expensive motion. Build the verification harness (diffing, contract tests, shadow replay) as part of the program, not as a QA afterthought, and let agents generate the checks from the enumerated surface. The division of labor that scales is: agents generate the checks, humans review the flags.
Reading route Act
The day-to-day shifts from writing migration code to reviewing plans, adjudicating parity flags and steering the next wave. Seniority expresses itself as judgment, which is exactly the scarce resource you were trying to scale.
The pipeline produces the plans; the plans are the structured prompts. One person who is brilliant at prompting is a bus factor, not a strategy.
From “read this 400-line diff” to “is this wave's plan bounded, complete and safe”, and separately “is this parity flag a bug or an intentional behavior we must preserve”.
Fewer synchronization meetings, more contracts, queues and dashboards. The organization aligns on one goal, provable parity on the new stack, instead of aligning on each other's calendars.
Reading route Tech
The structured program's first demo is an inventory and a scored plan, not a feature. You will defend that in a steering committee. The unstructured program demos a feature in week three and cannot answer the cutover question in month nine. Decide which conversation you would rather have.
Engineers in a legacy codebase see things they itch to redesign. Inside a wave, the answer is no: parity first, improvement after evidence. The discipline feels conservative; it is what keeps the parity claim provable. Park the redesigns in a backlog that activates after cutover.
Indexing the estate inside your boundary costs setup time that a cloud-hosted shortcut would not. In any regulated or confidentiality-sensitive environment, the shortcut is not actually available, and the local pipeline is what makes the program approvable at all.
Diffing, contract generation and shadow replay are real engineering investments that produce no user-visible features. They are also the only thing that ever lets you switch the legacy system off. Fund them as the product of the program, because they are.
Reading route Act
Watch for these; each one is observable and each one has a specific repair.
Parity tracking drifts back into spreadsheets and memory.
Repair
No wave closes without machine-generated parity results attached; the dashboard is the definition of done.
Generated code rebuilds shared modules instead of importing them. This is a context gap, not an agent quality problem.
Repair
Re-index, re-expose the library, and regenerate.
Approval latency drops to minutes and comments disappear. The control is now theater; the loop is open.
Repair
Sample-audit approved plans, rotate reviewers, make plan quality a named responsibility.
Each wave carries a little more scope than the last until “bounded execution” is a memory.
Repair
Hard wave-size limits enforced at planning, not at retrospective.
One person hand-crafts increasingly elaborate prompts outside the pipeline, and results depend on their availability.
Repair
Fold whatever they learned into the plan templates; the process, not the person, is the asset.
“While we're in there” grows past roughly a fifth of the work, parity stops being the goal, and you are now building a new product with a legacy anchor tied to it.
Repair
Route new asks to the post-cutover backlog, or consciously re-scope the program as product development, with different economics and different promises.
Reading route Exec
Use this as a gate, honestly, before you commit:
| Fit criterion | Fits this strategy | Does not fit |
|---|---|---|
| New business requirements | ≤ ~20% of target scope | Substantially new product |
| Feature structure | Screens, workflows, endpoints map roughly 1:1 | Consolidation or re-imagination |
| Legacy as specification | Business rules readable; ~80%+ of target derivable from legacy | Behavior undocumented and unreadable |
| System count | One system in, one system out | Several systems merging into one |
The second is a legitimate program; it is just a design program, and it needs discovery, product decisions and different verification, not a parity pipeline.
Reading route Act
≈6 weeks
Both tracks run at the same time.
Track 1
Pick a single feature domain and run it through the whole loop on real code: ingest, enumerate, trace, score, plan, human review, bounded execution, machine-verified parity. The output is go/no-go evidence, not a slideware pilot.
Track 2
While the slice runs, tune the agents and retrieval to your codebase, design the wave plan, the review gates, the verification harness and the team process.
By the end of the proof you hold verified parity on real code plus the complete toolkit to scale across the estate. That turns “should we modernize with agents” from a debate into a decision you have already piloted.
Reading route Exec
Practitioner observation · Not an audited benchmark
Ranges from modernization programs run this way, offered as practitioner observation rather than audited benchmark: endpoint migration throughput improving by roughly an order of magnitude once the pipeline is running; architecture-compliance audits that took weeks of manual review completing in hours when agents execute the checks in parallel across the estate; and frontend/backend handoff latency collapsing from days to minutes once a mocked contract replaces coordination.
weekshours
Architecture-compliance audits, once agents run the checks in parallel
daysminutes
Frontend and backend handoff latency, once a mocked contract replaces coordination
≈10×an order of magnitude
Endpoint migration throughput, once the pipeline is running
Your numbers will depend on how conventional the legacy codebase is, how much of its surface is mechanically discoverable, and how disciplined wave scoping stays.
Reading route Tech
Method
This guide generalizes IH Tech's operating model for AI-agent-driven modernization: local retrieval over an indexed legacy estate, agentic discovery and dependency tracing, scored wave planning, human plan review, bounded execution, and machine-generated parity verification.
Assumptions
The legacy surface is mechanically discoverable (conventional routing, enumerable screens and resources); the organization can staff plan review with people empowered to reject; production traffic or business criticality data exists to feed scoring where test coverage is weak; the environment permits local indexing infrastructure.
Limitations
The throughput observations above are not controlled studies; they come from programs where the fit criteria held. This strategy is explicitly not designed for product re-imagination, multi-system consolidation, or estates where the legacy code cannot serve as a behavioral specification. Model and tooling capabilities continue to shift; the structural principles are the durable part of this guide, and specific tool choices are not.
Corrections
If you believe something here is wrong, tell us. Corrections reach us through the contact route on ihtech.ba, and this guide's modified date changes when its content does.
This guide last changed on