design

Define the boundaries between components, name the exact files and function signatures, and record the trade-offs of alternatives considered. Attach a test or typecheck command to each unit of work so the design is verifiable.

Use a design phase when a change has unsettled interfaces, contracts, file structure, or verification boundaries. Trivial changes with clear requirements can proceed directly to implementation without a separate design step.

An ADR records a decision that is hard to reverse or drives a quality attribute like performance, security, or scalability. Write one for each architecturally-significant decision, listing options scored against the quality attributes that matter.

Require every design element to trace back to a requirement and favor the simplest design that satisfies them. Prefer stable interfaces over clever internals, and apply information hiding so likely-to-change decisions stay behind interfaces.

Designs must be grounded in exact path:line evidence of the current architecture, or they drift from reality. When a design mainly preserves accumulated exceptions, run a simplification analysis with a falsification test before replacing the current model.