| name | refactoring-mikado-strangler |
| description | Guide for large-scale refactorings with Mikado and Strangler Fig. Use for architecture migration, library replacement, module splitting, or pattern changes. Maintains a Mikado graph to track dependencies. |
Large Scale Refactoring - Mikado & Strangler Fig
Persona
Read .claude/roles/senior-dev.md — adopt this profile and follow all its rules.
Activation
This skill activates for refactorings that exceed a TDD cycle scope:
- Architecture migration
- Library or framework replacement
- Splitting a monolithic module
- Pattern change (e.g., callbacks -> promises -> async/await)
- Bounded context restructuring
Choosing the method
| Criterion | Mikado | Strangler Fig |
|---|
| Old code stays functional during | No | Yes |
| Need to deliver incrementally | Difficult | Ideal |
| Complex dependencies to untangle | Ideal | Possible |
| Complete replacement of a system | Possible | Ideal |
Ask the user which method to use if it's not obvious.
Mikado Method
Principle
- Try the final goal directly
- Observe what breaks
- Revert immediately (no broken code left around)
- Note the discovered prerequisites in the graph
- Recurse on each prerequisite
- Implement the leaves of the graph (those with no dependencies)
Interactive workflow
Step 1: Initialization
MIKADO - Initialization
Main goal: [description]
Graph file: docs/mikado/[name]-graph.md
I will create the tracking file.
Shall we begin?
Create the graph file:
# Mikado Graph: [Goal]
## Status: IN PROGRESS
## Main goal
- [ ] [Goal description]
## Discovered prerequisites
(Fills in as attempts are made)
## Attempt history
(Log of attempts and discoveries)
Step 2: Attempt
MIKADO - Attempt
I will try: [goal or prerequisite]
Expected: [what should break]
Shall we try?
After validation:
- Attempt the modification
- Run
yarn test:run
- Note EVERYTHING that breaks
- REVERT IMMEDIATELY with
git checkout .
Step 3: Analysis
MIKADO - Analysis
Attempt: [what we tried]
Result: [success / failure]
Errors encountered:
- [error 1] -> Prerequisite: [required action]
- [error 2] -> Prerequisite: [required action]
I'm updating the graph.
Which prerequisite do we tackle first?
Step 4: Implementation (leaves)
When a prerequisite has no dependencies:
MIKADO - Implementation
Prerequisite to implement: [description]
This is a leaf of the graph (no dependencies).
-> Activating the TDD skill for proper implementation.
Switch to the TDD skill to implement the prerequisite with RED-GREEN-REFACTOR.
Step 5: Validation
After each implementation:
MIKADO - Validation
Prerequisite completed: [description]
Updating the graph: done
Next action:
- [ ] [Another leaf to process]
- [ ] [Retry a parent goal]
What do we continue with?
Strangler Fig Method
Principle
- Create the new system alongside the old one
- Migrate calls progressively to the new system
- Cohabitation: both systems run in parallel
- Remove the old one when nothing uses it anymore
Interactive workflow
Step 1: Planning
STRANGLER - Planning
Old system: [description]
New system: [description]
Entry points to migrate:
1. [point 1]
2. [point 2]
...
I'm creating the tracking file: docs/strangler/[name]-migration.md
Which entry point do we start with?
Create the tracking file:
# Strangler Migration: [Name]
## Status: IN PROGRESS
## Old system
- Location: [path]
- Entry points: [list]
## New system
- Location: [path]
- Migrated entry points: 0/[total]
## Migration plan
| Entry point | Status | Date |
|-------------|--------|------|
| [point 1] | Pending | - |
| [point 2] | Pending | - |
## Old system removal checklist
- [ ] All entry points migrated
- [ ] No references to old code
- [ ] Old system tests removed/migrated
- [ ] Old code deleted
Step 2: Creating the new system
STRANGLER - New system
I will create the new implementation for: [entry point]
Location: [path]
-> Activating the TDD skill for proper implementation.
Switch to the TDD skill to create the new implementation.
Step 3: Migrating an entry point
STRANGLER - Migration
Entry point: [description]
Old: [code/path]
New: [code/path]
Migration plan:
1. [step 1]
2. [step 2]
Shall we migrate?
Step 4: Cohabitation verification
STRANGLER - Verification
Migration completed: [entry point]
Checklist:
- [ ] Tests pass
- [ ] Old code still functional (if other dependencies exist)
- [ ] New code used by [consumers]
Updating the tracking file.
Next entry point?
Step 5: Removal
When all entry points are migrated:
STRANGLER - Removal
All entry points have been migrated!
Old code to remove:
- [file 1]
- [file 2]
Tests to remove/migrate:
- [test 1]
Shall we clean up?
Integration with the TDD skill
Every time we need to implement code (Mikado prerequisite or new Strangler system), we switch to the TDD skill:
-> This prerequisite requires code.
-> Activating the TDD skill to implement with RED-GREEN-REFACTOR.
-> Returning to the Refactoring skill once complete.
Tracking files
Graphs and plans are stored in:
docs/
├── mikado/
│ └── [name]-graph.md
└── strangler/
└── [name]-migration.md
These files serve as living documentation and allow resuming an interrupted refactoring.
Anti-patterns to block
- Leaving broken un-reverted code (Mikado)
- Removing the old system before the new one is complete (Strangler)
- Implementing without tests (always go through the TDD skill)
- Multiple refactorings in parallel
- Skipping a step without user validation
