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.

设计哲学源自对 5 篇 Go 官方 proposal（泛型 / 错误包装 / loopvar / slog / try）的分析。核心信念：文档的价值不取决于方案是否通过，而取决于它是否让讨论建立在同一套事实和取舍之上。

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 is derived from the 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 enables discussions to be grounded in the same set of facts and tradeoffs.

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

).

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

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

Locate input — find or receive the PRD (or idea)
Analyze context (optional) — scan the codebase for existing patterns, constraints, and prior art
Surface the decisions — identify the real design forks and ask clarifying questions (max 3-5)
Generate the design doc — following the structure and writing style below
Review — present for feedback, especially on the Rationale and Compatibility sections
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.

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.

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.

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

markdown

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

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

markdown

Title: <A one-sentence statement of "what to do" — the title is a conclusion, not a noun phrase>
Author(s): <Author(s)>
Last updated: <YYYY-MM-DD>
Discussion at <issue / PR / document link>   # Keep the document connected, always attach an entry for discussions
Status: Draft | Under review | Accepted | Rejected

Abstract / 摘要

Abstract / Abstract

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

A single paragraph summarizing the entire document: what to do, how to do it roughly, and the most critical promise (e.g., "backward compatibility", "no new dependencies"). Readers should grasp the full picture after this paragraph. Embed implicit core constraints here.

Background / 背景与动机

Background / Background & Motivation

用具体、可感的例子说明"痛在哪"，而不是抽象地说"现状不好"。

能贴一段真实的 bug 代码 / 别扭的调用，就贴。先让读者"疼"起来。
量化痛点（出现频率、踩坑次数、损失），不要用形容词堆砌。
一句话给问题定性。

Use specific, tangible examples to explain "where the pain lies" instead of abstractly stating "the current state is bad".

Paste a snippet of real buggy code / awkward usage if possible. First make readers "feel the pain".
Quantify pain points (frequency of occurrence, number of pitfalls, losses) instead of using vague adjectives.
Qualify the problem in one sentence.

Design / Proposal / 设计

Design / Proposal / Design

文档主体。遵循三条：

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

The main body of the document. Follow three rules:

Progressive teaching from simple to complex: Start with the smallest example, leave complex scenarios until readers have an intuition.
Triad of declaration + example + boundary: For each API/interface, first provide the declaration, then a usage snippet, then clarify the applicable boundaries.
Before vs after transformation comparison: Display side-by-side to show benefits whenever possible. Never use a paragraph of text when a runnable code snippet can explain it clearly.

Rationale / 理由与取舍

Rationale / Rationale & Tradeoffs

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

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

Rationale = The argument for "why this solution, not others". This is the key section that distinguishes good documents from mediocre ones.

Explain the motivation behind key decisions.
Proactively list rejected alternatives + reasons for rejection ("We did not choose X because Y"). This is more credible than unilaterally justifying your chosen solution, and prevents repeated discussions by future teams.
Address foreseeable objections.

Compatibility / 兼容性

Compatibility / Compatibility

凡涉及破坏性变更，必须正面回应。

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

For any breaking changes, you must respond directly.

Is this a breaking change? State it clearly upfront.
What are the costs (performance, behavior changes, migration costs)? List them honestly, no hiding.
Gradual migration paths (opt-in by module/file, canary releases, feature flags).
It's better to have precedents ("A similar change was made in a certain system with unremarkable results").

Implementation / Transition / 实现与过渡

Implementation / Transition / Implementation & Transition

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

How to implement it, in what steps, and supporting tools.
Use data and tools to support "feasibility": Measured failure rates, canary release results, automated migration tools are more convincing than any "we believe risks are controllable".
Transition plans to maintain compatibility with old versions (e.g., independently released compatibility libraries).

Appendix / 附录（可选）

Appendix / Appendix (Optional)

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

---

Move details that would interrupt the main narrative to the end: complete APIs, end-to-end examples, FAQs. FAQs specifically address high-frequency questions ("Why this name?", "Why not use the approach of a certain language?", "How is this different from X?").

