Module 8: Capstone Project — Migrating a Real Legacy Project

Capsule description

This module closes the guide by consolidating all the techniques into a real project from start to finish. Modules 1-7 taught you individual skills: onboarding, exploration, architecture analysis, refactoring, migration, context management, modernization. Module 8 chains them into a complete workflow that reflects how a real migration works in the industry.

You can't migrate a project if you don't understand it (M1-3). You can't refactor without tests and multi-file coordination (M4). You can't migrate a framework without an incremental strategy (M5). You can't work with large projects without context management (M6). And you can't modernize without prioritization and an incremental approach (M7). This module is the proof that you master the whole pipeline.

The deliverable is genuinely portfolio-worthy: a legacy project migrated with complete documentation that demonstrates senior-level skill.

By the end of the 5 capsules, you'll have executed a complete migration of a legacy project applying the 7 previous modules as a single pipeline, produced professional documentation with before/after architecture maps, a detailed change log, and a handoff doc, and demonstrated senior-level skill in an artifact you can show in interviews or hiring processes.

Module Context

Phase 1: Understand Codebases (M1-3) ✅
Phase 2: Refactoring (M4-6) ✅
Phase 3: Legacy and Project (M7-8)
├── Module 7: Modernize Legacy Code ✅
└── Module 8: Capstone Project ← YOU ARE HERE

This is the last module of guide #8. There's no next module — the next step is to apply everything to your real work or continue with other guides in the Agentic Development path.

Professional Objective

Execute a complete migration of a legacy project using Claude Code, producing a professional result with documentation that demonstrates mastery of all the guide's techniques.

By the end you'll be able to:

✅ Execute a project assessment of a legacy codebase
✅ Create a migration plan with phases and checkpoints
✅ Execute the full migration cycle: onboarding → analysis → tests → refactoring → modernization → validation → documentation
✅ Produce before/after architecture maps
✅ Create professional handoff documentation
✅ Document each decision with traceable justification

Why This Project Is Different

Up to now, each module gave you an isolated skill. This module asks you to execute all of them in sequence, with a single deliverable, on a real codebase — not on curated examples.

Modules 1-7 (individual skills):
→ "Practice onboarding on this sample codebase"
→ "Practice refactoring on these 5 files"
→ "Practice modernization on this module"
→ Each one isolated, with controlled conditions

Module 8 (integration):
→ "Take a real project with real tech debt"
→ "Apply EVERYTHING you learned in sequence"
→ "Produce a professional deliverable with documentation"
→ Without controlled conditions: reality

It's the difference between practicing free throws and playing a complete game. The previous modules are free throws. This is the game. The integration is where the challenges appear that don't show up in isolated exercises: unexpected dependencies, gray files (is it legacy or just old?), decisions where the plan says one thing but the codebase asks for another.

What makes this project portfolio-worthy

What you produce is NOT:
❌ A repo with code that passes tests (any course produces that)
❌ A list of changes without context

What you produce IS:
✅ A migrated codebase with green tests
✅ An architecture map BEFORE (at the start) and AFTER (at the end) — visual
   evidence of the change
✅ A change log with traceable decisions: "this was done, this was NOT done,
   and why"
✅ A handoff doc a colleague could use to continue the work
✅ Before/after metrics: tech debt items resolved, lines removed,
   coverage added

An employer or client can read this and verify that you understand migration at a senior level — not that "you know Claude Code".

Module Progression

Capsule	Topic	What you'll do
01	Introduction + Assessment (this capsule)	Evaluate the legacy project: state, tech debt, priorities
02	Onboarding + Architecture	Understand the codebase and generate an architecture map (M1-3)
03	Migration Planning + Safety Nets	Create a migration plan + regression tests (M4-5)
04	Execution: Refactoring + Modernization	Execute the refactoring and modernization (M4, M7)
05	Delivery: Documentation + Handoff	Produce the final documentation

Learning flow

This capsule 01 does the initial assessment — without this, you decide blindly. Capsules 02-04 execute the complete cycle applying modules 1-7. Capsule 05 closes with documentation that turns the technical work into a professional artifact.

The Project

Legacy Codebase to Migrate

Use a real legacy project. Options:

Option A — Provided project:

A mini Flask project of 10-15 files, ~2K lines, with realistic tech debt: no tests, mixed patterns, deprecated dependencies, inconsistent naming, logic in the route handlers, no type hints. Available in the guide's examples repository.

