Component-Oriented Decomposition

Principle 01 · COD

Component-Oriented Decomposition

AI Agents working on complex long-horizon projects require stable, bounded units of work with explicit Contracts. They get that through Hierarchical Component Specifications, and not through flat lists of features or a monolithic requirements document.

This holds for software Systems, physical megastructures such as floating cities, energy Systems, transportation networks, or any other engineered System of high complexity.

Large Systems that stay coherent over time are decomposed into pieces with clear responsibilities, interfaces, and ownership boundaries. Those pieces are Components, such as modules, services, Subsystems, libraries, AI Agents, and layers. Without that decomposition the System becomes a monolith that no human team and no set of AI Agents can reason about, divide into parallel work, or change without constant global coordination.

It's therefore essential to prefer Components that can be replaced, upgraded, or removed with limited disruption to the rest of the System. Clean interfaces and explicit Contracts make this practical. Both humans and AI Agents benefit when a Component can be swapped without forcing redesign of high-stability elements.

Feature-centric thinking works only while the System is still small and mostly user-facing. Once the majority of the work is internal infrastructure, coordination logic, reliability mechanisms, or performance-critical paths, "features" become a forced and misleading frame. In software Systems that have end users, there are obviously user-facing Capabilities. In a floating city there are residential modules, power generation, desalination, docking systems, emergency response, governance interfaces, and so on. Some of those Capabilities are commonly called "features".

But the word "feature" has certain implications as a unit of work and specification:

  • It carries the assumption that the primary consumer is an end user and that the right framing is a user story.
  • Thinking in terms of "features" works cleanly only while the System is still small and mostly surface-level.
  • Once the majority of the effort is internal (coordination, reliability, interfaces between Subsystems, performance under load, safety Constraints, long-term maintainability, etc), forcing everything into "features" becomes artificial and misleading.

A floating city’s power distribution network, structural integrity monitoring, or waste-processing loops are not usefully described as features with user stories. They are Components with required behaviors, interfaces, Constraints, and Acceptance Criteria. The same is true for the majority of the work inside any ambitious software System after the first few user-visible slices.

So how do we go about features then?

  • A user-facing Capability is either its own Component or a required behavior of a larger Component.
  • When it's truly end-user facing, you may include one or a few short "user story" statements inside the Rationale section of the Component's Specification, which helps explain why the Component exists from the user's perspective.

In some rare edge cases like pure dataflow Systems the primary mental model starts with flows or roles rather than static Components. But even then those Systems end up being implemented as Components with defined interfaces.

There are some scenarios where the Component lens becomes secondary and impractical:

  • If you work on pure open-ended scientific exploration with no engineering deliverable or target artifact.
  • Certain forms of pure mathematical or theoretical work producing a single unified proof or insight rather than a constructed System.
  • Small-scale artistic or expressive works where modularity would actively harm the intended holistic quality.
  • Extremely short-lived, single-person prototypes where the overhead of formal decomposition exceeds any benefit (you already know that those days are counted).

But even in those scenarios, some form of decomposition emerges once the work grows beyond a certain size.

Therefore it is correct to treat Component-oriented decomposition as the default mental model.

Applied in the Specification #

These clauses of the Normative Structural Specification name Component-Oriented Decomposition among their grounds.