codebase-design

# Codebase Design Use this Skill to improve the shape of code, not to impose generic language style. Prefer the smallest design that makes the current behavior easy to understand, test, replace, and delete. ## Start From Pressure Name the concrete pressure before proposing structure: - which behavior is hard to change or test - which dependency leaks across boundaries - which concept has more than one competing owner - which repeated call pattern proves an interface is missing Do not redesign a module because a textbook pattern could fit. Use `ponytail` to challenge speculative seams and entity growth. ## Seek Deep Modules A deep module offers a small, stable interface while hiding meaningful complexity. Move volatile policy, integration quirks, and invariants behind the narrowest owner that can enforce them. Avoid shallow wrappers that merely rename another call or spread one operation across extra files. Prefer: - one canonical owner for each durable rule - dependencies that point toward stable domain behavior - explicit inputs, outputs, errors, and side effects - public seams that support behavior tests - direct control flow when only one implementation exists ## Prove An Abstraction One adapter means a hypothetical seam; two adapters make it real. Before adding an interface, registry, factory, plugin point, or compatibility layer, show the second concrete use or an unavoidable external boundary. Apply the deletion test: if the new entity disappeared, would req...