Module 8: Capstone Project — Migrating a Real Legacy Project

Delivery: Documentation and Handoff

Delivery: Documentation and Handoff

Project description

This is the final capsule of the guide. The code is migrated and modernized (capsule 04). Now you produce the documentation that closes the cycle: Architecture Map "After" (a comparison with the "Before"), a complete change log, before/after metrics, and handoff notes that let any developer continue the work.

A migrated project without documentation is a project that someone else will have to re-understand from scratch. Documentation closes the cycle and demonstrates professionalism. An employer or client who sees the repo after the project should be able to understand — without asking you — what changed, why, and what's missing.

This capsule is the difference between migrated code and a complete project. Both have green tests and modernized code. Only the second has a reproducible artifact that demonstrates senior skill.

Final Deliverables

1. Architecture Map: Before vs After

# Architecture: Before vs After

## Before
[Diagram of the original state - from the capsule 02 Architecture Map]

### Problems identified:
- God file (app.py with all the logic)
- No service layer
- Dead code (4 functions)
- No type hints
- Deprecated dependencies

## After
[Diagram of the current state]

### Improvements made:
- Service layer extracted (4 services)
- Modules organized by responsibility
- Dead code removed
- Type hints on 100% of public functions
- Dependencies updated

## Comparison

| Metric | Before | After | Change |
|---------|--------|-------|--------|
| Files | 5 | 12 | +7 (better separation) |
| Total lines | 1200 | 980 | -18% (dead code removed) |
| Lines in app.py | 800 | 120 | -85% (logic extracted) |
| Tests | 0 | 25 | +25 |
| Test coverage | 0% | 78% | +78% |
| Type hints | 0% | 95% | +95% |
| Dead code items | 11 | 0 | -100% |
| Tech debt score | 4/10 | 8/10 | +4 points |

2. Complete Change Log

# Change Log: [Project] Migration

## Phase 1: Safety Net
- Created 25 tests covering all endpoints and core logic
- Coverage: 78%
- Duration: 40 minutes

## Phase 2: Refactoring
### 2.1 Extract Service Layer
- Created: user_service.py, order_service.py, product_service.py, payment_service.py
- Moved business logic from route handlers to services
- Routes now average 8 lines (was 40+)
- Tests: ✅ 25/25 pass

### 2.2 Module Reorganization
- Created: src/services/, src/validators/, src/utils/
- Moved 8 files to appropriate directories
- Updated 23 imports
- Tests: ✅ 25/25 pass

### 2.3 Naming Consistency
- Renamed 5 functions for clarity
- Renamed 2 files to match conventions
- Tests: ✅ 25/25 pass

## Phase 3: Modernization
### 3.1 Dead Code Removal
- Removed: 4 unused functions, 6 unused imports, 1 unused constant
- Tests: ✅ 25/25 pass

### 3.2 Syntax Modernization
- Converted: 12 %-formatting → f-strings
- Converted: 3 type() → isinstance()
- Converted: 2 range(len()) → direct iteration
- Tests: ✅ 25/25 pass

### 3.3 Pattern Modernization
- Added: 4 context managers (with statement)
- Changed: 2 bare except → specific exceptions
- Created: enums for magic strings (3 enums)
- Tests: ✅ 25/25 pass

### 3.4 Type Hints
- Added type hints to 18 public functions
- Converted Config class to dataclass
- Tests: ✅ 25/25 pass

## Timeline
| Phase | Estimated | Actual | Notes |
|-------|-----------|--------|-------|
| Phase 1 | 30-45 min | 40 min | On track |
| Phase 2 | 45-60 min | 55 min | On track |
| Phase 3 | 30-45 min | 35 min | Faster than expected |
| Phase 4 | 20-30 min | 25 min | On track |
| **Total** | **2-3 hrs** | **2.6 hrs** | **Within estimate** |

## Commits
1. `add regression tests (25 tests, 78% coverage)`
2. `extract service layer from route handlers`
3. `reorganize modules into proper directories`
4. `rename functions and files for consistency`
5. `remove dead code (4 functions, 6 imports)`
6. `modernize string formatting to f-strings`
7. `modernize patterns (context managers, specific exceptions)`
8. `add type hints and convert Config to dataclass`
9. `add migration documentation`

3. Handoff Notes

# Handoff Notes: [Project] Post-Migration

## For the next developer

### What was done
- Complete migration of the legacy project
- See CHANGE_LOG.md for details of each change

### What was NOT done (and why)
- Flask → FastAPI migration wasn't done (out of scope, only modernization)
- The bug in tax calculation for the "APAC" region wasn't fixed (discovered during migration, documented as an issue)
- Structured logging wasn't added (recommended for the next sprint)

### Current state
- Tests: 25, passing, 78% coverage
- Python: 3.11 compatible
- Dependencies: all updated
- Tech debt: reduced from 11 items to 0

### How to continue
1. **To add a new endpoint:** follow the user_service.py pattern
2. **To add a test:** see tests/test_user_service.py as a template
3. **To understand the architecture:** see ARCHITECTURE.md

### Areas that need future attention
1. Coverage can go up to 90% with edge case tests
2. Consider migration to FastAPI next quarter
3. Add a CI/CD pipeline
4. Implement structured logging (structlog)

### Contact
- Migration performed by: [Your name]
- Date: [Date]
- Tool: Claude Code

Capstone Project Evaluation Rubric (100 points)

