codebase-design
Use when designing or improving a module's interface (deep modules, small interfaces, clean seams) or finding and assessing shallow modules worth deleting, inlining or deepening. Moves -> refactoring-catalog.
coding-agent · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add rafaelob/pragmatic-agent-skills --skill codebase-design技能说明
name: codebase-design description: "Use when designing or improving a module's interface (deep modules, small interfaces, clean seams) or finding and assessing shallow modules worth deleting, inlining or deepening. Moves -> refactoring-catalog." license: Apache-2.0 metadata: tags:
- domain-expertise
- codebase-design
- deep-modules
- ousterhout
- module-design
- seam
- testability
- interface-design version: "1.4.3" author: coding-agent category: domain-expertise subcategory: frameworks vendor: universal lifecycle: active coding_agent: true audience: developer output_format: markdown modality: text freshness: 2026-08 upstream: https://github.com/mattpocock/skills upstream_mode: adapted upstream_baseline_commit: 5b15a47f2d7150f545fbcacbfe381787fc0230dc upstream_baseline_date: 2026-08-21 upstream_author: Matt Pocock upstream_path: skills/engineering/codebase-design/SKILL.md adaptation_summary: 'Harness-neutral subagent dispatch (14bfbbd). Glossary location is left to local conventions. House Design Workflow and Checklist kept.' upstream_not_adopted: em-dash-sweep: Cosmetic 3216582; house keeps existing punctuation. Agent-tool: Cursor Task API; this catalog dispatches via the runtime in use.
Codebase Design — Deep Modules
Design deep modules: a lot of behaviour behind a small interface, placed at a clean seam, testable through that interface. Use this vocabulary and these principles wherever code is being designed or restructured. The aim is leverage for callers, locality for maintainers, and testability for everyone.
Glossary
Use these terms for the concepts below; they disambiguate "component," "service," "API," or "boundary" when those words are being used loosely for different things in the same discussion.
| Term | Definition | Avoid |
|---|---|---|
| Module | Anything with an interface and an implementation. Scale-agnostic: a function, class, package, or tier-spanning slice. | unit, component, service |
| Interface | Everything a caller must know to use the module correctly: type signature, invariants, ordering constraints, error modes, required configuration, performance characteristics. | API, signature (too narrow) |
| Implementation | What is inside a module. Distinct from Adapter: a Postgres repo is a small adapter with large implementation; an in-memory fake is a large adapter with small implementation. | — |
| Depth | Leverage at the interface: the amount of behaviour a caller or test can exercise per unit of interface they must learn. A module is deep when large behaviour sits behind a small interface; shallow when the interface is nearly as complex as the implementation. | impl-lines / interface-lines ratio |
| Seam | A place where behaviour can be altered without editing at that place (Feathers). The location at which a module's interface lives. Where to put the seam is its own design decision. | boundary (overloaded with DDD bounded context) |
| Adapter | A concrete thing that satisfies an interface at a seam. Describes role, not substance. | — |
| 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. Fix once, fixed everywhere. | — |
Deep vs Shallow
Deep module Shallow module (avoid)
┌──────────────────┐ ┌──────────────────────────────┐
│ Small Interface │ │ Large Interface │
├──────────────────┤ ├──────────────────────────────┤
│ │ │ Thin Implementation │
│ Deep Impl. │ │ (mostly pass-through) │
│ │ └──────────────────────────────┘
└──────────────────┘
When designing an interface, ask:
- Can I reduce the number of methods?
- Can I simplify the parameters?
- Can I hide more complexity inside?
Core Principles
Depth is a property of the interface, not the implementation. A deep module can be internally composed of many small, swappable parts — they just are not part of the external interface. A module can have internal seams (private to its implementation) as well as the external seam at its interface.
The deletion test. Imagine deleting the module. If complexity vanishes, it was a pass-through and is earning nothing. 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.
Two adapters are evidence of a real seam, not a requirement for one. A second adapter (typically production + test stand-in) proves something varies across the boundary, which is why it is the easiest justification to check. But it is one sufficient reason, not the only one. A seam is also justified by:
- independent volatility — the two sides change for different reasons, on different cadences;
- an external contract — the boundary is where a protocol, schema, or published API is honoured;
- a security boundary — trust, authorization, or tenancy changes across it, and collapsing it would erase the place the check belongs.
What is not a justification is a seam added because a second implementation might appear someday. Absent one of the reasons above, the seam is speculative — the cost is real now and the variation is hypothetical.
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.