跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
设计与 UI

design-it-twice

Use before committing to a non-trivial module, service boundary, or public API - generate 2-3 divergent interface designs, compare them on depth/locality/seam, and recommend one

etr · 已有静态检查记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add etr/groundwork --skill design-it-twice

技能说明


name: design-it-twice description: Use before committing to a non-trivial module, service boundary, or public API - generate 2-3 divergent interface designs, compare them on depth/locality/seam, and recommend one allowed-tools: ["Read", "Glob", "Grep", "Task"]

Design It Twice

Overview

Your first interface is rarely your best (Design it twice, Ousterhout). Before you commit a module boundary, generate genuinely different designs and compare them — the cost of exploring on paper is trivial next to the cost of a shallow interface that Hyrum's Law then freezes into a contract.

Core principle: Aim for deep modules — a simple interface hiding substantial functionality. A design that merely forwards calls is shallow and usually a liability.

This is a build-time and architecture-time discipline. [[design-architecture]] and [[swarm-design-architecture]] invoke it for module boundaries; invoke it directly any time you're about to design a single non-trivial interface.

When to Use

  • A new module, service boundary, or public API
  • A refactor that reshapes an existing interface many callers depend on
  • Any seam where a future change is likely to land and you want it to land in one place

Skip for trivial or single-call-site code, or interfaces fully dictated by an existing contract.

Process

1. Frame the problem space

Before generating alternatives, write down the constraints, dependencies, the dominant use case, and a rough code sketch of the interface. Use the project's domain language (see [[domain-modeling]]). Vague framing yields vague designs.

2. Generate 2–3 divergent designs

Each design optimizes one distinct goal — they must genuinely differ, not be three shades of the same idea:

LensOptimizes for
Minimize entry pointsFewest interfaces, maximum leverage per surface — a deep module
Maximize flexibilityReuse across the widest set of use cases
Optimize the common caseSimplest path for the dominant workflow
Isolate seamsCross-boundary dependencies behind ports & adapters

Orchestration: if the Agent/Task tool is available, fan out one agent per design in parallel, each with the same framing and a different lens. No agent teams or debate are needed — the designs are independent. If agents are unavailable, produce the designs sequentially yourself. Each brief returns the interface sketch plus its trade-offs.

3. Compare on three axes

  • Depth — functionality hidden behind the interface vs. surface exposed. Favor depth; mind Hyrum's Law on every exposed behavior.
  • Locality — where a likely future change concentrates (one module vs. scattered across callers).
  • Seam placement — whether boundaries fall where the system actually flexes.

4. Recommend, don't enumerate

Give an opinionated recommendation — which design solves the problem best and why — possibly a hybrid that grafts the best of two. A neutral menu pushes the judgment onto the reader and defeats the exercise.

Named principles referenced here are defined in ${CLAUDE_PLUGIN_ROOT}/references/engineering-principles.md.

Rationalizations

ExcuseReality
"My first design is obviously right"That feeling is exactly when a second design most often beats it. Cost of checking is one sketch.
"Three designs is slower"Slower than reworking a shallow interface every caller already depends on? No.
"They'd all come out the same"Then your lenses aren't divergent. Force distinct optimization goals.
"I'll just present the options and let them pick"A menu without a recommendation is unfinished work. Take a position.

Red Flags

  • The alternatives differ only cosmetically (same interface, renamed)
  • A "design" that forwards calls with no functionality hidden (shallow module)
  • Comparing on taste rather than depth / locality / seam
  • Ending with "any of these could work" instead of a recommendation

Verification

  • Problem space framed: constraints, dominant use case, interface sketch
  • 2–3 designs, each optimizing a genuinely distinct goal
  • Compared explicitly on depth, locality, and seam placement
  • A single opinionated recommendation (or justified hybrid), with reasoning