Modernize Legacy System

Modernize Legacy System

Estimated time: 4-12 weeks

This workflow guides engineering teams through the disciplined process of modernizing a legacy system. Rather than a risky big-bang rewrite, this workflow follows the proven strangler fig pattern: assess the current state, build a safety net of tests, refactor incrementally, containerize, and establish modern CI/CD practices.

Each step is designed to reduce risk. You build confidence through understanding before changing code, add tests before refactoring, and containerize before deploying to new infrastructure.

By the end of this workflow you will have: a comprehensive understanding of your codebase's health, a prioritized tech debt remediation plan, refactored code with test coverage, Docker containers, and a CI/CD pipeline for safe ongoing deployment.

When to Use

• User wants to modernize legacy system
• User needs a structured, step-by-step process for modernize legacy system
• modernize my legacy system
• how to refactor old code
• migrate legacy application
• Do NOT use when: the request is outside the scope of modernize legacy system or requires professional advice beyond educational guidance
• Do NOT use for single-step tasks that one atomic skill can handle independently

Prerequisites

Before starting this workflow, ensure:

• Access to the legacy system's source code and version control
• Ability to run the system locally or in a development environment
• Knowledge of the system's business purpose and critical paths
• Stakeholder buy-in for dedicated modernization time
• At least one developer who understands the existing system

Steps

Step 1: Review the Codebase (uses: code-reviewer)

perform a comprehensive assessment of the legacy codebase. This is a diagnostic step -- understand before you change.

• Input: Access to the legacy codebase and its repository history, Any existing documentation (even if outdated), Knowledge of the system's primary use cases and critical paths
• Output: Comprehensive health report of the legacy system, Third-party dependency versions, vulnerabilities, and upgrade paths, Current system architecture documentation
• Key focus: Code structure analysis (module organization, dependency graph)

Step 2: Analyze Technical Debt (uses: tech-debt-analyzer)

quantify and prioritize the technical debt in the system.

• Input: codebase-assessment from Step 1 (code quality findings), dependency-audit from Step 1 (outdated and vulnerable dependencies), critical-paths from Step 1 (business-critical areas to protect)
• Output: Categorized and prioritized technical debt register, Quantitative measurements of code health, Phased plan for debt reduction with effort estimates
• Key focus: Categorizing debt by type (design debt, code debt, test debt, dependency debt,

Step 3: Refactor the Code (uses: refactoring-guru)

systematically refactor the codebase. This is the core transformation step.

• Input: debt-inventory from Step 2 (what to refactor, in priority order), remediation-roadmap from Step 2 (phasing and sequencing), critical-paths from Step 1 (areas requiring extra caution)
• Output: Record of all refactorings applied with rationale, Updated codebase with improved structure and quality, Documentation of architectural changes made
• Key focus: Starting with the highest-priority, lowest-risk refactorings

Step 4: Build the Test Safety Net (uses: unit-test-writer)

build a comprehensive test suite that serves as a safety net for ongoing changes.

• Input: critical-paths from Step 1 (highest-priority areas for test coverage), codebase-assessment from Step 1 (existing test gaps), refactored-code from Step 3 (refactored code to protect with tests)
• Output: Comprehensive test suite covering critical paths, Code coverage metrics with gap analysis, Testing standards and patterns for the team
• Key focus: Characterization tests for legacy code (capture current behavior before changing it)

Step 5: Containerize the System (uses: docker-engineer)

containerize the modernized application.

• Input: architecture-map from Step 1 (system components to containerize), dependency-audit from Step 1 (runtime dependencies to include), refactored-code from Step 3 (the modernized codebase)
• Output: Production-ready Dockerfiles for all components, Docker Compose for local development, Guide for transitioning from bare-metal to containerized deployment
• Key focus: Creating Dockerfiles for each service component

Step 6: Establish CI/CD Pipeline (uses: cicd-architect)

establish automated build, test, and deploy pipelines.

• Input: test-suite from Step 4 (tests to run in CI), dockerfiles from Step 5 (container builds for the pipeline), architecture-map from Step 1 (deployment topology)
• Output: CI configuration with all quality gates, CD configuration with staging and production environments, Procedures for rolling back failed deployments
• Key focus: CI pipeline: lint, build, test, security scan on every push

Decision Points

• After Step 2: What modernization strategy will you follow?
  • If Incremental refactoring (strangler fig): Safest approach. Refactor piece by piece while keeping the system running. Recommended for most cases.
  • If Parallel rewrite: Build a new system alongside the old one. Higher risk, but necessary when the codebase is beyond refactoring. Step 3 focuses on the new codebase.
  • If Lift and shift first: Containerize the legacy system as-is first, then refactor in containers. Good when infrastructure modernization is the priority.

Failure Handling

• Big-bang rewrites: Rewriting from scratch fails more often than it succeeds. Refactor incrementally.
• Refactoring without tests: Never refactor code that is not under test. Write tests first.
• Boiling the ocean: Do not try to fix everything at once. Follow the prioritized roadmap.
• Ignoring the team: Modernization requires team buy-in. Communicate the plan and progress regularly.
• No metrics tracking: Without before-and-after metrics, you cannot prove the investment was worthwhile.

Expected Outcome

When this workflow is complete, the user will have:

1. Code quality metrics show measurable improvement over the starting baseline
2. Critical business paths have automated test coverage
3. The system runs in containers with automated deployment
4. The team can deploy to production confidently and frequently
5. Technical debt has been reduced to manageable levels
6. The system is easier for new developers to understand and contribute to

Output Format

MODERNIZE LEGACY SYSTEM TRACKER
===============================

[ ] Step 1: Review the Codebase
    Status: [pending/in-progress/complete]
[ ] Step 2: Analyze Technical Debt
    Status: [pending/in-progress/complete]
[ ] Step 3: Refactor the Code
    Status: [pending/in-progress/complete]
[ ] Step 4: Build the Test Safety Net
    Status: [pending/in-progress/complete]
[ ] Step 5: Containerize the System
    Status: [pending/in-progress/complete]
[ ] Step 6: Establish CI/CD Pipeline
    Status: [pending/in-progress/complete]

Timeline: ______ weeks
Overall Status: [IN PROGRESS / COMPLETE]

Adaptation notes:

• Adjust timeline based on user's availability and prior experience
• Steps may be reordered if dependencies allow parallel execution
• Skip optional steps if time or budget is constrained

Edge Cases

• Big-bang rewrites: Rewriting from scratch fails more often than it succeeds. Refactor incrementally.
• Refactoring without tests: Never refactor code that is not under test. Write tests first.
• Boiling the ocean: Do not try to fix everything at once. Follow the prioritized roadmap.
• Ignoring the team: Modernization requires team buy-in. Communicate the plan and progress regularly.

Example

Input: "I want to modernize legacy system and need a structured plan to follow step by step."

Output:

Step 1 (code-reviewer): Review the Codebase -- produces concrete deliverables for this phase.

Step 2 (tech-debt-analyzer): Analyze Technical Debt -- produces concrete deliverables for this phase.

Step 3 (refactoring-guru): Refactor the Code -- produces concrete deliverables for this phase.

Step 4 (unit-test-writer): Build the Test Safety Net -- produces concrete deliverables for this phase.

Step 5 (docker-engineer): Containerize the System -- produces concrete deliverables for this phase.

Step 6 (cicd-architect): Establish CI/CD Pipeline -- produces concrete deliverables for this phase.

Result: User has a complete modernize legacy system plan with all deliverables produced, validated, and ready for implementation.