---

Writing Style (照搬 Go 文档的文风)

Writing Style (Adhere strictly to Go documentation style)

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

Voice / 主语

Voice / Subject

决策用 "我们 / We" — 把设计说成一群人可负责的选择，不是客观真理。("We propose…", "我们决定移除…")
行为用代码本身当主语 — "this code has a bug" / "这段代码会…"，让注意力落在程序上。
说理对读者用 "你 / you" — 像面对面解释。
禁止无主语的被动腔 — 不写"据建议应当…""It is suggested that…"这类推卸责任的句式。

Use "We" for decisions — Frame the design as a choice that a group takes responsibility for, not an objective truth. ("We propose…", "We decided to remove…")
Use the code itself as the subject for actions — "this code has a bug" / "this code will…" to focus attention on the program.
Use "you" when explaining to readers — As if explaining face-to-face.
Avoid subject-less passive voice — Do not use evasive phrases like "It is suggested that…" or "According to suggestions, we should…".

Sentences / 句子

Sentences / Sentences

判断用短句，论证用长句。先用一个极短的句子拍板（"这段代码有 bug。"），再用信息密集的长句铺开机制。
长短交替制造节奏。不要通篇绕来绕去的长句。

Use short sentences for judgments, long sentences for arguments. First make a decision with an extremely short sentence ("This code has a bug."), then elaborate on the mechanism with information-dense long sentences.
Alternate between short and long sentences to create rhythm. Avoid using meandering long sentences throughout.

Paragraphs / 段落

Paragraphs / Paragraphs

一段只讲一件事，观点放段首（结论先行）。
小标题写成一句完整的论点，而不是名词短语。
- 写
```
老代码不受影响，编译结果与之前完全一致
```
  ，而不是
```
兼容性
```
  。
- 读者光看标题就能读完整条论证链。

Each paragraph focuses on one thing, with the point at the beginning (conclusion first).
Write subheadings as complete argumentative sentences, not noun phrases.
- Write
```
Legacy code is unaffected, compilation results are identical to before
```
  instead of
```
Compatibility
```
  .
- Readers can follow the entire argument chain just by reading the headings.

Tone / 语气

Tone / Tone

克制的诚实，甚至自嘲。承认代价、承认自己也踩过坑，比形容词更有说服力。
强调要省着用。全文只在最关键处加粗/斜体一次，反而最醒目。

Restrained honesty, even self-deprecation. Acknowledging costs and admitting you've made mistakes is more persuasive than adjectives.
Use emphasis sparingly. Bold/italicize only once at the most critical point in the entire document to make it stand out.

Step 5: Review & Iteration

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

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

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

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

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

The design document has been generated. Please focus on these sections:

- Rationale: Are the rejected alternatives and their reasons valid? Are there any missing alternatives?
- Compatibility: Are the breaking changes and costs stated honestly? Is the migration path feasible?
- Background: Are pain points explained with specific examples instead of adjectives?
- Writing style: Are the titles conclusions rather than noun phrases? Is there any subject-less passive voice?

Reply "OK" to save, or provide revision suggestions.

Step 6: Save

设计文档保存到哪里？

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

Where to save the design document?

A. tasks/design-[feature-name].md (Next to the PRD, recommended)
B. docs/design/[feature-name].md
C. Custom path: [Specify]

Mapping: PRD → Design Doc

PRD 部分	Design Doc 部分	转化方式
Problem / 背景	Background	找到真实的痛点代码/场景，量化它
Goals / 目标	Abstract + Background	提炼成"最重要的承诺"埋进摘要
User Stories / 需求	Design	转成渐进式的设计示例
Technical Considerations	Design + Rationale	约束 → 设计决策 + 取舍论证
Non-Goals	Rationale	写成"我们没做 X，因为 Y"
Risks / 风险	Compatibility + Implementation	风险 → 兼容性代价 + 迁移/灰度方案
隐含的备选方案	Rationale	显式列出并解释为何不选

