deep-modules
Apply when designing or reshaping a module's interface, deciding where a seam goes, or making code easier to test. Put a lot of behavior behind a small interface, at a seam where something really varies, and test through it.
- License 许可
- MIT
- 最近更新
- 2026-11-04
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- deep-modules
- metadata
- { "layer": "L2", "source": "mattpocock/skills@49dd158:skills/engineering/codebase-design/SKILL.md + DEEPENING.md + DESIGN-IT-TWICE.md", "license": "MIT" }
- description
- Apply when designing or reshaping a module's interface, deciding where a seam goes, or making code easier to test. Put a lot of behavior behind a small interface, at a seam where something really varies, and test through it.
02 资源文件 2
- 参考文档references/deepening.md2.5 KB
- 参考文档references/vocabulary.md2.1 KB
03 SKILL.md 正文
Deep Modules
Put a lot of behavior behind a small interface, at a seam where something actually varies, and test it through that interface.
Why: A deep module gives callers leverage (more capability per thing they must learn) and maintainers locality (change, bugs and verification gather in one place). A shallow module makes every caller learn nearly as much as the implementation knows, so complexity spreads instead of shrinking.
The interface is everything a caller must know: the signature, plus invariants, ordering, error modes, required configuration and performance. Use the exact terms in references/vocabulary.md.
Pattern:
- Shrink the interface. Fewer entry points, simpler parameters, more hidden inside. A good default makes the common call trivial.
- Depth belongs to the interface. The inside may be small swappable parts with their own internal seams; they just aren't exposed.
- One adapter is a guess; two make a seam. Add a seam only where something varies, usually production and test.
- Take dependencies, don't create them. Pass collaborators in, so a test can hand over a stand-in.
- Return results instead of mutating. A function that returns a value is easier to test than one that edits its argument in place.
- Test where callers call. Tests cross the same seam callers do. After deepening, replace the old tests on the shallow parts with tests at the new interface.
- Design it twice when the interface is a real decision. Dependency kinds, seam rules and how to compare alternatives are in references/deepening.md.
The test:
- Deletion: imagine deleting the module. If complexity vanishes, it was a pass-through. If it reappears in every caller, it was earning its keep.
- Surface: is the interface nearly as large as the implementation? Then it is shallow.
- Reach: does a test have to get past the interface to check something? Then the module is the wrong shape.
Stop: Don't measure depth as implementation lines over interface lines; that rewards padding. Don't split a module into a chain of tiny pass-throughs so each piece looks simple.
04 同仓库更多 Skills
yeet
Take every local change green through the repo's own checks, slice it into conventional commits, push, and with --pr open a pull request on the code host. Use only when the user explicitly asks to yeet, or to commit and push everything; never on your own initiative.
write-docs
Write or update documentation from the code: gather facts, pick the shape for the reader, write it plain, and prove every command and path in it. Use when asked to document a repo, module or feature, or to bring stale docs up to date.
why
Find why code is shaped the way it is (design rationale, trade-offs, regressions, odd thresholds) from history, tickets, docs and chat, citing every claim and stating its confidence. Use for 'why does X work this way', 'why did we pick Y', or before changing code whose purpose is unclear.
verify
Prove a change works with the check that matches its type, do the read-back, and log the pass against the exact tree. Use when a change is ready to call done, before review, commit or stopping, and whenever ven-decisions end refuses an unverified tree.
unslop
Cut AI writing tells (filler, model vocabulary, metaphor nouns, hedging, formatting tics) from text while keeping every fact. Use when editing or checking any prose before it ships: docs, PR bodies, reports, skill text.
type-discipline
Apply when designing types or data shapes, reviewing a signature, or handling outside data, in any language. Make wrong states fail early: in the compiler for typed languages, in validated runtime contracts for untyped ones.