Design Principles

# Architecture Catalog

Structural design decisions that require judgment, applied before and while code is written, not mechanically checkable.

→ Destination: `AGENTS.md` (# Design Principles section)

## Module Boundaries

- **Deep Modules** → Prefer modules with simple interfaces that hide substantial implementation; depth, not a thin pass-through, is what earns a module its interface.
  > Pick when: classes are mostly thin wrappers, the interface is nearly as wide as the implementation, or many tiny single-method classes ("classitis") fragment the logic.

- **Information Hiding** → A design decision (file format, schema, protocol, algorithm) lives in exactly one module; the same knowledge must not surface in modules that then have to change together.
  > Pick when: the same format or assumption is duplicated across modules, or one conceptual change forces edits in several places that each "know" the detail.

- **Tell, Don't Ask** → Tell an object what to do and let it act on its own state, rather than querying its state and deciding on its behalf.
  > Pick when: callers inspect an object's fields to decide what to do, logic that belongs inside a type leaks into its consumers, or feature envy appears across boundaries.

## Coupling

- **Law of Demeter** → Talk only to immediate collaborators: call methods on self, parameters, owned fields, or objects you created; never on objects returned by other calls.
  > Pick when: chains of three or more calls reach through object graphs ("train wrecks"), or a change in a distant class breaks unrelated callers.

### Sources

- [Deep Modules](https://web.stanford.edu/~ouster/cgi-bin/aposd.php) → John Ousterhout, "A Philosophy of Software Design" (2018)
- [Information Hiding](https://en.wikipedia.org/wiki/Information_hiding) → David Parnas (1972); revived as "information leakage" by Ousterhout (2018)
- [Tell, Don't Ask](https://martinfowler.com/bliki/TellDontAsk.html) → Martin Fowler; origin Andy Hunt & Dave Thomas, "The Pragmatic Programmer"
- [Law of Demeter](https://en.wikipedia.org/wiki/Law_of_Demeter) → Karl Lieberherr et al., Demeter Project (1987)


# Design Catalog

Pre-implementation design decisions that require judgment, not mechanically checkable.

→ Destination: `AGENTS.md` (# Design Principles section)

## Module Design

- **SRP** → A module should have one, and only one, reason to change: responsible to one actor.
  > Pick when: modules mix unrelated concerns, a change in one feature breaks another, or a class serves multiple actors.

- **OCP** → Software entities should be open for extension but closed for modification.
  > Pick when: adding features requires editing existing working code, switch statements grow with each new variant, or plugin/strategy patterns would eliminate modification.

- **LSP** → Objects of a supertype shall be replaceable with objects of a subtype without altering program correctness.
  > Pick when: subclasses override behavior in ways that surprise callers, downcasts appear in consuming code, or inheritance hierarchies violate parent expectations.

- **ISP** → No client should be forced to depend on methods it does not use; prefer many client-specific interfaces over one general-purpose interface.
  > Pick when: interfaces have methods most implementors stub out, consumers depend on large objects but only use a fraction, or mock setup is painful because of unused surface area.

- **DIP** → High-level modules should not depend on low-level modules. Both should depend on abstractions; abstractions should not depend on details.
  > Pick when: business logic imports infrastructure directly, swapping a database or API client requires touching core code, or testing requires standing up real dependencies.

- **Composition Over Inheritance** → Default to composition; use inheritance only when the subtype genuinely satisfies LSP and the hierarchy is closed to further extension.
  > Pick when: class hierarchies deepen beyond two levels, subclasses overri