Before AI Changes Your Legacy Code, Make It Show You the Plan

An AI agent can now rewrite a legacy application faster than your team can review the result. That makes the document it writes before touching the code the most important thing it produces.

Microsoft made the point in July with .NET Modernization for Beginners, a free, open-source course built on the GitHub Copilot modernization agent. The course takes a legacy ASP.NET MVC 5 application from .NET Framework 4.8 to .NET 10. Before the agent changes any code, it writes an assessment and a plan. During the upgrade it tracks its work in a task list. The three files are assessment.md, plan.md, and tasks.md, and all of them are plain Markdown you can read, question, and edit. As the announcement puts it, "The agent assists you, but you make the calls."

We have some history here. GAPVelocity AI began as ArtinSoft, the company that built the Visual Basic Upgrade Wizard Microsoft shipped in Visual Studio .NET. That wizard wrote a report too. It arrived after the conversion, listed what the tool couldn't handle, and left UPGRADE_ISSUE comments in your code for someone to clean up. Getting the report first, in a form you can change, is a real improvement.

It only pays off if someone reads the plan critically before approving it. Here are five questions to ask, whether you're the architect who will live with the result or the executive signing the budget. They apply to any AI modernization tool or vendor, ours included.

1. What dependencies did it find?

The assessment exists to answer this. In Microsoft's course, the first chapter has you run the assessment on the sample app and sort its findings into blockers and warnings before any planning starts.

For a .NET Framework application, most dependencies sit in project files and package references, where a tool can see them. Older systems hide theirs. A VB6 or PowerBuilder application can depend on an ActiveX control from a vendor that no longer exists, a COM component registered on one server, business rules buried in stored procedures, or a nightly file drop another department relies on.

A good answer lists every dependency with a decision beside it: keep, replace, rewrite, or retire. It also says what the tool could not see. Be suspicious of an assessment with no unknowns in it.

For budget owners, each blocker without a decision is a cost nobody has priced yet.

2. What behavior has to stay the same?

Old code is full of behavior nobody documented: how invoices round, what a blank date means, which errors get swallowed so the nightly batch finishes. Some of those quirks are bugs. Others are rules the business has run on for twenty years, and the code is the only place they are written down.

An agent can read every line. It has no way to tell which quirks your customers, auditors, or downstream systems count on. That knowledge sits with your people, and an editable plan is where they add it.

Ask for a plain-language list of behaviors the migration must preserve, and a second list of behaviors it will change on purpose. Without those lists the decisions still get made, one generated line at a time, by a tool that was never told what mattered.

3. What will change architecturally?

The plan.md in Microsoft's course recommends a target framework, sequences the upgrade steps, and estimates the effort. Read the first two before you look at the third. An estimate is only as good as the scope underneath it.

Even an upgrade inside the .NET family changes more than a version number. The course moves its sample app to .NET 10 and EF Core, then deploys it to Azure App Service. Web framework, data access, and hosting all move in one project.

When the source is a desktop application headed for the web, the change is larger. Where state lives, how printing works, and what happens to the barcode scanner on the warehouse floor all need an answer.

A good plan says what changes, what stays, and why, in terms your operations team can check. It also draws a line around scope. A migration that redesigns the database along the way is two projects sharing one budget.

For budget owners, architecture sets what the system costs after go-live: hosting, licensing, and retraining. Ask for those figures alongside the migration price.

4. How will correctness be tested?

A successful build is the weakest evidence that a migration worked. Microsoft's documentation describes the modernization tooling validating builds, running tests, and scanning for known vulnerabilities after an upgrade. Those checks are worth having. They also reach only as far as your existing tests do, and most legacy applications have few tests or none.

So ask what the evidence will be. The strongest kind is behavior captured from the old system before the migration starts: recorded inputs and outputs, report totals, the state of the database after a known set of transactions. Run the same cases against the new system and compare.

Watch for tests written after the fact by the same agent that wrote the code. They show that the new code agrees with itself and tell you nothing about whether it matches the system you are replacing.

Ask who signs off, too. The plan should name a person from the business, with acceptance criteria written down before execution begins.

5. What happens if the migration fails?

Every plan describes the path where things work. Ask for the other one.

Technical reviewers should ask where the work happens and how far back they can go. Is it on its own branch? Is each finished task committed separately, so you can return to the last good state? Which steps can't be undone? Schema and data changes are the usual culprits, and they deserve a rollback script and a dry run.

Microsoft's course treats this as part of planning. Its plan turns assessment findings into ordered tasks with checkpoints between them, and tasks.md shows which step was underway when something broke.

Budget owners should ask what the company owns if the project stops halfway. A half-migrated codebase is worth less than either the old system or the new one. Ask where the exit points are, how long the old system keeps running in parallel, and who pays if the easy majority converts quickly and the work stalls on the hard remainder.

The five questions on one page

Approve the plan, then the work

If your team maintains .NET Framework code, have a developer work through the course repository. Even if you never adopt the tool, seeing what an assessment and a plan look like raises the bar for everything a vendor shows you afterward.

If your application is older than .NET, the five questions still apply. VB6, PowerBuilder, Access, Clarion, and Delphi systems keep more of what they do outside the code a tool can read, so expect the answers to take longer.

Assessment is the cheapest phase of a modernization, and it is the last point where changing your mind costs almost nothing. Spend the time there.

Sources

• Announcing .NET Modernization for Beginners, .NET Blog, July 16, 2026
• microsoft/dotnet-modernization-for-beginners, course repository on GitHub
• GitHub Copilot modernization overview, Microsoft Learn