Skip to main content
skill CX Codex

modular-decomposition — Claude Code skill: what it does

modular-decomposition walks a monolith through five analysis steps before splitting it into modules: sizing and listing components, finding duplicate domain logic, hierarchy, coupling, and domain grouping.

MIT ★ 7,191 updated 2026-10-24

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add tech-leads-club/agent-skills --skill modular-decomposition -a claude-code
Open on GitHub

What modular-decomposition does

The skill chains five patterns (pattern-01 through pattern-05), each living as its own markdown file under references/. It starts by cataloguing components and sizing them, then looks for domain logic repeated across different parts of the codebase, works through flat or tangled module hierarchies, measures coupling between pieces of code, and finally clusters components into candidate groupings aligned with domain boundaries.

Steps run in sequence: the component list and sizes from pattern 1 feed into the coupling numbers in pattern 4 and the grouping in pattern 5. An agent is only allowed to skip a step when the user explicitly narrows the scope, and has to state which conclusions become weaker as a result. Before or during pattern 5, references/domain-analysis.md adds a strategic DDD pass — subdomains, bounded contexts, shared vocabulary — for checking the structural grouping against business language.

The skill stops short of building an extraction roadmap with phases and priorities; that part belongs to decomposition-planning-roadmap, meant to run after this pipeline. A full legacy migration strategy, with strangler-fig patterns or cross-stack rewrites, calls for legacy-migration-planner instead.

What it helps with

  • break a monolith into modules before pulling out services
  • spot domain logic duplicated across different parts of a codebase
  • size and catalogue components ahead of extraction
  • measure coupling between packages or modules
  • cluster components into service candidates along domain lines

Example prompts for the agent

  • Run modular-decomposition patterns 1 through 5 on this repo
  • Use modular-decomposition to find duplicated domain logic across our modules
  • Measure coupling between our packages and group components by domain

How to install modular-decomposition

1Skills CLI (Vercel)

npx skills add tech-leads-club/agent-skills --skill modular-decomposition -a claude-code

2Manually: put the files in place

~/.claude/skills/modular-decomposition/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/modular-decomposition/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about modular-decomposition

How do I install modular-decomposition in Claude Code?

Run npx skills add tech-leads-club/agent-skills --skill modular-decomposition -a claude-code; the skill lands at ~/.claude/skills/modular-decomposition/SKILL.md.

What does modular-decomposition do?

It runs a monolith through five patterns: sizing and cataloguing components, finding duplicated domain logic, untangling hierarchy, measuring coupling, and grouping components into service candidates by domain.

How does modular-decomposition differ from decomposition-planning-roadmap?

modular-decomposition handles the structural analysis — inventory, coupling, grouping — while decomposition-planning-roadmap takes that output and builds a phased extraction plan with priorities, meant to run afterward.

Source text

SKILL.md · MIT
---
name: modular-decomposition
description: Runs a sequenced monolith-to-modular pipeline that sizes and inventories components, finds shared domain duplication, addresses flattening and hierarchy issues, analyzes coupling, then groups components into candidate domain-aligned units, with optional embedded DDD strategic analysis for bounded contexts. Use when asking how to split a monolith, size components before extraction, find duplicated domain logic, clean up module hierarchy, measure coupling between modules, or group components into services. Do NOT use for phased extraction roadmaps or prioritization without the prior analysis steps (use decomposition-planning-roadmap after this pipeline), end-to-end legacy migration strategy writeups (use legacy-migration-planner), pure infrastructure capacity sizing, or when you only need DDD without the structural pipeline (install domain-analysis standalone).
---

# Modular Decomposition

This skill runs the **Patterns 1–5** analysis pipeline before service extraction. Each pattern is plain markdown under `references/`; load the file for that step and execute it against the user’s codebase.

## How to Use

### Quick start (what users can say)

- **Full pipeline:** “Run modular decomposition Patterns 1 through 5 on this repo,” “Analyze this monolith for splitting—inventory, coupling, and domain grouping.”
- **Single early step:** “Identify and size components here,” “Find duplicated domain logic across modules,” “Analyze coupling between our packages.”
- **With DDD lens:** “Group components into domains and check bounded contexts,” “Use DDD strategic design on this codebase before we group services.”

If the user only wants **extraction order, phases, or migration roadmap** after analysis exists, use **decomposition-planning-roadmap** instead. If they need a **full legacy migration plan** (strangler fig, research, multi-stack), use **legacy-migration-planner** as well or instead of this skill when that is the primary ask.

### How the agent should run it

1. **Scope:** Confirm the task is structural analysis (inventory → coupling → grouping), not roadmap authoring. If unclear, ask once whether they want the full ordered pipeline or a subset.
2. **Order:** Run patterns **1 → 2 → 3 → 4 → 5** in that order. Do not skip a step unless the user explicitly limits scope; if they do, state which patterns were skipped and how that limits later conclusions.
3. **Load references:** For each pattern, open the matching `references/pattern-NN-*.md` file and follow its instructions. Use the optional `*-quick-reference.md` for the same number when a short checklist is enough.
4. **Carry context forward:** Reuse outputs from earlier patterns in later ones (e.g. component inventory from Pattern 1 informs coupling in 4 and grouping in 5). Reference concrete paths, modules, or tables from previous steps.
5. **Domain language (Pattern 5):** If subdomains or bounded contexts need grounding beyond structure, read `references/domain-analysis.md` **before or alongside** Pattern 5. Optionally open `references/domain-analysis-quick-reference.md` or `references/domain-analysis-examples.md` for condensed rules or illustrations.
6. **Deliver:** Produce clear, actionable findings per pattern or one consolidated report—always tied to evidence from the repository (files, dependencies, metrics), not generic advice.

