SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsto-design

to-design

Design & creation

View repository

Updated 10-15 23:46

About this skill

to-design — PRD to Design Document

Turn a PRD (or a rough idea) into a design document written in the style of Go's official design proposals: plain language, concrete examples, and—above all—an honest account of why this approach and not the alternatives.

This is not the same as prd-to-spec. A SPEC is an implementation contract (tables, endpoints, schemas) for an engineer to build against. A design document is a decision artifact: it argues for an approach, surfaces the tradeoffs, and lets a team agree on the same facts before anyone writes code. When the question is "how should we build this and why", produce a design doc; when the question is "give me the exact contract to implement", produce a SPEC.

The design philosophy comes from an analysis of 5 official Go proposals (generics / error wrapping / loopvar / slog / try). Core belief:The value of a document does not depend on whether the proposal is accepted, but on whether it makes the discussion rest on the same set of facts and trade-offs.

When to Use

  • A PRD exists and you need to decide how to build it before committing to implementation
  • The approach has real tradeoffs and you want them documented and debated
  • The change is risky, breaking, or hard to reverse (a design doc forces the compatibility conversation early)
  • Multiple people need to agree on a direction before work fans out
  • You want a durable record of "why we chose X and rejected Y" — even if the proposal is later rejected

If the team just needs the concrete contract to code against, use /prd-to-spec instead (or run to-design first, then prd-to-spec).

The Job

  1. Locate input — find or receive the PRD (or idea)
  2. Analyze context (optional) — scan the codebase for existing patterns, constraints, and prior art
  3. Surface the decisions — identify the real design forks and ask clarifying questions (max 3-5)
  4. Generate the design doc — following the structure and writing style below
  5. Review — present for feedback, especially on the Rationale and Compatibility sections
  6. Save — write to the agreed location

Step 1: Locate Input

Provide the PRD (or idea) to design from:

A. File path (e.g., tasks/prd-priority-system.md)
B. GitHub Issue URL
C. Paste content directly
D. Just describe the idea — I'll design from the conversation

A design doc can start from a half-formed idea, not only a polished PRD. If the input is thin, lean harder on Step 3.

Step 2: Analyze Context (Optional)

Skip for greenfield. Otherwise scan to ground the design in reality:

  • Existing patterns the design should match (naming, error handling, module boundaries)
  • Prior art — has something similar been tried or rejected here before?
  • Constraints — compatibility promises, public APIs, data the design can't break
  • Real pain — find the actual buggy/awkward code the design fixes, so Background can quote it

The most persuasive Background sections quote real code from the user's own repo, not hypotheticals.

Step 3: Surface the Decisions

A design doc lives or dies on its Rationale. Before writing, find the real forks in the road — the points where a competent engineer could reasonably go two ways — and resolve them.

Ask only about genuine forks:

Design decisions to settle before I write the doc:

1. Where does this logic live?
   A. Extend the existing X
   B. New standalone component Y
   C. Let me recommend based on the codebase

2. Is this a breaking change for existing callers?
   A. Yes — needs a migration path
   B. No — purely additive
   C. Unsure — I'll analyze and flag it

3. What's the one promise this design must keep? (e.g. backward compatibility,
   latency budget, no new dependencies)

For every fork, also note the option you are NOT choosing — that becomes the Rationale.

Step 4: Design Document Structure

This is the standard skeleton distilled from the 5 Go proposals. Keep section names; drop sections that genuinely don't apply (and say why if the omission is notable).

Title: <一句话说清"做什么" —— 标题就是结论，不是名词短语>
Author(s): <作者>
Last updated: <YYYY-MM-DD>
Discussion at <issue / PR / 文档链接>   # 让文档不孤立，永远附讨论入口
Status: Draft | Under review | Accepted | Rejected

## Abstract / 摘要

一段话讲完全文：做什么、大致怎么做、以及**最重要的那个承诺**（如"向后兼容""不引入新依赖"）。
读者读完这一段就该知道全貌。把隐含的核心约束埋在这里。

