Codebase Design (vocabulaire modules profonds)
A vocabulary skill, not a process one: it pins seven exact terms (module, interface, implementation, depth, seam, adapter, leverage, locality) and bans fuzzy synonyms like component, service, API or boundary. Its thesis: a good module is deep, a lot of behaviour behind a small interface, sitting on a clean seam and testable through that interface. It ships the deletion test (if deleting the module makes complexity vanish, it was a pass-through) and the rule one adapter means a hypothetical seam, two adapters mean a real one. /tdd and /improve-codebase-architecture both speak it.
Strengths
- Seven exact terms with their banned synonyms, so you and the agent finally talk about the same thing
- The deletion test gives an operational criterion where depth is usually left as intuition
- Separates where the seam goes from what sits behind it: two distinct design decisions, treated as such
- A rejected-framings section: it says what it refuses and why, rare in a design doc
Limitations
- Produces nothing tangible: without /improve-codebase-architecture to find candidates, you hold a lexicon with nothing to apply it to
- Imposes a vocabulary that clashes with your team's if they already say service or boundary
- Two external references (DEEPENING.md, DESIGN-IT-TWICE.md) you must read for the most operational part
Best for
- Devs refactoring an area who cannot say why the new version is better
- Tech leads who want a shared language for design reviews, humans and agents alike
- Codebases where every module exposes twenty methods and tests reach past the interface