codebase-design
Shared vocabulary and method for designing deep modules — much behaviour behind a small interface, placed at a real seam, tested through that interface. Use when designing or reshaping a module's interface, deciding where a seam belongs, finding shallow pass-through code worth merging, making code easier to test or navigate, or when another skill needs this vocabulary.
- License 许可
- MIT
- 最近更新
- 2026-09-25
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- codebase-design
- description
- Shared vocabulary and method for designing deep modules — much behaviour behind a small interface, placed at a real seam, tested through that interface. Use when designing or reshaping a module's interface, deciding where a seam belongs, finding shallow pass-through code worth merging, making code easier to test or navigate, or when another skill needs this vocabulary.
- allowed-tools
- [ "Read", "Grep", "Glob" ]
03 SKILL.md 正文
Codebase Design
Purpose
Give design conversations one precise language and a small set of tests for whether a structure earns its keep.
The skill produces recommendations and interface sketches in the conversation; it edits no code and records no
decision. Implementation belongs to the workflow plugin doing the work; the eventual decision record belongs to
rinnegan.
Trigger Conditions
Use this skill when the user is shaping a new module, unhappy with a wide or leaky interface, choosing where an abstraction should sit, or asking why code is hard to test or hard to find.
Do not use it to review a finished change for defects (sharingan), to define business terms
(domain-modeling), or to map an unfamiliar repository (codebase-onboarding).
Vocabulary
Use these words exactly; substitutes blur the discussion.
| Term | Meaning | Say it instead of |
|---|---|---|
| Module | Anything with an interface and an implementation, at any scale | unit, component, service |
| Interface | All a caller must know: signature, invariants, ordering, error modes, setup, cost | API, signature |
| Implementation | The body behind the interface | — |
| Seam | The place where behaviour can be swapped without editing there; where an interface lives | boundary |
| Adapter | A concrete thing that satisfies an interface at a seam; names a role, not a size | — |
| Depth | Behaviour a caller gets per unit of interface learned | — |
| Leverage | The caller's gain from depth: one implementation repaid across many call sites and tests | — |
| Locality | The maintainer's gain from depth: change, bugs, and knowledge concentrate in one place | — |
A module is deep when a small interface hides a lot; shallow when the interface is nearly as wide as what sits behind it. Depth is a property of the interface, so a deep module may still be built from small, swappable internal parts with their own private seams.
Method
- Name the module and write its interface in full — types, invariants, ordering, failure modes, required setup, performance shape. If that list is long relative to the behaviour, the module is shallow.
- Apply the deletion test: imagine the module gone. If complexity disappears, it was pass-through; if it reappears across several callers, it was earning depth.
- Place the seam only where something varies. One adapter is a hypothetical seam; two (usually production and test) make it real. Classify each dependency to decide the testing shape: pure in-process logic merges freely; a dependency with a local stand-in is tested with the stand-in; a service you own gets a port with a production adapter and an in-memory one; a third-party service gets a port with a test double.
- Check testability through the interface alone: dependencies are accepted rather than constructed inside, results are returned rather than applied as side effects, and tests describe behaviour, not internals. A test that must change when the implementation changes is reaching past the interface.
- Design it twice, inline. Before recommending, sketch the interface at least three different ways in this session, each under a different pressure — fewest entry points, most flexibility, easiest common call, and ports-and-adapters when a dependency crosses a seam. Present them in turn, compare on depth, locality, and seam placement, and give a firm recommendation or a hybrid. No subagents are dispatched for this.
- When shallow modules are merged, write new tests at the deepened interface and retire the old ones on the parts; layering both is waste.
Safety Checks
- Read-only: the skill reads code and writes nothing (C-3).
- Do not adopt lines-of-implementation over lines-of-interface as a depth measure; it rewards padding.
- Language- and framework-specific idioms enter only when the user asks for them (P-2).
Output Contract
- Module and interface — the full interface as it stands, and the depth verdict
- Alternatives — the sketches from step 5, compared
- Recommendation — the chosen shape, seam placement, dependency strategy, and test surface
04 同仓库更多 Skills
good-skill
Fixture - a skill whose name equals its directory and whose description clears the forty-character floor (N-2).
wrong-name
Too short.
<skill-name>
<What the skill does, then the situations that should trigger it. Concrete and situational, third person, never marketing. Minimum 40 characters — this text is the auto-invocation surface (N-2).>
writing-plans
Turns an agreed design or spec into a step-by-step implementation plan that an engineer with no context could execute. Use when a multi-step change is understood well enough to sequence but no plan exists yet, before touching code. Produces a plan file with exact paths, test-first steps, interfaces between tasks, and no placeholders.
verification-before-completion
Gate that runs before any claim that work is done, fixed, passing, or shipped. Identifies the command that would prove the claim, runs it fresh, reads the whole output, and only then reports — with the evidence attached and any gap stated. Use before committing, opening a pull request, marking a task complete, or telling the user something works.
using-skills
Session discipline that fires before the first action of any task. Checks whether an installed skill or command already covers the job, keeps every action inside the requested scope, and reports verification as evidence rather than confidence. Use at the start of a conversation, before answering a question, before exploring a codebase, and whenever a task changes shape mid-session.