## Background / 背景与动机

用**具体、可感的例子**说明"痛在哪"，而不是抽象地说"现状不好"。
- 能贴一段真实的 bug 代码 / 别扭的调用，就贴。先让读者"疼"起来。
- 量化痛点（出现频率、踩坑次数、损失），不要用形容词堆砌。
- 一句话给问题定性。

## Design / Proposal / 设计

文档主体。遵循三条：
- **从简单到复杂，渐进式教学**：从最小例子起步，复杂场景留到读者有直觉之后。
- **声明 + 示例 + 边界**三件套：每个 API/接口先给声明，再给用法片段，再划清适用边界。
- **改造前 vs 改造后对照**：能并排展示收益的，就并排展示。
能用一段可运行代码说清的，绝不用一段文字描述。

## Rationale / 理由与取舍

> Rationale = "为什么是这个方案，而不是别的"的论证。这是区分好文档和平庸文档的关键章节。

- 解释关键决策的动机。
- **主动列出被放弃的备选方案 + 放弃原因**（"我们没选 X，因为 Y"）。这比单方面论证你选的方案更可信，也避免后人重复讨论。
- 回应可预见的质疑。

## Compatibility / 兼容性

凡涉及破坏性变更，必须正面回应。
- 是不是破坏性变更？**开门见山承认**。
- 代价是什么（性能、行为变化、迁移成本）？**诚实列出**，不藏着。
- 渐进迁移路径（按模块/按文件 opt-in、灰度、特性开关）。
- 有先例佐证更好（"某系统做过类似变更，结果平淡无奇"）。

## Implementation / Transition / 实现与过渡

- 如何落地、分几步、配套什么工具。
- **用数据和工具支撑"可落地"**：实测失败率、灰度结果、自动化迁移工具，比任何"我们认为风险可控"都管用。
- 兼容老版本的过渡方案（如独立发布的兼容库）。

## Appendix / 附录（可选）

把会打断主线的细节后置：完整 API、端到端示例、FAQ。
FAQ 专门回应高频质疑（"为什么叫这个名字""为什么不用某语言的做法""和 X 有何不同"）。

Writing Style (following the writing style of Go documentation)

Structure is the skeleton; style is the muscle. Enforce these — they're what make the doc readable.

Voice / Subject

  • Use "we / We" for decisions — present the design as a choice a group of people can be responsible for, not as objective truth. ("We propose…", "We decided to remove…")
  • Use the code itself as the subject for behavior — "this code has a bug" / "this code will…", keeping attention on the program.
  • Use "you / you" when reasoning with the reader — like explaining face to face.
  • Prohibit subjectless passive voice — do not write evasive constructions like "it is suggested that…" or "It is suggested that…".

Sentences / Sentences

  • Use short sentences for judgments and long sentences for arguments. First use an extremely short sentence to make the call ("This code has a bug."), then use information-dense long sentences to lay out the mechanism.
  • Alternate long and short to create rhythm. Do not use long, convoluted sentences throughout.

Paragraphs / Paragraphs

  • One paragraph covers only one thing, with the point at the start of the paragraph(conclusion first).
  • Write subheadings as a complete argument, not as noun phrases.
    • Write 老代码不受影响，编译结果与之前完全一致, not 兼容性。
    • Readers can read the entire chain of argument just from the headings.

Tone / Tone

  • Restrained honesty, even self-deprecation. Acknowledging the cost and admitting that you have stepped in pitfalls yourself is more persuasive than adjectives.
  • Use emphasis sparingly. Bold/italicize only once in the most critical place in the whole document; that makes it stand out most.

Step 5: Review & Iteration

Present the doc and steer feedback to the sections that matter most:

设计文档已生成。重点请看这几处：

- Rationale：被放弃的方案和理由是否站得住？有没有遗漏的备选项？
- Compatibility：破坏性和代价是否如实说清？迁移路径可行吗？
- Background：痛点是否用具体例子讲清，而不是形容词？
- 文风：标题是否是"结论"而非名词？有没有无主语的被动腔？