Assessment + Analysis (20 points)

  • (5 pts) Project assessment with a health score
  • (5 pts) Onboarding documentation
  • (5 pts) Architecture Map "Before" with a dependency map
  • (5 pts) Anti-patterns identified with severity

Planning + Safety Net (20 points)

  • (10 pts) Migration plan with phases and checkpoints
  • (10 pts) Regression tests with 70%+ coverage

Execution (30 points)

  • (10 pts) Service layer extracted / improved structure
  • (10 pts) Modernization executed (5+ items)
  • (10 pts) Tests green at each step (0 regressions)

Documentation (20 points)

  • (5 pts) Architecture Map "After" with a comparison
  • (5 pts) Complete change log by phase
  • (5 pts) Professional handoff notes
  • (5 pts) Clean git history (1 commit per change)

Professional Quality (10 points)

  • (5 pts) The project is portfolio-worthy
  • (5 pts) Another developer can continue using your docs

Extra Credit (+15 points)

  • (+5 pts) Framework migration included (Flask→FastAPI)
  • (+3 pts) CI/CD pipeline configured
  • (+3 pts) CLAUDE.md created for the project
  • (+2 pts) Per-phase time metrics documented
  • (+2 pts) Bugs found during migration documented as issues

Common Errors

  1. Skipping the assessment — without an assessment, the plan is guesswork
  2. Not writing tests first — the error that invalidates the whole migration
  3. Mixing refactoring with bug fixes — they're separate commits
  4. Documentation at the end "if there's time left" — documentation is part of the deliverable
  5. Not doing handoff notes — migrated code without a handoff is incomplete
  6. Underestimating the time — plan for 20% more than you think you need
  7. Not tagging in git — tags at each phase enable fast rollback

How to Use This Documentation in Your Career

The deliverable of this project lives beyond "completing the guide". It's an artifact you can use concretely in different contexts:

In a technical interview

Share it with the recruiter or interviewer. When they ask "show me an example of your work", you don't need to compose a story — you point to the repo and the CHANGE_LOG. The documentation speaks for itself: a rigorous assessment, an executable plan, incremental execution with metrics, a professional handoff. That progression demonstrates much more than a well-done side project.

In a senior-level hiring process

The typical questions for senior ("How do you approach a legacy project?", "How do you structure a migration?") have your concrete and verifiable answer: "Here's a project where I did it. The deliverables are in the repo." This changes the conversation from "I'll describe how I would do it" to "I'll show you how I did it".

In your current job

The complete framework (assessment → architecture map → plan → safety net → execution → documentation) is directly transferable. Apply it to the next legacy project your team touches. The quality will be noticeable, and you'll have the vocabulary and the artifacts to defend the approach.

As an educational example for your team

If you lead a team or mentor juniors, this project is a template. "When you face a legacy, follow this pattern. Here's my example." It reduces the cognitive cost of "how to approach this" and raises the quality of the team's work.

Final Reflection

By completing this project, you've demonstrated that you can:

  1. Understand a codebase you didn't write (M1-3)
  2. Plan an improvement with professional criteria
  3. Execute coordinated refactoring with a safety net (M4-5)
  4. Handle projects of any size (M6)
  5. Modernize legacy code incrementally (M7)
  6. Document your work so others can continue (M8)

These are the most valued skills in software teams. Most of the work isn't creating new code — it's improving existing code. And with Claude Code as your tool, you can do in hours what used to take weeks.

But the tool doesn't replace judgment. What you learned in this guide isn't "how to use Claude Code to refactor" — it's how to plan and execute improvements to existing code with professional discipline, using Claude Code as an amplifier. The methodology is transferable to any future tool. The tool is the scalpel; you are the surgeon.

Final Evidence of Success for the Capstone Project

At the close of all of guide #8, validate that your deliverable meets the following 8 points:

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

If the 8 points are in place, you completed guide #8 — and you have an artifact that demonstrates senior-level skill in migrating legacy codebases with AI. That's the result that justifies the 8-10 hours of the complete guide.

Congratulations

You completed guide #8 of the Claude Code Agentic Development Path — the guide with the most technical depth of the Professional level. The capstone project you produced synthesizes skills that software teams value at a senior level: systematic onboarding, coordinated refactoring, disciplined migration, incremental modernization, and professional documentation.

What comes next is up to you: apply this framework in your work, contribute to an open-source project with this methodology, or move on to guide #9 (Advanced Claude Code Workflows) to scale to multi-agent workflows, automation with hooks, and CI/CD integration. Whatever route you take — the discipline you exercised in this project is transferable.

If you decide to move on to guide #9, you'll notice that the techniques of context management, coordinated refactoring, and incremental planning become the base on which more complex workflows are built. Guide #8 gave you the foundation; #9 scales the scope.

Resources for the Project

  1. Claude Code Documentation - Your main tool
  2. Working Effectively with Legacy Code - Michael Feathers
  3. Refactoring - Martin Fowler - A catalog of refactorings
  4. pytest Documentation - For your safety net
  5. Mermaid Diagrams - For your architecture maps

Connection with the Path

By completing this guide (#8), you've finished the Professional level of the Agentic Development Path. The next guide is #9: Advanced Claude Code Workflows which teaches you Agent Teams, advanced subagents, plugins, advanced hooks, and headless SDK for automation.

The transition: "You master each individual refactoring and modernization technique. But what happens when you need to coordinate multiple Claude Code agents, automate with hooks, or integrate with CI/CD? The next guide takes you to the Advanced level."

← PreviousExecution: Refactoring, Modernization and Testing