Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Decomposition

Pattern

A reusable solution you can apply to your work.

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 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. Look for clusters of behavior that change together, serve a common purpose, and have minimal communication with the rest. These clusters are natural modules or components.

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.
  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. 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. 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, a contract, 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.