AGENT SKILL

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

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

Ventorius
Ventorius/ven-stack

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.

★ 0
Ventorius
Ventorius/ven-stack

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.

★ 0
Ventorius
Ventorius/ven-stack

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.

★ 0
Ventorius
Ventorius/ven-stack

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.

★ 0
Ventorius
Ventorius/ven-stack

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.

★ 0
Ventorius
Ventorius/ven-stack

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.

★ 0