codebase-design
Codebase Design
This skill exists to stop: interface-first refactors from hiding, relocating, or multiplying complexity without improving leverage, locality, or testability.
🤖 0. HOW TO USE
- Design (default): shape one deep module and its smallest useful interface.
- Review: apply depth, locality, seam, deletion, and complexity-treatment checks to a proposal.
- Complexity: when state, effects, dependencies, control flow, or size drive the decision, read complexity-management.md.
- Structure: when package/module ownership, placement, naming, or dependency direction is in scope, read engineering-philosophy.md.
Output: a module/interface decision with evidence. If state, effects, dependencies, control flow, or size is the reason for the design, begin with these required fields: Essential complexity, Accidental complexity, Axes observed, Treatment per axis (reduce/isolate/accept), Complexity deleted versus relocated, and Verification by layer. Do not impose a paradigm or Functional Core / Imperative Shell on simple work.
If package/module structure is central, also emit: Capability and owner, Locality, Packages/modules and evidence for each split, Names and type placement, and Dependency DAG (allowed and forbidden edges). For a cycle, show all three candidates in order—move responsibility, merge fake boundary, consumer-owned contract—and select the first sufficient remedy, stating why each earlier candidate did or did not settle the problem. When discussing Go, distinguish its compile-time enforcement from the stack-neutral design principle.
Design deep modules: a lot of behaviour behind a small interface, placed at a clean seam, testable through that interface. Use this language and these principles wherever code is being designed or restructured. The aim is leverage for callers, locality for maintainers, and testability for everyone.