Refactor when maintenance cost, operational risk, or blocked product growth outweighs the transformation cost. Otherwise, retain, retire, or replatform. That’s the decision in one sentence.
The practical method: start with characterization tests to pin down current behavior, make small reversible commits, and use the Strangler Fig pattern to migrate functionality in waves rather than rewriting everything at once. Three immediate actions before you touch a single line of production code:
- Inventory your surface area (repos, APIs, jobs, data stores, owners)
- Add characterization tests to capture what the system actually does
- Build a CI/CD pipeline with rollback gates before any refactor commit lands
The AWS wave-based refactoring framework organizes this work into discovery, analysis, and incremental implementation waves, each with acceptance criteria before you move forward.
Table of Contents
- Discovery: what do you actually have?
- Characterization tests: pin down behavior before changing anything
- Safe refactor practices: commit rules and common patterns
- Strangler Fig pattern and wave-based migration to AWS
- Prioritization and measurable signals to track progress
- Tools for large-scale, cross-repo refactors
- Operational and organizational workstreams
- Execution checklist and sample wave plan
- Key Takeaways
- What running 700+ migrations actually teaches you
- IT-Magic takes full ownership of your AWS migration
- Useful sources and further reading
- FAQ
Discovery: what do you actually have?
You cannot safely refactor what you haven’t mapped. Run discovery as a structured sprint before any code changes.
- Pull repo access and catalog every service, library, and shared module
- Trace runtime behavior: collect logs, APM traces, and API call graphs under real load
- Inventory all jobs, cron tasks, event consumers, and batch processes
- Map data flows: which services share a database, which write to the same tables
- Interview stakeholders to identify undocumented integrations and ownership gaps
Sourcegraph is the right tool for cross-repo code search at scale. It lets you find every callsite for a function, every import of a module, and every reference to a deprecated API across dozens of repositories in seconds. Pair it with runtime traces and dependency analyzers to build a capability map grounded in evidence, not just diagrams.
Your deliverable: a validated capability map that ties each bounded context to its runtime evidence, data dependencies, third-party integrations, and named owner.
Pro Tip: Treat the capability map as a living document. Update it after every wave. Stale maps are worse than no maps because teams trust them.
Characterization tests: pin down behavior before changing anything
The first job on legacy code is testing, not refactoring. Characterization tests (also called golden-file or approval tests) capture what the system actually does today, including the odd behaviors you don’t fully understand yet.
The workflow is straightforward:
- Call the unit or endpoint with realistic inputs
- Capture the output (JSON, rendered HTML, file, database state)
- Commit that output as the “golden file”
- Configure CI to fail if the output changes
ApprovalTests libraries support this pattern in Java, C#, Python, and JavaScript. For large structured outputs, store them as versioned files in the repo alongside the test.
When you encounter behavior that looks wrong, document it and open a separate ticket. Do not fix it during the refactor commit. Mixing behavior changes with structural changes destroys bisectability and makes rollback ambiguous.
Pro Tip: Add property-based assertions for critical invariants (e.g., “total always equals sum of line items”) alongside golden-file tests. They catch regressions that exact-match snapshots miss.
Safe refactor practices: commit rules and common patterns
Refactoring risk comes from step size, not end state. Keep commits small enough that a reviewer can read the diff in under five minutes and a failing test can be bisected to a single change.
The commit discipline:
- Commit 1: Add characterization tests (no production code changes)
- Commit 2: Structural refactor only (rename, extract function, introduce seam) with tests still green
- Commit 3: Behavior change, if needed, in a separate commit with its own test
Common safe refactors to start with:
- Extract function: pull a block of logic into a named function with a clear contract
- Introduce seam: replace a hard-coded dependency with an injected interface
- Rename: align names with the domain language your team actually uses
- Extract class: separate unrelated responsibilities that share a single file
Martin Fowler’s refactoring catalog remains the canonical reference for these patterns. The SOLID-focused approach described in large-scale refactoring research confirms that applying recurring patterns systematically across thousands of files reduces architectural debt at scale.
If you find a bug during a refactor, stash the fix, complete the structural commit, then apply the fix separately. Keeping those concerns apart is what makes the history useful.
Strangler Fig pattern and wave-based migration to AWS
The Strangler Fig pattern solves the moving-target problem that kills big-bang rewrites. You build new behavior incrementally at the edge while the legacy system keeps running, then route traffic to the new path once it’s proven.
The sequence for each capability slice:
- Add a facade: deploy Amazon API Gateway in front of the legacy endpoint
- Implement one path: build the new behavior in AWS Lambda or a containerized service on Amazon EKS / AWS Fargate
- Route via feature flag: send a controlled portion of traffic to the new path
- Monitor metrics: confirm error rates and latency stay within SLO
- Expand traffic incrementally with canary waves, starting small and increasing gradually
- Delete the legacy slice once the new path is stable at full traffic
For data, move to Amazon Aurora (PostgreSQL-compatible) using dual-write during the transition period. The AWS prescriptive guidance provides wave templates and capability matrices for exactly this pattern.
Pro Tip: Feature flag toggles must revert end-to-end, not just at the front end. If the flag rolls back the API route but leaves the new Lambda writing to the new database, you have a split-brain state. Test the full rollback path before each wave.
Prioritization and measurable signals to track progress
Metrics tell you whether modernization is changing the estate or just generating activity. Track a small set that both engineers and leadership can read.
| Metric | What it measures |
|---|---|
| % traffic on new path | Routing progress per capability |
| Legacy callsite count | Remaining references to deprecated code |
| Deployment frequency | CI/CD health and release cadence |
| Error rate vs. SLO | Stability of new path under real traffic |
| Support ticket volume | Operational toil reduction over time |
Wave acceptance criteria example: measurable reduction in old endpoint usage, majority of traffic routed to new path, error rates within agreed service levels, and at least one successful rollback drill completed. The Sourcegraph wave-based modernization guide recommends sourcing callsite counts directly from code search results so the metric is reproducible and not dependent on manual counts.
Pick five metrics maximum. A dashboard nobody trusts is worse than no dashboard.
Tools for large-scale, cross-repo refactors
The right tool depends on the scope and language of the transform.
- Sourcegraph: — Cross-repo code search and Batch Changes for staged, reviewable codemods across dozens of repos
Never run a large mechanical transform without reviewable diffs and a targeted test run. The pattern: scope the codemod narrowly, generate the diff, review a sample, run the full test suite, then merge in batches with code-review gates.
Pro Tip: OpenRewrite recipes are composable. Build a library of organization-specific recipes for your most common patterns (logging framework migration, deprecated API replacement) and reuse them across every wave.
| Tool | Best for | Language scope |
|---|---|---|
| Sourcegraph | Cross-repo search and staged batch changes | All |
| OpenRewrite | AST-safe recipe-based transforms | JVM |
| Codemod | Mechanical syntax and import updates | Broad |
| GitHub Copilot | Low-risk generation and boilerplate | All |
Operational and organizational workstreams
Modernization that covers only code recreates fragility. CI/CD, monitoring, disaster recovery, and data integration must be upgraded alongside every refactor wave.
Ops checklist per wave:
- CI gates: characterization tests and integration tests must pass before merge
- Incremental rollout: feature flags, blue/green, or canary configured before the wave starts
- Observability: structured logs, metrics, and distributed traces in place for the new path
- DR and backups: recovery procedures tested and documented for the new architecture
- Incident runbooks: updated before the wave goes live, not after
For database schema changes, use dual-write during the transition: write to both old and new schemas, validate consistency with a reconciliation job, then cut reads over once parity is confirmed. Change-data-capture tools (AWS Database Migration Service, Debezium) handle this reliably at scale.
Organizationally, assign a cross-functional wave team (engineer, QA, product owner, on-call lead) for each wave. Document ownership explicitly. Communicate the wave plan and rollback criteria to business stakeholders before each cutover, not during an incident.
Execution checklist and sample wave plan
Execution checklist:
- Inventory repos, APIs, jobs, data stores, and owners
- Add characterization tests for the target capability
- Introduce seams (dependency injection) to isolate the slice
- Make small structural refactor commits, tests green throughout
- Deploy facade (Amazon API Gateway) and new implementation
- Enable feature flag at 5% traffic; monitor for 24 hours
- Expand to 25%, 50%, 100% with metrics verification at each step
- Delete legacy slice after 100% traffic stable for 72 hours
| Capability | Dependencies | Complexity | Business value | Wave | Acceptance criteria |
|---|---|---|---|---|---|
| Auth service | Low | Low | High | 1 | 70% traffic on new path, error rate within SLO |
| Order processing | Medium | Medium | High | 2 | 80% callsite reduction, dual-write parity confirmed |
| Reporting pipeline | High | High | Medium | 3 | Full cutover, legacy batch jobs retired |
For teams moving to AWS, the developer-focused refactor guide covers Lambda, API Gateway, and EKS patterns in detail. The monolith-to-microservices guide is the right companion for wave 3 complexity.
Key Takeaways
Refactoring legacy applications safely requires characterization tests before any code changes, small reversible commits, and the Strangler Fig pattern to migrate in waves with measurable acceptance criteria at each step.
| Point | Details |
|---|---|
| Refactor only when ROI justifies it | Score systems on business impact, coupling, and operational cost before committing to refactor. |
| Characterization tests come first | Pin down current behavior with golden-file tests before touching any production code. |
| Small commits, one concern each | Separate test commits, structural refactors, and behavior changes to keep history bisectable. |
| Strangler Fig with canary waves | Route traffic in gradual increments (for example, 5%, 25%, 50%, up to 100%) with feature flags and rollback drills at each step. |
| IT-Magic for hands-on execution | IT-Magic’s 700+ AWS migrations cover discovery through post-migration optimization with zero-downtime delivery. |
What running 700+ migrations actually teaches you
The most common failure mode isn’t a bad architecture decision. It’s large commits. Teams under deadline pressure batch up two weeks of changes into a single PR, the test suite catches something, and nobody can bisect which change caused it. The refactor stalls, confidence drops, and the project either gets abandoned or pushed through with fingers crossed.
The second failure mode is the moving target: the legacy system keeps receiving feature requests while the new path is being built, so the new path is always slightly behind. The Strangler Fig pattern addresses this structurally by routing at the edge, but it only works if the team has the discipline to freeze feature development on the legacy slice during the wave. That requires a communication plan with product and business stakeholders, not just a technical decision.
What actually works is treating modernization as an ecosystem problem. Code is one layer. CI/CD, observability, on-call runbooks, and team ownership are the other layers. Teams that modernize only the code and leave the deployment and monitoring infrastructure unchanged end up with new code running in an old operational model. The fragility moves, it doesn’t disappear.
Small wins matter more than people expect. A single capability migrated cleanly, with metrics proving it, builds more organizational confidence than a six-month plan presented in a slide deck.
IT-Magic takes full ownership of your AWS migration
Zero-downtime AWS migration with full execution ownership is what IT-Magic delivers. Where most teams struggle with the gap between a refactor plan and a production-ready AWS architecture, IT-Magic closes that gap directly: discovery, wave planning, refactor execution, CI/CD modernization, data migration, and post-migration optimization are all included in a single fixed-price engagement.
For high-load eCommerce and fintech environments, where a botched cutover means lost revenue, IT-Magic’s track record across 700+ completed projects is the relevant proof point. The approach is the same one described in this article: characterization tests first, Strangler Fig routing via Amazon API Gateway and Lambda, canary waves with rollback drills, and measurable KPIs at every step.
Request a free migration audit or review the AWS migration best practices guide to see the execution framework in detail.
Useful sources and further reading
- Strangler Fig Application
- Characterization test — Wikipedia
- Lift and shift vs modernization — Microsoft Learn
- Refactoring legacy code without breaking it | Codably
- Legacy code modernization — Sourcegraph
- Wave-based refactoring — AWS prescriptive guidance (PDF)
- Experience report on applying SOLID principles for large-scale refactoring — ScienceDirect
- The Archaeologist’s Copilot — Martin Fowler
| Tool / Service | Documentation |
|---|---|
| AWS Lambda | docs.aws.amazon.com/lambda |
| Amazon API Gateway | docs.aws.amazon.com/apigateway |
| Amazon Aurora | docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide |
| Amazon EKS | docs.aws.amazon.com/eks |
| AWS Fargate | docs.aws.amazon.com/AmazonECS/latest/userguide/what-is-fargate |
FAQ
When should you refactor instead of rehosting a legacy app?
Refactor when the system is hard to change, costly to run, or blocking product growth, and when the domain is stable enough to justify the investment. Rehost when the primary goal is infrastructure cost reduction and the code itself doesn’t need to change.
What are characterization tests and why do they matter?
Characterization tests capture what a system currently does by recording its outputs as golden files, then failing CI if those outputs change. They are the primary safety net for refactoring legacy code that has no existing test coverage.
How does the Strangler Fig pattern reduce migration risk?
It routes requests through a facade (such as Amazon API Gateway) and incrementally replaces one capability at a time, so the legacy system keeps running until the new path is proven at full traffic. Canary waves with gradual increments (such as 5%, 25%, 50%, and 100%) with rollback drills at each step keep the blast radius small.
Which tools handle large-scale refactors across many repositories?
Sourcegraph handles cross-repo search and staged batch changes. OpenRewrite runs AST-safe recipe-based transforms for JVM codebases. Codemod covers broader language support for mechanical syntax updates. GitHub Copilot is useful for low-risk generation tasks but should not make unconstrained architectural decisions.
How does IT-Magic support refactor-first AWS migrations?
IT-Magic covers the full lifecycle: discovery, wave planning, refactor execution using Strangler Fig and AWS services, CI/CD modernization, data migration to Amazon Aurora, and post-migration optimization, all under a fixed-price engagement with zero-downtime delivery as the standard.