Originally published on the AWS Builder Center. Republished here with light formatting adjustments.
TL;DR — Transformation isn’t new; AI just makes it faster. The same five-phase framework (Assessment → Target roadmap → Preparation → Transformation → Validation) still applies. We put it to the test on a real legacy PHP app: after training on AWS Transform Custom + Kiro and a throwaway practice run, the production transformation ran in one hour. But “transformed” isn’t “working” — auth, Docker, env vars, and dependency conflicts all traced back to documentation gaps, not AI failures. We closed the last ~30% in Kiro and had screens running end-to-end (DB, schema, backend, new UI) in ~6 hours total. The lesson: your document corpus is the product, and the test harness belongs in phase 3, not at the end.
I keep hearing the same thing from customers: “Modernization preparation takes too much time.”
It’s a fair complaint. Before AI, the preparation alone could eat a quarter — RFPs, procurement, hunting for a contractor specialized enough (and willing) to touch a legacy application. Months of overhead before a single line of code changed.
But here’s the thing I want to establish up front: transformation is not new. AI accelerates the process — it doesn’t change it. We don’t need to reinvent how we modernize applications. We already have a framework. What AI changes is the speed at which we can run it.
Let me lay out that framework, and then show you what happened when we applied it to a real legacy PHP application.
The Framework: Five Phases
1. Assessment
You can’t transform what you don’t understand. Build the application inventory, group by affinity and tier, run a technology deep dive, and document the target architecture.
2. Target roadmap definition
Select your technologies, lock the target architecture, and identify the major transformation patterns you’ll apply repeatedly.
3. Transformation preparation
Pick the first application. Stand up the transformation environment (CI/CD, DevXP). Schedule the trainings. This is where momentum is won or lost.
And this is where validation actually starts. Don’t treat validation as the finish line — build a solid test harness at the very beginning, one designed to survive the modernization. You’ll need it twice: once to characterize the legacy application’s behavior, and again to prove the modernized system behaves identically. Let AI do the heavy lifting here — point it at the legacy codebase to identify the use cases, map the scenarios, and generate the automation.
4. Transformation
Run your tools and scripts and let them do the heavy lifting — AWS Transform Custom, Kiro, custom tooling. Then fix the remaining untransformed code manually.
5. Validation
Run that same harness against the modernized application. Tests, QA, the quality gate, cutover. The moment your early investment pays off.
Underneath all five phases now runs a layer of AI tools and accelerators — AWS Transform Custom, Kiro, custom tooling — compressing the timeline at every step.
That’s the framework. Now here’s what it looks like in practice.
The Framework in Practice: A Legacy PHP Modernization
We started with training, then practiced on something safe
Before touching anything real, the team did Immersion Days to get hands-on with AWS Transform Custom and Kiro. Then we grabbed a GitHub PHP application and built a transformation to take it from legacy PHP to a modern PHP architecture.
We reviewed the output, assessed the gaps — and immediately learned the first lesson: our prompts and supporting documents weren’t accurate enough. So we iterated. The dry run was the point. It taught us how much the quality of the input corpus drives the quality of the output.
Then came the real application
For the production application, we built a complete document corpus and had the important conversation up front: how many iterations do we run? Do we build a test harness first?
Here’s where reality met ambition. The team wanted to move fast. They opted for a single transformation to do the whole job — no test harness — to measure raw accuracy with minimal preparation.
The transformation itself? Done in one hour with AWS Transform Custom.
And then the problems started (this is the useful part)
One hour to transform. But “transformed” isn’t “working.” The gaps were almost entirely about context the AI never had:
- Security & authentication weren’t defined with clear samples in the docs — so the AI generated its best guess of what auth should look like.
- The company’s Docker setup had no documentation, and some environment variables were simply missing.
- The corporate framework required specific config values that weren’t spelled out anywhere.
package.jsonhad dependency conflicts — combining the in-house framework modules needs deliberate dependency management, and the AI couldn’t reliably generate it without a sample to follow.
Notice the pattern: none of these are AI failures. They’re documentation gaps. The model filled the vacuum with plausible guesses — which is exactly what it will do every time you leave one. This is the framework talking back to you: the gaps trace directly to Assessment and Transformation Preparation.
Kiro closed the last 30%
We picked up the remaining ~30% of the work in Kiro — the auth wiring, the env vars, the Docker fixes, the dependency untangling. After roughly 6 hours total, the team had multiple screens working end-to-end: live DB, schema, backend, and a new UI/UX design.
From legacy PHP to a modernized, running app with a fresh UI — in a single working day.
What the Field Test Confirmed About the Framework
- Assessment and preparation are where the outcome is decided. Every gap that showed up in hour two — auth, Docker, env vars, framework config — was a document that didn’t exist in phase 1. The corpus is the product.
- Practice on a throwaway repo first. Your first transformation teaches you about your prompts and docs, not the tool.
- The one-hour transform is real, and so is the last 30%. AWS Transform Custom does the bulk; Kiro is where you finish the job. Budget for both.
- The test harness is not optional — it’s phase 3. The team skipped it to measure raw accuracy fast. That worked as an experiment, but a harness is what turns “the code compiles” into “the behavior is correct.” Build it early and it pays you back at validation.
- Transformation isn’t new. AI accelerates it — it doesn’t change it. The five phases still hold. The difference is you now measure preparation in weeks and transforms in hours, not quarters.
Feed the AI a real corpus, and it’ll take you 70% of the way in an hour. Bring the context it’s missing, and you’ll close the rest in an afternoon.
Read the full article on the AWS Builder Center.
Any opinions in this article are my own and may not reflect the opinions of AWS.