dewyll/monolith-decomposition-skill

Break a monolith into microservices one measured, reviewed and protected step at a time.
An agent skill for Claude Code (and other coding agents) that works with any programming language.
---
Most monolith-to-microservices migrations go wrong in the same place: the
service boundaries are guessed in a meeting, and nobody can say later why
they were drawn there. This skill turns the migration into a sequence of
small, evidence-based steps. At every step your agent **measures** the
codebase with scripts, **proposes** decisions backed by those numbers,
**records** them as architecture RFCs, **guards** them with fitness
functions, and **stops for your approval** before moving on.
The workflow follows the *component-based decomposition* patterns from
**Software Architecture: The Hard Parts** (Neal Ford, Mark Richards, Pramod
Sadalage and Zhamak Dehghani), with *tactical forking* as the alternative
for codebases with no usable structure. The book's spirit runs through the
whole process:
> Strive for "the least worst combination of trade-offs."
> — *Software Architecture: The Hard Parts*
Contents
- How it works
- What each phase produces
- Quick start
- Supported languages
- What ends up in your repository
- Try it on the example
- FAQ
- Credits and further reading
How it works
Every phase runs the same loop, much like spec-driven development:
Three rules keep it honest:
1. **Numbers come from scripts, judgement comes from people.** Sizes,
coupling and cycles are computed, never estimated by the model.
2. **Every phase ends at a gate.** Domain boundaries are business
decisions, so the agent stops and asks.
3. **Every decision is an RFC, and every RFC is protected by a fitness
function** that can run in CI long after the migration starts.
What each phase produces
| Phase | You get | Typical RFC | Fitness function |
|---|---|---|---|
| **0. Assess** | drivers, constraints, a structural probe | Component-based or tactical forking? | — |
| **1. Identify & size** | component inventory: size, % of codebase, z-score, outliers | Inventory and size thresholds | no component above *X*%, outliers justified |
| **2. Common domain** | shared-concern candidates, duplicated capabilities, fan-in | What gets consolidated, and where | duplicates cannot come back |
| **3. Flatten** | orphaned code in parent namespaces and where it goes | Flattening plan | no code in flattened parents |
| **4. Dependencies** | Ca/Ce/instability, cycles, matrix, Mermaid graph, feasibility | Coupling assessment, how to break each cycle | no cycles, coupling cap |
| **5. Domains** | domain map, cross-domain edges, cohesion per domain | Domain map, contested boundaries | forbidden dependencies between domains |
| **6. Services** | service map, declared interfaces, extraction order | One per service, extraction order, shared-code reuse | undeclared cross-service calls fail CI |
Quick start
Install as a Claude Code plugin
(Inside a session: /plugin marketplace add dewyll/monolith-decomposition-skill.)
Or copy the skill folder
Other agents that understand SKILL.md folders can load the same
directory. For any other agent, point it at
SKILL.md as
its instructions; everything else is plain Markdown, JSON and Python.
Use it
Open your monolith's repository and ask for it in plain words:
The plugin also exposes it as /monolith-decomposition:decompose
(/decompose when copied as a standalone skill).
**Requirements:** Python 3.9+ (standard library only). Optional:
scc for faster, more precise size metrics,
and your ecosystem's dependency tools for higher-confidence graphs.
Supported languages
The workflow and artifacts are language-neutral. Each ecosystem has an