### Usage examples

**Example 1 — Full pipeline**

```
User: "We're going to split this monolith—run the full decomposition analysis (Patterns 1–5)."

Agent: Execute patterns 1→5 in order, loading each references/pattern-NN-*.md, preserving outputs between steps, then summarize cross-cutting recommendations.
```

**Example 2 — Coupling after inventory**

```
User: "We already have a rough module list—focus on coupling (Pattern 4) and then domain grouping (Pattern 5)."

Agent: If no prior inventory exists in the thread, either run Pattern 1 briefly or derive an explicit module list from the repo before 4 and 5. State any assumptions.
```

**Example 3 — DDD before grouping**

```
User: "Map bounded contexts and language, then group components into domains."

Agent: Read references/domain-analysis.md (and optional quick reference/examples) in parallel with or immediately before Pattern 5; align Pattern 5 groupings with linguistic boundaries where evidence supports it.
```

## Prerequisites

- Complete **Pattern N** before starting Pattern N+1 unless the user explicitly narrows scope. Later patterns depend on earlier results (for example, inventory and structure inform coupling and grouping).
- If business vocabulary, subdomains, or bounded contexts are uncertain, use `references/domain-analysis.md` **before or alongside Pattern 5** (see Bounded contexts below).

## Ordered workflow (Patterns 1–5)

| Step | Pattern                            | Primary reference                                                                                          |
| ---- | ---------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| 1    | Identify and size components       | `references/pattern-01-identify-and-size.md` (optional: `pattern-01-identify-and-size-quick-reference.md`) |
| 2    | Common domain detection            | `references/pattern-02-common-domain.md` (optional: `pattern-02-common-domain-quick-reference.md`)         |
| 3    | Flattening / hierarchy             | `references/pattern-03-flattening.md` (optional: `pattern-03-flattening-quick-reference.md`)               |
| 4    | Coupling analysis                  | `references/pattern-04-coupling.md`                                                                        |
| 5    | Domain identification and grouping | `references/pattern-05-domain-grouping.md` (optional: `pattern-05-domain-grouping-quick-reference.md`)     |

## Pattern 6 — planning and extraction

**Pattern 6** (_create domain services / extraction_) is not duplicated here. After Pattern 5, switch to **decomposition-planning-roadmap** for phased extraction order, milestones, and migration-style planning. For full legacy migration strategy (strangler-fig, cross-stack rewrites, research-heavy plans), optionally use **legacy-migration-planner** in addition.

## Bounded contexts and DDD strategic design

- **Patterns 1–4** focus on **structural** inventory, duplication, hierarchy, and **coupling** between parts of the codebase.
- **Pattern 5** produces **candidate** groupings aligned with **solution-space** boundaries (which components belong together as services).
- **Strategic DDD** (subdomains, bounded contexts, ubiquitous language) is covered in `references/domain-analysis.md`, with optional `domain-analysis-quick-reference.md` and `domain-analysis-examples.md`. Use it when you need to validate or refine boundaries against business language, not only folder structure.

© tech-leads-club · MIT · tech-leads-club/agent-skills

Similar skills

All skills for Code review and refactoring →

From the same set130

The whole set →
state-context-interface The state-context-interface rule separates a component’s UI from its state implementation with a context split into state, actions, and meta. Use it when the same UI needs to work with different providers. CX Codex +1 ★ 7,191repo stars learning-opportunities learning-opportunities adds optional 10–15 minute exercises to a Claude session, so the person who shipped the code can still explain how it works. CX Codex +1 ★ 7,191repo stars confluence-assistant confluence-assistant operates Confluence spaces through Atlassian MCP tools. Helps Claude Code search team documentation, create structured pages, and update existing entries using Markdown. CX Codex +1 ★ 7,191repo stars security-threat-model security-threat-model reads your repository and writes a threat model: trust boundaries, assets, realistic abuse paths and mitigations, saved as a Markdown file. CX Codex +1 ★ 7,191repo stars tlc-plan tlc-plan turns PRDs, tickets, and task threads into an unambiguous implementation plan. It resolves all edge cases through direct questions before writing specs. CX Codex +1 ★ 7,191repo stars legacy-migration-planner The legacy-migration-planner skill plans legacy migrations, codebase modernization, and monolith decomposition. Use it before implementation when the move needs documented research and staged decisions. CX Codex +1 ★ 7,191repo stars shopify-developer shopify-developer gives the agent a Shopify reference: Liquid, OS 2.0 themes, GraphQL APIs, Functions and Hydrogen, all pinned to API version 2026-01. CX Codex +1 ★ 7,191repo stars aws-advisor aws-advisor is a Claude Code skill that advises on AWS architecture, reviews security policies, and verifies recommendations against documentation via MCP tools. CX Codex +1 ★ 7,191repo stars

Project sponsors

Companies that keep this analytics open