design-an-interface
Produce 3+ radically different designs for a module, API, or interface, compare them in prose, and synthesize a recommendation. Use when asked to "design an interface", "shape this API", "design it twice", "explore module boundaries", or when planning a new deep module and the first idea is unlikely to be the best. Based on "Design It Twice" from A Philosophy of Software Design — the value is the contrast, not the first draft.
- License 许可
- MIT
- 最近更新
- 2026-11-06
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- design-an-interface
- description
- Produce 3+ radically different designs for a module, API, or interface, compare them in prose, and synthesize a recommendation. Use when asked to "design an interface", "shape this API", "design it twice", "explore module boundaries", or when planning a new deep module and the first idea is unlikely to be the best. Based on "Design It Twice" from A Philosophy of Software Design — the value is the contrast, not the first draft.
03 SKILL.md 正文
<objective> Generate at least three radically different interface designs for a single module or API, present them sequentially, compare them honestly, and recommend one (or a hybrid). The goal is to surface the design space — not to pick fast. A small interface hiding significant complexity is a deep module; a large interface with thin implementation is a shallow one. Optimize for the former. </objective>
<context>
This skill runs during planning — before S##-PLAN.md task decomposition, or mid-slice when a seam turns out to be more load-bearing than the roadmap assumed. It is not for picking between two libraries. It is for shaping the interface your own code will expose.
Typical invocation points:
- A slice plan says "add module X" and the shape of X is not obvious.
- Two callers are about to grow coupled to an interface that has not been designed on purpose.
- A refactor surfaces a seam that needs to be re-cut deliberately. </context>
<core_principle> RADICALLY DIFFERENT, NOT VARIANTS. Three designs with different method names are one design. Three designs that hide different things, expose different axes of control, or invert the caller/callee relationship are three designs. Enforce real divergence by assigning each sub-agent a constraint that would force a different shape.
INTERFACE, NOT IMPLEMENTATION. Do not estimate effort. Do not argue about how hard it is to build. Argue about how the interface behaves from the caller's side and what it hides internally. </core_principle>
<process>
Step 1: Gather requirements
Before spawning anything, answer in the conversation:
- What problem does the module solve?
- Who calls it? (other modules, external users, tests)
- What are the key operations?
- What constraints exist? (performance, compatibility, existing patterns)
- What should stay hidden inside vs be exposed?
If the user did not supply all of these, ask — one round, 1–3 questions max, per the ask-vs-infer rule.
Step 2: Spawn parallel design agents
Use Agent(subagent_type=general-purpose) for 3–4 agents in one message so they run concurrently. Each agent gets the same requirements brief plus one divergent constraint:
- Agent 1: "Minimize method count — 1 to 3 entry points max."
- Agent 2: "Maximize flexibility — support many extension points and composition."
- Agent 3: "Optimize for the single most common caller — make the default case trivial and the advanced case possible."
- Agent 4 (optional): "Design around a ports-and-adapters boundary — interface is the port, concrete implementations are adapters."
Each agent returns:
- Interface signature (types, methods, params)
- One worked usage example showing a real caller
- What complexity this design keeps internal
- Trade-offs — what it's bad at
Step 3: Present sequentially
Show the three designs one after another. Let the user read each before the next. Do not lead with the comparison — the value is in feeling the shape of each option first.
Step 4: Compare in prose
After all three are on the page, compare them on:
- Simplicity — fewer methods and simpler params are easier to learn and harder to misuse
- Depth — small interface hiding significant complexity (good) vs large interface with thin implementation (bad)
- Generality vs specialization — does it cover the real use case without overfitting?
- Efficiency of the shape — does the interface let the implementation be efficient, or force awkward internals?
- Misuse surface — what can a caller do wrong?
Prose, not a table. Highlight where the designs diverge most sharply — that is where the interesting trade-off lives.
Step 5: Recommend
Be opinionated. Pick one, or propose a hybrid that takes specific elements from multiple designs. State the reason in one paragraph. The user wants a strong read, not a menu.
Step 6: Capture the decision
Once the user picks:
- Append to
.gsd/DECISIONS.mdwith the chosen shape and the reason. - If a slice is active, update
S##-CONTEXT.mdwith the interface sketch. - Do not write the implementation — that happens during execute.
</process>
<anti_patterns>
- Three-variants-of-the-same-idea: all three use a builder, all three return the same object, etc. Kill and re-spawn.
- Implementation creep: proposing file paths, call graphs, or internal data structures. Keep it at interface shape.
- Skipping comparison: presenting three designs and asking "which do you like?" The comparison is the whole skill.
- Effort-based ranking: "#2 is easiest to build" is not an interface argument. Rank by what the caller experiences.
</anti_patterns>
<success_criteria>
- [ ] 3+ genuinely different interface shapes were produced.
- [ ] Each design shows a real usage example, not a type signature in isolation.
- [ ] Trade-offs are named per design.
- [ ] A specific recommendation (or hybrid) is on the page with a reason.
- [ ] The decision is captured in
.gsd/DECISIONS.mdor the activeS##-CONTEXT.md.
</success_criteria>
04 同仓库更多 Skills
write-milestone-brief
Synthesize the current conversation into a milestone brief (PRD). Writes to `M###-CONTEXT.md` by default, or files a GitHub issue only with explicit user confirmation. Use when asked to "turn this into a PRD", "draft a milestone brief", "capture this context", "write it up", or when enough has been discussed to commit the plan to paper. Does not interview — it synthesizes what is already known.
write-docs
Collaborative authoring workflow for proposals, technical specs, decision docs, READMEs, ADRs, and long-form prose that must work for fresh readers. Three stages: gather context, iterate on structure, reader-test for a stranger. Use when asked to "write the docs", "draft a proposal", "write a spec", "write an RFC", "write the README", or when a doc must be understandable without this session's context.
web-quality-audit
Comprehensive web quality audit covering performance, accessibility, SEO, and best practices. Use when asked to "audit my site", "review web quality", "run lighthouse audit", "check page quality", or "optimize my website".
web-design-guidelines
Review UI code for Web Interface Guidelines compliance. Use when asked to "review my UI", "check accessibility", "audit design", "review UX", or "check my site against best practices".
verify-before-complete
Block completion claims until verification evidence has been produced in the current message. Use before marking a task/slice/milestone complete, before creating a commit or PR, before saying "it works" or "tests pass", and any time you are about to claim work is done. The rule is: evidence before claims, always — running the verification must happen now, not "earlier in the session". Fresh output or no claim.
userinterface-wiki
UI/UX best practices for web interfaces. Use when reviewing animations, CSS, audio, typography, UX patterns, prefetching, or icon implementations. Covers 11 categories from animation principles to typography. Outputs file:line findings.