AGENT SKILL

codebase-design

Shared vocabulary and principles for designing deep modules: a lot of behaviour behind a small interface, at a clean seam, testable through that interface. Use when designing or reshaping a module's interface, deciding where a seam goes, making code more testable or easier for agents to navigate, and when another skill needs the deep-module vocabulary.

适用职业设计师
使用场景视觉设计
License 许可
Apache-2.0
最近更新
2026-11-13
Stars
★ 0
Forks
1

01 前言 Front Matter

name
codebase-design
description
Shared vocabulary and principles for designing deep modules: a lot of behaviour behind a small interface, at a clean seam, testable through that interface. Use when designing or reshaping a module's interface, deciding where a seam goes, making code more testable or easier for agents to navigate, and when another skill needs the deep-module vocabulary.

02 资源文件 3

03 SKILL.md 正文

Codebase Design

Design deep modules: a lot of behaviour behind a small interface, placed at a clean seam, testable through that interface. The aim is leverage for callers, locality for maintainers, and testability for everyone.

Vocabulary

Use these terms exactly; consistent words are the point.

  • Module: anything with an interface and an implementation, at any scale: a function, class, package, or slice across tiers. Avoid: unit, component, service.
  • Interface: everything a caller must know to use the module correctly: the signature plus invariants, ordering constraints, error modes, required configuration, and performance characteristics. Avoid: API, signature (both name only the type-level surface).
  • Implementation: the code inside a module.
  • Depth: leverage at the interface, the behaviour a caller or test can exercise per unit of interface they have to learn. The deep-module idea is Ousterhout's; measuring it as leverage rather than as a ratio of implementation lines to interface lines is deliberate, since a line ratio rewards padding. Deep: much behaviour behind a small interface. Shallow: the interface is nearly as complex as the implementation.
  • Seam (Michael Feathers): a place where behaviour can change without editing that place; where a module's interface lives. Where to put it is a design decision of its own. Avoid: boundary (overloaded with DDD's bounded context).
  • Adapter: a concrete thing that satisfies an interface at a seam. It names a role, not a size: a thin adapter can wrap a large implementation.
  • Leverage: what callers gain from depth; one implementation pays back across many call sites and tests.
  • Locality: what maintainers gain from depth; change, bugs, and knowledge concentrate in one place.

Principles

  • Depth belongs to the interface. A deep module can be built from small, swappable parts inside; they just aren't part of its interface. A module can have internal seams for its own tests as well as the external seam callers use.
  • The deletion test. Imagine deleting the module. If complexity vanishes, it was a pass-through. If complexity reappears across many callers, it was earning its keep.
  • The interface is the test surface. Callers and tests cross the same seam. Wanting to test past the interface means the module is the wrong shape.
  • One adapter means a hypothetical seam; two adapters mean a real one. Introduce a seam only when something actually varies across it (typically production and test).

Designing for testability

  • Accept dependencies; don't construct them. processOrder(order, paymentGateway) is testable; a function that builds its own gateway is not.
  • Return results rather than producing side effects where the caller can apply them: calculateDiscount(cart): Discount over applyDiscount(cart): void.
  • Keep the surface small. Fewer methods mean fewer tests; fewer parameters mean simpler setup. For any interface, ask: can it have fewer methods, simpler parameters, or hide more inside?

Going deeper

  • Deepening a cluster of shallow modules given their dependencies (in-process, local stand-in, remote but owned, true external), seam discipline, and replacing old tests rather than layering on them: DEEPENING.md.
  • Exploring alternative interfaces with parallel subagents, each designing under a different constraint, then comparing on depth, locality, and seam placement: DESIGN-IT-TWICE.md.

04 同仓库更多 Skills

dougborg
dougborg/harness-kit

teach

Teach yourself a topic over several sessions, with lessons, references, and a record of what you've learned.

教师与教育
★ 0
dougborg
dougborg/harness-kit

svg-logo-designer

Generate SVG logos with multiple concepts, layouts, and color variations.

图像与多媒体
★ 0
dougborg
dougborg/harness-kit

documentation-writer

Writes and revises human-facing documentation — READMEs, contributor and setup guides, reference pages, architecture notes, CLAUDE.md, and changelog entries. Covers picking the right document type for the question being asked, structuring for skimming, writing examples that actually run, and keeping docs from going stale. Use when creating or rewriting docs, when a README has drifted from the code, or when deciding where a piece of information belongs. For SKILL.md and agent files, use /skill-writer instead.

内容创作者写作与文案
★ 0
dougborg
dougborg/harness-kit

adhd-mode

Shapes every response for a reader with ADHD: the next action first, numbered steps, progress restated each turn, tangents held back, concrete time estimates, wins made visible. Stays on for the rest of the session until the reader says "stop adhd mode". On Claude Code, the harness-kit:adhd output style does the same without invoking this skill.

★ 0
dougborg
dougborg/harness-kit

wait-what

That last message didn't land: re-explain it with the missing context.

★ 0
dougborg
dougborg/harness-kit

to-questionnaire

Turn a decision you can't make alone into a questionnaire for the one person who can answer it, filled in async or together in a meeting.

★ 0