# To Design

> Generate a design document (design proposal) from a PRD, in the style of Go's official design proposals — Abstract / Background / Design / Rationale / Compatibility / Implementation, heavy on the 'why' and tradeoffs. Triggers on: to-design, prd-to-design, prd转设计文档, 生成设计文档, 写设计文档, design doc, design proposal, 设计提案, 技术设计文档.

- Skill: `smallnest/to-design` (Agent Skill)
- Install (CLI): `npx skillmds add smallnest/to-design`
- Raw SKILL.md: https://api.skillmd.com/api/skills/smallnest/to-design/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: smallnest (https://skillmd.com/u/smallnest)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/smallnest/to-design

---


# 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）的分析。核心信念：**文档的价值不取决于方案是否通过，而取决于它是否让讨论建立在同一套事实和取舍之上。**

---

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

```markdown
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 (照搬 Go 文档的文风)

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

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

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

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

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

---

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

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