Most modernization projects don't fail on the choice of framework. They fail on a handful of early decisions that only show their cost when the new system meets real users. Here are the ten we see most often, and what to do instead.
Most legacy modernization projects don't fail because the new framework is wrong. They fail because of a handful of decisions made early, often in the first planning meeting, that only show their cost months later, when the new system meets real users.
Here are the ten mistakes we see most often on frontend and application modernization projects, and what to do instead. AI agents make some of them faster and easier to make, so we cover those too.
Why legacy modernization projects go wrong
A legacy app is years of decisions, fixes and workarounds that nobody wrote down. The code is the only full record of what the business actually relies on. Modernization means moving all of that onto a new stack while the business keeps running and keeps asking for changes.
That makes it different from a greenfield build. The risk is less about writing new code and more about losing behavior people depend on without noticing. Most of the mistakes below come from treating a migration like a new project.
Planning mistakes
Starting without an inventory
Teams estimate from the folder structure and a few demos. Then they find the second router, the global event bus, the jQuery plugin that patches every form, and the admin screens nobody mentioned.
Do this instead: map every route, component, service, global, dependency and test before you write a plan. A read-only agent can do this quickly and thoroughly. The inventory is the plan's foundation, not a nice extra.
Betting on a big-bang rewrite
Freezing the old app and building the new one alongside it for a long time means two systems, a moving target and a single risky cutover day. The business keeps asking for features, and they land in the old app, widening the gap.
Do this instead: migrate incrementally. Run old and new side by side (the strangler-fig pattern) and move one route or screen at a time, so each step ships to real users.
“[Rewriting the code from scratch is] the single worst strategic mistake that any software company can make.” — Joel Spolsky, Things You Should Never Do, Part I
Rewriting when you meant to migrate
"While we're in there" turns a migration into a redesign. New UX, new data model and new framework all at once means nobody can tell whether a difference is a bug or a feature.
Do this instead: migrate first, with parity as the goal. Improve afterwards, on a stack that's now easier to change. Record any deliberate change in a decisions log.
Build mistakes
Porting without tests that pin down today's behavior
Legacy apps rarely have good tests, so teams port and then click around to check. That misses edge cases: empty states, errors, slow responses, permissions.
Do this instead: write characterization tests from the old code before porting. Run them against the old app first, then against the new one. Lock them once they pass.
Mixing refactoring and porting in one change
A pull request that moves a component to React and renames its props and restructures its state can't be reviewed for parity. Reviewers end up approving on trust.
Do this instead: keep port changes and improvement changes separate. Each one should be small enough to judge in a single pass.
Ignoring hidden wiring
The dangerous behavior in legacy apps lives outside the obvious files: global listeners, mixins, server-rendered data islands, analytics hooks, CSS that depends on DOM order, timers that assume a page reload.
Do this instead: make hidden wiring its own inventory section, and give every item an owner and a destination in the new app before the unit that depends on it is ported.
Letting AI agents port with no gates
Agents produce code fast and with confidence. Without gates, that just means plausible-looking bugs arrive faster. An agent that reviews its own output mostly agrees with itself.
Do this instead: put agents inside a process. Use a shared conventions file, small units, locked tests, and a separate reviewer agent that sees only the old code, the new code and the test results. Nothing merges on the porter's word.
A related trap is running one model for every job. Different stages need different strengths: deep reasoning for planning, speed and volume for porting, and a second model family for review so the checker doesn't share the porter's blind spots.
“Automation applied to an efficient operation will magnify the efficiency. Automation applied to an inefficient operation will magnify the inefficiency.” — Bill Gates, The Road Ahead
Shipping mistakes
No rollback path
Teams cut over and delete the old route the same day. When something breaks, the only way back is a revert and a redeploy under pressure.
Do this instead: put each migrated route behind a flag or a routing switch. Roll out to a small share of traffic, watch errors and key metrics, and keep the old path working until the new one has run cleanly for a while.
Cutting over without parity data
"It looks right" is not evidence. Without numbers, teams can't say whether the new checkout converts the same, loads as fast or sends the same requests.
Do this instead: decide the parity signals up front: error rates, performance, key conversion steps, API call patterns, visual diffs. Compare old and new on those before widening a rollout.
Declaring done too early
The last 10% (the old build pipeline, the dead dependencies, the compatibility shim, the two screens nobody uses) gets dropped when the team moves on. Two years later you're running both frameworks for good.
Do this instead: define "done" as the old framework fully removed from the bundle, the build and the dependency list. Track it in the plan from day one, and don't close the project until it's true.
Warning signs your project is drifting
These mistakes rarely announce themselves. Watch for the symptoms instead:
- Estimates keep growing as the team "discovers" screens, integrations or global code nobody listed.
- The share of the app live on the new stack hasn't moved in weeks, even though plenty of code is being written.
- Bug reports after each release are about things that "used to work".
- Reviews are approved quickly because nobody can tell what changed.
- New features are still being built in the old app.
Any two of these together usually point back to a missing inventory, missing characterization tests or a big-bang plan in disguise.
Where AI agents change the picture
AI agents make several of these mistakes cheaper to avoid. An inventory that used to take weeks of reading is now a read-only agent run. Characterization tests that nobody had time to write can be generated from the old code and checked against it. A second reviewer is always available.
They also make some mistakes faster to make. Agents will happily do a big-bang rewrite, mix refactoring into a port, or edit a failing test until it passes. The process around them, with small units, locked tests and an independent reviewer, matters more with agents, not less.
The pattern behind all ten
Almost every mistake here is a planning or verification shortcut that saves a few days early and costs far more later. The fix is consistent: inventory first, move in small units, verify parity with evidence, and keep a way back.
That's the workflow our MigrateX plugins encode for Angular, AngularJS, Backbone and Ember to React migrations: a read-only inventory, a written plan and unit map, unit-by-unit porting, and an independent parity reviewer on every piece before the old code goes.
Pre-flight checklist
Before the first unit is ported, check that you can tick every line:
Checklist
- Full inventory, including hidden wiring, before any plan or estimate.
- Incremental, strangler-fig migration instead of a big-bang rewrite.
- Parity first, improvements after, with deliberate changes logged.
- Characterization tests written from the old code and locked.
- Small, single-purpose changes; agents behind gates with an independent reviewer.
- Flags and rollback for every cutover, judged on parity data.
- Done means the old framework is gone.
Related reading: how multi-agent AI speeds up application migration, a migration testing strategy with AI agents and software migration lessons from Shopify's AI rewrite.
Originally published on the CobuildX blog.
Top comments (0)