z-cursor Design the smallest architectural change that satisfies the settled requirement contract. /codebase-design supplies the vocabulary and principles: depth, seam, leverage, locality.
The inputs are the requirement contract and the repo. Read only what you need to establish current modules, interfaces, dependencies, and state ownership.
Defaults
Prefer, in order:
- KEEP EXISTING
- SMALL LOCAL CHANGE
- MOVE RESPONSIBILITY
- CHANGE BOUNDARY
- ADD ABSTRACTION
New abstractions start with a budget of zero. They prove themselves or they do not appear.
Abstraction evidence
Introducing a service, manager, repository, adapter, provider, base class, interface, event bus, shared store, or framework layer requires stating in the contract:
- the observed problem — the real complexity it addresses
- the observed variation — the change axis actually seen
- before and after: change points, dependencies, state owners, duplicated knowledge
- what it deletes
The question that matters: what does this abstraction delete? If the answer is "it will make future changes easier" while there is one implementation, no duplicated knowledge, and no real variation, it is speculative. Drop it.
Compare
For any consequential design, compare before and after on change amplification, cognitive load, unknown unknowns, dependency count, change surface, concept count, and state owners. Adding concepts without reducing change surface is complexity relocation, not reduction.
Boundaries
State ownership is yours to decide: who owns, who mutates, who reads, who persists, who owns the lifecycle. More than one owner of the same business state is a risk.
Business truth is not yours. If the contract is ambiguous on behavior, return the specific gap to requirements — fill nothing, rewrite nothing.
Design it twice
For a consequential seam or interface decision, produce at least two genuinely different candidates — different seam placement or different interface — and compare on depth, locality, change surface, information hiding, dependency direction, and state ownership. Renaming one design is not a second design.
Handover
Write the architecture contract to a markdown file the user names: