--- slug: decomposition type: pattern summary: "Dividing a larger system into smaller, more manageable pieces, where the choice of where to cut shapes everything that follows." created: 2026-04-04 updated: 2026-04-05 related: agent-teams: relation: used-by note: "Effective team coordination requires effective task decomposition." architecture: relation: enabled-by note: "Architecture makes principled splitting possible." big-ball-of-mud: relation: related note: "Decomposition is the primary corrective for structural collapse." boundary: relation: produces note: "The outputs of decomposition." cohesion: relation: guided-by note: "The principles that tell you where to cut." component: relation: produces note: "The outputs of decomposition." composition: relation: contrasts-with note: "Composition builds up; decomposition breaks down." coupling: relation: guided-by note: "The principles that tell you where to cut." god-object: relation: corrects note: "Breaking a god object apart is a concrete decomposition task." design-doc: relation: enabled-by note: "The proposed design section naturally decomposes the problem into buildable pieces." module: relation: produces note: "The outputs of decomposition." monolith: relation: applied-to note: "Decomposition is how a monolith evolves when it needs to." orchestrator-workers: relation: depended-on-by note: "The orchestrator's core skill is good decomposition." parallelization: relation: depended-on-by note: "Effective parallelization requires effective decomposition." separation-of-concerns: relation: guided-by note: "The principles that tell you where to cut." shape: relation: enabled-by note: "Understanding the shape helps you decide where to split." strangler-fig: relation: related note: "Strangler fig decomposes a monolith incrementally rather than all at once." stream-aligned-team: relation: used-by note: "Stream alignment requires decomposing the system along value-stream boundaries rather than technical-layer boundaries." subagent: relation: depended-on-by note: "Effective subagent use requires decomposing the task well." task-decomposition: relation: refined-by note: "The same idea applied to work items rather than code." team-cognitive-load: relation: enabled-by note: "Cognitive load provides a concrete criterion for when and where to decompose a system." --- # Decomposition > **Pattern** > > A named solution to a recurring problem. ## Context Every system starts as one thing: a single idea, a single file, a single responsibility. As it grows, it must be broken into parts. **Decomposition** is the act of dividing a larger system into smaller, more manageable pieces. It operates at the **architectural** scale, and *where you cut* shapes everything that follows. Decomposition is the structural complement of [composition](composition.md): composition builds up from parts, decomposition breaks down into them. ## Problem How do you break a system into parts such that each part is understandable on its own and the parts work together to achieve what the whole system needs? ## Forces - A system that is not decomposed becomes harder to understand and change as it grows. - Decomposing too early, before you understand the natural seams, creates boundaries you'll regret. - Decomposing along the wrong lines produces parts that constantly reach across boundaries to get their work done. - Every decomposition introduces coordination overhead. The parts must communicate where before they simply shared memory. ## Solution Decompose along the lines of [separation of concerns](separation-of-concerns.md). Look for clusters of behavior that change together, serve a common purpose, and have minimal communication with the rest. These clusters are natural [modules](module.md) or [components](component.md). Three common decomposition strategies: 1. **By domain concept** — each part represents a business entity or capability (users, orders, payments). This tends to produce high [cohesion](cohesion.md). 2. **By technical layer** — each part handles a technical concern (presentation, business logic, data access). This is clear but can scatter a single feature across many parts. 3. **By rate of change** — things that change together stay together; things that change independently are separated. This is often the most pragmatic strategy. The best decompositions combine these strategies, using domain boundaries as the primary cut and technical layers within each domain part. In agentic coding, decomposition has a direct practical effect: it determines the size of the context an agent needs. A well-decomposed system lets you give an agent a single module and say "work here." A poorly decomposed system forces the agent to load the entire codebase just to make a local change. ## How It Plays Out A team inherits a 50,000-line [monolith](monolith.md). Rather than rewriting it as microservices, they analyze the codebase for natural seams: which files change together? Which functions call each other most? They identify four clusters and extract them into internal modules with explicit [interfaces](interface.md). The monolith remains a single deployable unit, but each module can now be understood and tested independently. An AI agent is given the task: "Add support for PDF export." In a decomposed system, the agent identifies the `export` module, reads its interface, sees the existing formats (CSV, JSON), and adds PDF following the same pattern. In an undecomposed system, export logic is woven through the report generation code, the API handlers, and the file storage layer. The agent either misses pieces or makes changes in the wrong places. > **💡 Tip** > > If you are unsure where to decompose, look at your version control history. Files that always change in the same commit belong together. Files that never change together are candidates for separate modules. > **💡 Example Prompt** > > "Analyze the codebase for natural module boundaries. Check which files change together in the git history. Identify clusters that should be separate modules and propose a decomposition plan." ## Consequences Good decomposition makes systems comprehensible, testable, and evolvable. Each part becomes a manageable unit of work for a human or an agent. It enables team autonomy, parallel development, and independent deployment (if the parts are separately deployable). The cost is the overhead of managing boundaries. Each boundary requires an [interface](interface.md), a [contract](contract.md), and coordination when the contract needs to change. Premature decomposition (splitting before you understand the natural seams) is expensive to reverse. When in doubt, keep things together and extract when the evidence is clear. --- - [Next: Task Decomposition](task-decomposition.md) - [Previous: Monolith](monolith.md)