codebase-design
Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary.
- License 许可
- MIT
- 最近更新
- 2026-11-14
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- codebase-design
- description
- Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary.
02 资源文件 3
- 参考文档agents/openai.yaml102 B
- 参考文档DEEPENING.md2.5 KB
- 参考文档DESIGN-IT-TWICE.md2.6 KB
03 SKILL.md 正文
Codebase Design
Design deep modules: much behaviour behind a small interface, placed at a clean seam, testable through that interface. Use this language and these principles wherever code is designed or restructured. Aim: leverage for callers, locality for maintainers, testability for everyone.
Glossary
Use these terms exactly — don't substitute "component," "service," "API," or "boundary." Consistent language is the whole point.
Module — anything with an interface and an implementation. Deliberately scale-agnostic: a function, class, package, or tier-spanning slice. Avoid: unit, component, service.
Interface — everything a caller must know to use the module correctly: the type signature, but also invariants, ordering constraints, error modes, required configuration, and performance characteristics. Avoid: API, signature (too narrow — type-level surface only).
Implementation — what's inside a module, its body of code. Distinct from Adapter: a thing can be a small adapter with a large implementation (a Postgres repo) or a large adapter with a small implementation (an in-memory fake). Reach for "adapter" when the seam is the topic; "implementation" otherwise.
Depth — leverage at the interface: behaviour a caller (or test) can exercise per unit of interface learned. A module is deep when much behaviour sits behind a small interface, shallow when the interface is nearly as complex as the implementation.
Seam (Michael Feathers) — a place where you can alter behaviour without editing in that place; the location at which a module's interface lives. Where to put the seam is its own design decision, distinct from what goes behind it. Avoid: boundary (overloaded with DDD's bounded context).
Adapter — a concrete thing that satisfies an interface at a seam. Describes role (what slot it fills), not substance (what's inside).
Leverage — what callers get from depth: more capability per unit of interface learned. One implementation pays back across N call sites and M tests.
Locality — what maintainers get from depth: change, bugs, knowledge, and verification concentrate in one place rather than spreading across callers. Fix once, fixed everywhere.
Deep vs shallow
Deep module = small interface + lots of implementation:
┌─────────────────────┐
│ Small Interface │ ← Few methods, simple params
├─────────────────────┤
│ │
│ Deep Implementation│ ← Complex logic hidden
│ │
└─────────────────────┘
Shallow module = large interface + little implementation (avoid):
┌─────────────────────────────────┐
│ Large Interface │ ← Many methods, complex params
├─────────────────────────────────┤
│ Thin Implementation │ ← Just passes through
└─────────────────────────────────┘
When designing an interface, ask:
- Can I reduce the number of methods?
- Can I simplify the parameters?
- Can I hide more complexity inside?
Principles
- Depth is a property of the interface, not the implementation. A deep module can be internally composed of small, mockable, swappable parts — they just aren't part of the interface. A module can have internal seams (private to its implementation, used by its own tests) as well as the external seam at its interface.
- The deletion test. Imagine deleting the module. If complexity vanishes, it was a pass-through. If complexity reappears across N callers, it was earning its keep.
- The interface is the test surface. Callers and tests cross the same seam. If you want to test past the interface, the module is probably the wrong shape.
- One adapter means a hypothetical seam. Two adapters means a real one. Don't introduce a seam unless something actually varies across it.
Designing for testability
Good interfaces make testing natural:
-
Accept dependencies, don't create them.
// Testable function processOrder(order, paymentGateway) {} // Hard to test function processOrder(order) { const gateway = new StripeGateway(); } -
Return results, don't produce side effects.
// Testable function calculateDiscount(cart): Discount {} // Hard to test function applyDiscount(cart): void { cart.total -= discount; } -
Small surface area. Fewer methods = fewer tests. Fewer params = simpler test setup.
Relationships
- A Module has exactly one Interface (the surface it presents to callers and tests).
- Depth is a property of a Module, measured against its Interface.
- A Seam is where a Module's Interface lives.
- An Adapter sits at a Seam and satisfies the Interface.
- Depth produces Leverage for callers and Locality for maintainers.
Rejected framings
- Depth as ratio of implementation-lines to interface-lines (Ousterhout): rewards padding the implementation. Use depth-as-leverage instead.
- "Interface" as the TypeScript
interfacekeyword or a class's public methods: too narrow — interface here includes every fact a caller must know. - "Boundary": overloaded with DDD's bounded context. Say seam or interface.
Going deeper
- Deepening a cluster given its dependencies — see DEEPENING.md: dependency categories, seam discipline, and replace-don't-layer testing.
- Exploring alternative interfaces — see DESIGN-IT-TWICE.md: spin up parallel sub-agents to design the interface several radically different ways, then compare on depth, locality, and seam placement.
04 同仓库更多 Skills
writing-design-docs
Use when the user wants to write a problem-statement design doc, says "let's plan a feature properly" / "write a design doc" / "I'm thinking about how to do X" for a non-trivial X, or before committing to a non-obvious technical direction
write-doc
Use when the user asks to write or draft a README, ADR, runbook, tutorial, how-to, explanation, or reference doc, or a caller passes "type ADR" or "type README". Picks the type, fills a template, adds diagrams. RFCs and design docs belong to writing-design-docs.
review-doc
Use when the user asks to review, critique, score, grade, or "how good is this doc" for a Markdown doc or pasted text. Read-only. Scores it on the 20 Practical Prose dimensions and emits a findings table. Does not edit; fix-doc applies the findings next.
fix-doc
Use when the user asks to fix, edit for prose quality, polish, tighten, humanize, or de-slop a Markdown doc or pasted text, or says "make this read less AI". Applies review-doc findings, generates flagged diagrams, lists substantive issues for the author, then runs the AI-tell pass last. Modifies the target.
create-slides
Use when the user asks for a slide deck, presentation, talk, or slides from a document, report, PR, notes, or topic. Builds one self-contained Machinify-branded HTML deck in a minimalist style, with headline-plus-visual slides, speaker notes, and every diagram drawn by architecture-design:create-diagram.
start-session
Open a Claude Code working session in a fresh, isolated git worktree, so the user can start a task with a single /start-session <name>. Use at the START of a session when the user says "start session", "start a worktree", "spin up a worktree for ABC-123", "begin work on <ticket>", or passes a name/ticket to work under. Creates and ENTERS a worktree via the EnterWorktree tool (never `git worktree add`) under .claude/worktrees/, named exactly after the argument, on a local branch `worktree-<argument>`. Reports what the worktree inherited (`.worktreeinclude` copies, symlinked node_modules) and whether its `.env` still points at the main checkout's stack. If the argument is a JIRA key (e.g. ABC-123, PROJ-1505), also loads that story with the Atlassian CLI (`acli`) when available and summarizes the implementation ask. Also renames the session to the argument (the same effect as `/rename <NAME>`) so it's easy to find in `/resume`. Then stops and waits — it sets up the workspace and context, it does not implement.