to-design

to-design — 从 PRD 到设计文档

将 PRD（或粗略想法）转化为一份设计文档，文风仿照 Go 官方设计提案：语言平实、示例具体，最重要的是，坦诚说明为什么选择这种方案，而不是其他方案。

这与 prd-to-spec 并不相同。SPEC 是供工程师据以实现的实现契约（表格、端点、架构）。设计文档则是决策产物：它为某种方案提供论据，揭示权衡，并让团队在编写代码之前就能基于相同事实达成共识。当问题是“我们应该如何构建，以及为什么”时，产出设计文档；当问题是“给我精确的实现契约”时，产出 SPEC。

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

---

适用场景

• 已有 PRD，需要在开始实现前决定如何构建
• 方案存在实际权衡，希望将其记录下来并展开讨论
• 变更风险高、会造成破坏或难以撤销（设计文档能让团队尽早讨论兼容性）
• 多人需要在工作展开之前就某个方向达成一致
• 希望持久记录“为什么选择 X、拒绝 Y”——即使提案后来被否决

如果团队只需要用于编码的具体契约，请改用 /prd-to-spec（也可以先运行 to-design，再运行 prd-to-spec）。

---

工作内容

1. 定位输入 — 查找或接收 PRD（或想法）
2. 分析上下文（可选） — 扫描代码库，了解现有模式、约束和先例
3. 揭示决策点 — 找出真正的设计分歧，并提出澄清问题（最多 3-5 个）
4. 生成设计文档 — 遵循下文的结构和写作风格
5. 评审 — 提交反馈，尤其关注 Rationale 和 Compatibility 部分
6. 保存 — 写入商定的位置

---

第 1 步：定位输入

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

设计文档可以从尚未成形的想法开始，不必只有完善的 PRD。如果输入信息不足，请更多依靠第 3 步。

---

第 2 步：分析上下文（可选）

从零开始的项目可以跳过此步。其他情况请先扫描代码库，让设计立足现实：

• 现有模式：设计应遵循的模式（命名、错误处理、模块边界）
• 先例 — 此处以前是否尝试过或否决过类似方案？
• 约束 — 兼容性承诺、公共 API，以及设计不能破坏的数据
• 实际痛点 — 找出设计要修复的真实缺陷或不便之处，让 Background 能引用对应代码

最有说服力的 Background 部分会引用用户自己代码库中的真实代码，而不是假设性的示例。

---

第 3 步：揭示决策点

设计文档的成败取决于 Rationale。动笔之前，先找出真正的分岔点——也就是有经验的工程师可能会合理地选择不同做法的地方——并确定如何取舍。

只询问真正存在分歧的问题：

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)

对于每个分岔点，也要记录你没有选择的方案——这将成为 Rationale 的内容。

---

第 4 步：设计文档结构

这是根据 5 篇 Go 提案提炼出的标准框架。保留章节名称；确实不适用的章节可以删去（如果删去的章节值得说明，则交代原因）。

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 有何不同"）。

---

写作风格（照搬 Go 文档的文风）

结构是骨架，风格是肌肉。请遵循以下要求——它们决定了文档是否易读。

语气 / 主语

• 决策用“我们 / We” — 将设计表述为一群人可以负责的选择，而非客观真理。（“We propose…”，“我们决定移除…”）
• 行为以代码本身为主语 — “this code has a bug” / “这段代码会…”，让注意力落在程序上。
• 说理时称呼读者为“你 / you” — 像面对面解释一样。
• 禁止使用没有主语的被动语态 — 不写“据建议应当…”“It is suggested that…”这类推卸责任的句式。

句子 / 句式

• 判断用短句，论证用长句。先用极短的句子表明结论（“这段代码有 bug。”），再用信息密集的长句展开说明机制。
• 长短句交替，形成节奏。不要通篇使用迂回冗长的句子。

段落

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

语气

• 保持克制、坦诚，甚至可以自嘲。承认代价、承认自己也踩过坑，比堆砌形容词更有说服力。
• 谨慎使用强调。全文只在最关键处加粗或斜体一次，反而最醒目。

---

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

---

Quality Criteria

A good design doc should pass these checks:

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

---

Edge Cases & Fallback

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

---

Anti-Patterns to Avoid

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

---

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 逆向）

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