Option B — Open-source project:

An open-source project that needs modernization. Look for issues tagged "good first issue" + "refactoring" on GitHub. Repos with low activity and visible debt are ideal.

Option C — Your own project:

If you have a real legacy project you want to improve, use it. The benefit is that you produce real value for your company or personal product.

Minimum requirements:

5-15 files
1-3K lines of code
At least 3 types of tech debt
Verifiable functionality (you can run the app)
Allows changes (if it's from your work, confirm with your team)

The Full Migration Cycle

1. ASSESS    → Evaluate the state of the codebase (this capsule)
2. ONBOARD   → Understand with Claude Code (M1)
3. ANALYZE   → Architecture map (M3)
4. PLAN      → Migration plan with checkpoints
5. TEST      → Regression safety net (M4-5)
6. REFACTOR  → Improve structure (M4)
7. MODERNIZE → Update patterns (M7)
8. VALIDATE  → Verify behavior preserved
9. DOCUMENT  → Handoff documentation

Each step uses specific techniques from previous modules. The value of this project is the integration — you won't invent new techniques, you orchestrate them.

Assessment: The First Step (What You Do in This Capsule)

The assessment is the informed decision before you start touching code. Without an assessment, you decide blindly. With an assessment, each decision has traceable justification.

The initial command

> "Analyze this legacy project and produce an assessment:
   1. Size: files, lines, modules
   2. Tech stack: language, framework, dependencies
   3. Test coverage: are there tests? how many? what do they cover?
   4. Tech debt: top 5 problems by severity
   5. Documentation: README, docstrings, comments
   6. Overall health score: 1-10 with justification"

The Assessment Report

# Project Assessment: [Project name]

## Overview
- Files: X
- Lines: X
- Framework: Flask 1.x
- Python: 3.8
- Tests: 0 (!)
- Dependencies: 5 (2 deprecated)

## Health Score: 4/10
- ✅ Works (the app runs)
- ✅ Has a basic directory structure
- ❌ No tests
- ❌ No type hints
- ❌ Logic in the route handlers (no service layer)
- ❌ Deprecated dependencies
- ❌ Significant dead code

## Top 5 Tech Debt
1. [HIGH] Logic in route handlers → needs a service layer
2. [HIGH] 0 tests → needs a safety net before any change
3. [MEDIUM] Deprecated dependencies → requests 2.25 → httpx
4. [MEDIUM] No type hints → hard to maintain
5. [LOW] Dead code: 3 unused functions

## Recommendation
Priority: Tests → Service Layer → Dependencies → Type Hints → Dead Code
Estimate: 8-12 hours with Claude Code

Why the assessment is the most important capsule

Without a rigorous assessment, everything that comes after is improvisation. With an assessment, capsules 02-05 execute an informed plan:

The project's scope is bounded (you don't add new features)
The priority of the tech debt is clear
The estimate helps you decide whether it's 1 day or 1 week of work
The health score serves as a baseline for the project's "after"

Connection with the Following Capsules

Capsule 02: Onboarding + Architecture analysis of the project (applies M1, M2, M3)
Capsule 03: Migration planning + Safety nets — regression tests that protect the change (applies M4)
Capsule 04: Execution of the refactoring and modernization with all the previous modules (applies M4, M5, M7)
Capsule 05: Final documentation + Handoff — turns the technical work into a professional artifact

The architecture map you produce in capsule 02 is the direct input for the plan in capsule 03. The plan in capsule 03 is the input for the execution in capsule 04. The execution in capsule 04 feeds the documentation in capsule 05. It's a linear pipeline — skipping steps breaks the flow.

Traps to Avoid While Taking This Module

Five predictable misunderstandings that appear specifically when you integrate the 7 modules into a single project.

1. "I'll start by refactoring because I feel comfortable with M4"

It's the most expensive trap. Without an assessment (this capsule) and without an architecture map (capsule 02), your refactoring decisions have no basis. You're going to refactor the wrong thing, in the wrong order, without the right priorities. The module 8 rule is mandatory sequence: assess → onboard → analyze → plan → test → execute → document.

2. "The assessment is just paperwork"

No. The assessment is the informed decision of what to touch and what not. Without an assessment, you'll touch 30 things and resolve 5. With an assessment, you touch 5 and resolve 5. The time invested in the assessment is recovered 5× in the execution.