PRD Section	Design Doc Section	Transformation Method
Problem / Background	Background	Find real pain point code/scenarios and quantify them
Goals / Objectives	Abstract + Background	Refine into the "most critical promise" and embed it in the abstract
User Stories / Requirements	Design	Convert into progressive design examples
Technical Considerations	Design + Rationale	Constraints → Design decisions + tradeoff arguments
Non-Goals	Rationale	Write as "We did not do X because Y"
Risks / Risks	Compatibility + Implementation	Risks → Compatibility costs + migration/canary release plans
Implicit Alternatives	Rationale	Explicitly list and explain why they were rejected

Quality Criteria

A good design doc should pass these checks:

标题是一句"做什么"的结论，不是名词短语，且附了讨论链接
摘要里埋了最重要的承诺/约束
Background 用了具体例子或真实代码讲痛点，而非形容词
Design 遵循"声明 + 示例 + 边界"，并有渐进式教学
Rationale 主动列出了至少一个被放弃的方案及原因（最关键的检查项）
凡破坏性变更，Compatibility 都正面承认并列出代价
Implementation 用数据/工具支撑"可落地"，而非空喊"风险可控"
文风：决策用"我们"、行为用代码、无无主语被动腔；长短句交替；小标题是论点句
没有 "TBD / TODO"——要么解决，要么挪进 Open Questions

A good design doc should pass these checks:

The title is a one-sentence conclusion of "what to do", not a noun phrase, and includes a discussion link
The most critical promise/constraint is embedded in the abstract
Background uses specific examples or real code to explain pain points, not adjectives
Design follows the "declaration + example + boundary" rule and uses progressive teaching
Rationale proactively lists at least one rejected alternative and its reason (the most critical check item)
For any breaking changes, Compatibility clearly acknowledges them and lists the costs
Implementation uses data/tools to support "feasibility" instead of empty claims like "risks are controllable"
Writing style: Uses "We" for decisions, code as the subject for actions, no subject-less passive voice; alternates between short and long sentences; subheadings are argumentative sentences
No "TBD / TODO" items — either resolve them or move them to Open Questions

Edge Cases & Fallback

场景	处理
PRD 含糊不全	在 Step 3 多问，把缺失项写进 Open Questions / 假设
没有真实痛点代码可引	用最小可信的示例代码代替，并注明是构造的
没有备选方案可写	强迫思考"最朴素的做法是什么、为什么不够"——总有一个被否决的基线
不是破坏性变更	Compatibility 一句话说明"纯增量、无破坏"，不必硬凑
方案最终被否决	照样写好——记录"这条路为什么走不通"本身就是高价值产物，Status 标 Rejected
特性太大	拆成多篇 design doc（按边界），互相链接
用户只要实现契约	提示改用 `/prd-to-spec` ，或先 to-design 再 prd-to-spec

Scenario	Handling
Vague or incomplete PRD	Ask more questions in Step 3, and record missing items in Open Questions / Assumptions
No real pain point code to reference	Replace with the smallest credible sample code and note that it is constructed
No alternatives to write	Force yourself to think "What is the most naive approach and why is it insufficient?" — there is always a rejected baseline
Non-breaking change	Compatibility section can simply state "Purely additive, no breaking changes" without unnecessary elaboration
Proposal is ultimately rejected	Still write the document well — recording "why this path didn't work" is a high-value product in itself; mark Status as Rejected
Feature is too large	Split into multiple design docs (by boundaries) and link them to each other
User only needs implementation contract	Prompt to use `/prd-to-spec` instead, or run `to-design` first then `prd-to-spec`

Anti-Patterns to Avoid

别只论证你选的方案。 不写被放弃的备选项，文档就少了一半价值。
别用形容词讲痛点。 "现状很糟"没有说服力；一段真实的 bug 代码才有。
别藏代价。 性能变慢、行为变化、迁移成本——都明说，再给迁移路径。
别把标题写成名词。 "兼容性" → "老代码不受影响，编译结果完全一致"。
别用无主语的被动腔。 决策要有人负责，主语用"我们"。
别写成 SPEC。 设计文档讲"为什么这么选"和"取舍"，不是字段级的实现契约。
别因为方案可能被否就敷衍。 文档质量与提案是否通过无关。

