/modular-design-principles

name: modular-design-principles
description: >
  Technology-agnostic guidance for modular systems: bounded contexts, clear boundaries,
  composability, state isolation, explicit contracts, failure containment, scaffolding workflows,
  split/merge criteria, sub-units inside a context, and compliance review signals. Use when
  designing or reviewing module structure, service boundaries, package layout, cross-cutting
  dependencies, "how should we split this?", modularity assessments, coupling between domains,
  greenfield context design, or architecture discussions without assuming a specific framework,
  language, or repository layout. Do NOT use for executing the full Patterns 1–5 repo
  decomposition pipeline or per-pattern inventories (use modular-decomposition), phased
  extraction roadmaps as the main deliverable (use decomposition-planning-roadmap), or
  end-to-end legacy migration strategy (use legacy-migration-planner).

Modular Design Principles

Use this skill when reasoning about **structure and boundaries** in any codebase. It intentionally avoids framework names, folder conventions, and tooling — map principles to your stack locally.

What to load

| Task | Where | |------|--------| | Principles table + violations + workflows (this file) | `SKILL.md` | | Per-principle definition, agent rules, abstract examples | `references/principles.md` |

---

Layered mental model

• **Composition roots** (applications, hosts, runners): wire modules together; keep orchestration thin.
• **Modules / bounded contexts**: cohesive units of behavior and data ownership; each should be understandable and testable on its own.
• **Shared kernels** (use sparingly): only stable, truly cross-cutting concepts; resist turning them into a grab-bag of “everything everyone needs.”

How you physically lay this out (mono repo, multi repo, packages, libraries) is a **delivery choice**, not the definition of modularity. The principles below still apply.

---

The ten principles

| # | Principle | Intent | |---|-----------|--------| | 1 | **Well-defined boundaries** | A small, stable **public surface**; everything else is internal. Consumers depend on contracts, not internals. | | 2 | **Composability** | Modules can be used alone or combined without special knowledge of each other’s internals. | | 3 | **Independence** | No hidden shared mutable state across boundaries; each module should be testable in isolation (with fakes or test doubles at the edges). | | 4 | **Individual scale** | Resources (compute, storage, rate limits, batch size) can be tuned **per module** where it matters, without rewriting others. | | 5 | **Explicit communication** | Cross-module interaction uses **documented contracts** (APIs, events, messages, shared types) — not incidental coupling. | | 6 | **Replaceability** | Dependencies on other modules are expressed through **interfaces or protocols** so implementations can change. | | 7 | **Deployment independence** | Modules do not assume they share a process, host, or release cadence unless that is an explicit architectural decision. | | 8 | **State isolation** | Each module **owns** its persistent state and naming; no silent sharing of the same logical data store or ambiguous global names across boundaries. | | 9 | **Observability** | Each module can be diagnosed on its own: logs, metrics, traces, health — attributable to the unit that emitted them. | | 10 | **Fail independence** | Failures are **contained** (timeouts, bulkheads, circuit breaking, idempotency) so one module’s outage does not blindly cascade. |

**Principle 8** is often the hardest: ambiguous ownership of data or names is a frequent source of “works until it doesn’t” integration bugs.

For **depth** (rules for agents + abstract examples per principle), load `references/principles.md`.

---

Typical violations (stated abstractly)

1. **Colliding concepts** — the same name or schema for different things in different modules, or duplicate “global” definitions that diverge over time. 2. **Reach-through persistence** — one module reading or writing another module’s tables, buckets, or documents **without** going through an agreed contract. 3. **Centralized data ownership** — a single persistence layer that registers and exposes **all** stores for **all** modules, encouraging hidden coupling. 4. **Logic at the edge** — business rules in transport adapters (HTTP handlers, UI, CLI) instead of domain/application code. 5. **Edge talking to storage directly** — adapters depending on low-level persistence APIs instead of use cases or application services. 6. **Unscoped transactions** — writes that span boundaries without clear transaction ownership and failure semantics. 7. **Leaky exports** — repositories, internal services, or implementation types exposed as the module’s public API. 8. **Facades that aren’t thin** — “public” entry points that embed querying, mapping, or policy instead of delegating to the right layer inside the module.

---

Creating a bounded context (workflow)

Use when introducing a **new** cohesive area of the system (greenfield module or extracted domain).

1. **Scope and language** — Name the context; list core nouns/verbs (**ubiquitous language**). Reject vague names that collide with other contexts. 2. **Responsibilities** — What decisions happen **only** here? What is explicitly *out* of scope? 3. **State ownership** — Which facts are **authoritative** in this context? Where are they stored conceptually (even if storage tech is undecided)? 4. **Public contract** — Operations and/or events other contexts may use. Version or evolve this contract intentionally. 5. **Integrations** — For each neighbor: sync call, async message, shared read model, or batch sync? Document **consistency** (immediate, eventual) and **failure** behavior. 6. **Invariants and lifecycles** — What must always be true inside this boundary? What starts/completes a lifecycle? 7. **Isolation check** — Can you test co