Codebase Design gives the model a fixed glossary (module, interface, implementation, depth, seam, adapter, leverage, locality) and a set of principles for designing or restructuring code. It asks the model to use these terms exactly and to avoid component, service, API and boundary.
Two companion documents cover deepening a cluster of modules by dependency category and exploring alternative interfaces with parallel sub-agents.
What You Get
- A glossary of eight terms, with the words to avoid for each
- Principles including the deletion test, the interface as the test surface, and the rule that one adapter means a hypothetical seam while two mean a real one
- DEEPENING.md, with four dependency categories (in-process, local-substitutable, remote but owned, true external) and the testing strategy for each
- DESIGN-IT-TWICE.md, a pattern that spawns three or more sub-agents to design the interface in radically different ways and compares them on depth, locality and seam placement
Common Use Cases
- Reshaping a cluster of shallow modules into one deep module
- Deciding whether a port is justified at the boundary between your code and a third-party service
- Giving a team and its agents one consistent vocabulary for design discussions
What Makes It Unique
It defines depth as leverage at the interface and sets aside the ratio of implementation lines to interface lines, because that ratio rewards padding. It gives a concrete test for whether a seam is real, and a replace-the-old-tests rule for testing a deepened module. A Rejected framings section names the alternatives it set aside.
Under The Hood
The skill is reference text with no scripts. The model reads SKILL.md when a design task matches its description, and loads DEEPENING.md or DESIGN-IT-TWICE.md when it needs them. The design-it-twice pattern starts sub-agents with fresh context windows. The skill itself runs no commands and reaches no network.