3. "I'll take the opportunity to improve the business logic"

Not while you're executing the capstone project. Migration preserves behavior. If the code has a bug, you document it in the handoff doc — you don't fix it now, because mixing bug fixes with migration makes it impossible to verify what changed and why. Capsule 05 gives you the format for the "issues found, not addressed" doc.

4. "If Claude Code lists 30 tech debt items, I fix them all"

No. Module 7 gave you the impact/risk matrix. Here you apply it. You'll probably tackle 5-10 items of the 30 — the ones with high impact and manageable risk. The rest are documented as "tech debt remaining" in the handoff. Wanting to resolve everything in one PR is how you make the "big bangs" from module 7 that end badly.

5. "Documentation is the last thing, I'll do it at the end if I have time left"

The opposite. Documentation is the most valuable deliverable. A project migrated without documentation is personal work; with documentation, it's a portfolio. Capsule 05 gives you the structure — start the change log from the first commit, not at the end.

Diagnosis: Ready for the Capstone Project?

Five questions to confirm you have what you need before starting.

Question 1: Can you execute systematic onboarding with Claude Code in under 1 hour? (M1)

If yes: you're ready for capsule 02.

If no: review Module 1 (the 5 onboarding questions and the findings doc).

Question 2: Can you generate an Architecture Map (dependency map + flow analysis + patterns) of a project you don't know? (M3)

If yes: capsule 02 will flow.

If no: review Module 3. It's the direct input for the migration plan.

Question 3: Do you write regression tests out of habit before any refactoring? (M4)

If yes: you're going to survive the execution in capsule 04.

If you doubt: review Module 4 capsule 05. Without this, the capstone project is a risky "big bang".

Question 4: Do you have a useful CLAUDE.md for your projects? (M6)

If yes: you'll be able to keep the context productive during the project.

If no: review M6 capsule 04 before starting — you're going to need it for the chosen codebase.

Question 5: Do you know the difference between modernization (preserves behavior) and rewrite (changes behavior)? (M7)

If yes: you're going to avoid trap #3.

If you doubt: review M7 before capsule 04 of the project.

If you hesitated on 2 or more: go back to the corresponding module before starting the project. Module 8 can't be executed well without the previous ones being solid. If you answered them all with confidence, you're ready — start with the assessment of your chosen codebase.

Final Evidence of Success

At the close of the capstone project, your deliverable must contain:

✅ Project Assessment (this capsule) — the document that justifies all the decisions
✅ Architecture Map BEFORE and AFTER (capsule 02 + capsule 05) — visual evidence of the change
✅ Migration Plan (capsule 03) — phases with checkpoints
✅ Regression test suite (capsule 03) — green pre and post migration
✅ Migrated codebase (capsule 04) — refactored and modernized, tests green
✅ Change log (capsule 05) — one commit per type of change, traceable justification
✅ Handoff doc (capsule 05) — a colleague could continue your work by reading it
✅ Before/after metrics (capsule 05) — tech debt items resolved, coverage, lines removed

If the 8 deliverables are in place, you completed guide #8 — and you have an artifact that demonstrates senior-level skill in migrating legacy codebases with AI.

Summary

This module integrates everything you learned in M1-M7
The full migration cycle has 9 steps executed in sequence
The assessment is the first step — it informs all the following decisions
The project is portfolio-worthy: it demonstrates senior-level skill
Use a real codebase with real tech debt
The most expensive trap is skipping the assessment and starting to touch code
Documentation is the most valuable deliverable, not the last optional task

Next capsule: 02 — Onboarding + Architecture Analysis — you apply M1 (onboarding) and M3 (architecture map) to the project you assessed here. It's the direct input for the migration plan (capsule 03).

Additional Resources

Working Effectively with Legacy Code - Michael Feathers, the bible of legacy code
Refactoring - Martin Fowler - The refactoring reference
The Pragmatic Programmer - Software principles that apply to migrations
Strangler Fig Pattern - For gradual migrations
Claude Code Documentation - Reference for the main tool
The Software Engineer's Guidebook - Gergely Orosz - Chapters on migration and senior-level work

Module 8, Capsule 01 — Refactoring & Legacy Code with Claude Code Guide

← PreviousModule Project: Modernizing a Legacy Module Next →Onboarding and Architecture Analysis of the Legacy Project