refactoring-mikado-strangler
Skill44 starsChanged 6 months agoMITView on GitHub
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.
In this repository30 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- agent-creatorSkill
- anti-overengineeringSkill
- audit-docsSkill
- auto-reviewSkill
- architectureSkill
- clean-codeSkill
- commitSkill
- create-docSkill
- dddSkill
- discoverySkill
- docs-indexSkill
- e2eSkill
- event-stormingSkill
- implement-featureSkill
- product-managerSkill
- refactor-featureSkill
- review-backSkill
- review-docSkill
- review-followupSkill
- review-frontSkill
- review-fullstackSkill
- securitySkill
- shipSkill
- skill-creatorSkill
- solidSkill
- dashboard-stylingSkill
- tddSkill
- update-docsSkill
- worktreeSkill
The file
We split this skill into the rules it gives an agent
6 rules. About 0 are common, 5 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈5
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 10
Read .claude/roles/senior-dev.md — adopt this profile and follow all its rules.
- Distinctive: line 59
Create the graph file:
- Distinctive: line 110
When a prerequisite has no dependencies:
- Distinctive: line 168
Create the tracking file:
- Distinctive: line 243
When all entry points are migrated:
- Distinctive: line 263
Every time we need to implement code (Mikado prerequisite or new Strangler system), we switch to the TDD skill:
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
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 deletedStep 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.mdThese 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
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