Don't only justify your chosen solution. Without listing rejected alternatives, the document loses half its value.
Don't use adjectives to explain pain points. "The current state is bad" is not persuasive; a snippet of real buggy code is.
Don't hide costs. Performance degradation, behavior changes, migration costs — state them clearly and provide a migration path.
Don't write titles as nouns. "Compatibility" → "Legacy code is unaffected, compilation results are identical to before".
Don't use subject-less passive voice. Decisions need accountability; use "We" as the subject.
Don't write it as a SPEC. A design document focuses on "why this choice was made" and "tradeoffs", not a field-level implementation contract.
Don't cut corners just because the proposal might be rejected. The quality of the document is independent of whether the proposal is accepted.

Relationship to Other Skills

/prd  →  /to-design  →  /prd-to-spec  →  /goal  →  /review-it  →  /ship-it
 │            │               │              │
 │ 需求(what) │ 决策与取舍     │ 实现契约(how) │ 编码
 │            │ (why/which)   │

/prd 产出 PRD（本 skill 的输入）
/to-design 产出设计文档：论证方案、暴露取舍、对齐认知（本 skill）
/prd-to-spec 产出实现级 SPEC：字段、接口、schema 契约
/code-to-spec 从既有代码逆向出 SPEC（互补：正向 vs 逆向）

写设计文档的终极目的不是"说服别人同意你"，而是"让所有人在同一个事实和取舍基础上做决定"。

/prd  →  /to-design  →  /prd-to-spec  →  /goal  →  /review-it  →  /ship-it
 │            │               │              │
 │ Requirements(what) │ Decisions & Tradeoffs │ Implementation Contract(how) │ Coding
 │            │ (why/which)   │

/prd Generates PRD (input for this skill)
/to-design Generates design document: argues for the solution, exposes tradeoffs, aligns team understanding (this skill)
/prd-to-spec Generates implementation-level SPEC: field, interface, schema contracts
/code-to-spec Reverses existing code into SPEC (complementary: forward vs reverse)

The ultimate goal of writing a design document is not "to convince others to agree with you", but "to enable everyone to make decisions based on the same set of facts and tradeoffs."

to-design

Original

Translation

to-design — PRD to Design Document

to-design — PRD to Design Document

When to Use

When to Use

The Job

The Job

Step 1: Locate Input

Step 1: Locate Input

Step 2: Analyze Context (Optional)

Step 2: Analyze Context (Optional)

Step 3: Surface the Decisions

Step 3: Surface the Decisions

Step 4: Design Document Structure

Step 4: Design Document Structure

Abstract / 摘要

Abstract / Abstract

Background / 背景与动机

Background / Background & Motivation

Design / Proposal / 设计

Design / Proposal / Design

Rationale / 理由与取舍

Rationale / Rationale & Tradeoffs

Compatibility / 兼容性

Compatibility / Compatibility

Implementation / Transition / 实现与过渡

Implementation / Transition / Implementation & Transition

Appendix / 附录（可选）

Appendix / Appendix (Optional)

Writing Style (照搬 Go 文档的文风)

Writing Style (Adhere strictly to Go documentation style)

Voice / 主语

Voice / Subject

Sentences / 句子

Sentences / Sentences

Paragraphs / 段落

Paragraphs / Paragraphs

Tone / 语气

Tone / Tone

Step 5: Review & Iteration

Step 5: Review & Iteration

Step 6: Save

Step 6: Save

Mapping: PRD → Design Doc

Mapping: PRD → Design Doc

Quality Criteria

Quality Criteria

Edge Cases & Fallback

Edge Cases & Fallback

Anti-Patterns to Avoid

Anti-Patterns to Avoid

Relationship to Other Skills

Relationship to Other Skills