回复 OK 保存，或给出修改意见。

Step 6: Save

设计文档保存到哪里？

A. tasks/design-[feature-name].md（紧挨 PRD，推荐）
B. docs/design/[feature-name].md
C. 自定义路径：[指定]

Mapping: PRD → Design Doc

PRD section Design Doc section Transformation method
Problem / Background Background Find the real pain-point code/scenario and quantify it
Goals / Goals Abstract + Background Distill into the "most important promise" and embed it in the summary
User Stories / Requirements Design Convert into progressive design examples
Technical Considerations Design + Rationale Constraints → design decisions + trade-off arguments
Non-Goals Rationale Write as "we did not do X because Y"
Risks / Risks Compatibility + Implementation Risks → compatibility costs + migration/rollout plan
Implicit alternatives Rationale Explicitly list them and explain why they were not chosen

Quality Criteria

A good design doc should pass these checks:

  • The title is a "what to do" conclusion, not a noun phrase, and includes a discussion link
  • The summary embeds the most important promise/constraint
  • Background usesconcrete examples or real codeto discuss pain points, not adjectives
  • Design follows "declaration + example + boundaries" and includes progressive teaching
  • Rationale proactively lists at least one abandoned option and the reason(the most critical checklist item)
  • For any breaking change, Compatibility directly acknowledges it and lists the costs
  • Implementation uses data/tools to support "feasible," rather than shouting "risks are controllable" in the abstract
  • Style: use "we" for decisions, code for behavior, no subjectless passive voice; alternate long and short sentences; headings are thesis statements
  • No "TBD / TODO"—either resolve it or move it into Open Questions

Edge Cases & Fallback

Scenario Handling
PRD is vague and incomplete Ask more in Step 3, write missing items into Open Questions / Assumptions
No real pain-point code to cite Substitute a minimal credible example code, and note that it is constructed
No alternatives to write about Force yourself to think "what is the most naive approach, and why is it not enough"—there is always a rejected baseline
Not a breaking change Compatibility: explain in one sentence that it is "purely additive, non-breaking"; no need to force it
The proposal is ultimately rejected Still write it well—recording "why this path does not work" is itself a high-value artifact; mark the Status as Rejected
The feature is too large Split it into multiple design docs (by boundary), and link them to each other
The user only wants the implementation contract Suggest switching to /prd-to-spec, or first to-design and then prd-to-spec

Anti-Patterns to Avoid

  • Do not only argue for the option you chose. If you do not write the abandoned alternatives, the document loses half its value.
  • Do not describe pain points with adjectives. "The current state is terrible" is not persuasive; a real piece of buggy code is.
  • Do not hide the costs. Slower performance, behavior changes, migration costs—state them all clearly, then give the migration path.
  • Do not write headings as nouns. "Compatibility" → "Old code is unaffected, and the compilation result is completely identical".
  • Do not use the subjectless passive voice. Decisions need someone accountable; use "we" as the subject.
  • Do not write it as a SPEC. A design document discusses "why this choice" and "trade-offs", not a field-level implementation contract.
  • Do not be perfunctory just because the proposal may be rejected. Document quality is unrelated to whether the proposal is approved.

Relationship to Other Skills

/prd  →  /to-design  →  /prd-to-spec  →  /goal  →  /review-it  →  /ship-it
 │            │               │              │
 │ 需求(what) │ 决策与取舍     │ 实现契约(how) │ 编码
 │            │ (why/which)   │
  • /prd Produce the PRD (input to this skill)
  • /to-design Produce the design document: argue the approach, expose trade-offs, align understanding (this skill)
  • /prd-to-spec Produce an implementation-level SPEC: fields, interfaces, schema contracts
  • /code-to-spec Reverse-engineer a SPEC from existing code (complementary: forward vs reverse)

The ultimate purpose of writing a design document is not "to persuade others to agree with you", but "to let everyone make decisions on the same basis of facts and trade-offs".