AGENT SKILL

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

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. 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.
  6. 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

  1. Module and interface — the full interface as it stands, and the depth verdict
  2. Alternatives — the sketches from step 5, compared
  3. Recommendation — the chosen shape, seam placement, dependency strategy, and test surface

04 同仓库更多 Skills

coltonbearden
coltonbearden/awakened

good-skill

Fixture - a skill whose name equals its directory and whose description clears the forty-character floor (N-2).

★ 0
coltonbearden
coltonbearden/awakened

wrong-name

Too short.

★ 0
coltonbearden
coltonbearden/awakened

<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).>

★ 0
coltonbearden
coltonbearden/awakened

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.

★ 0
coltonbearden
coltonbearden/awakened

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.

★ 0
coltonbearden
coltonbearden/awakened

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.

★ 0