to-design

to-design — PRD から設計ドキュメントへ

PRD（または大まかなアイデア）を、Go の公式設計提案のスタイルで書かれた設計ドキュメントに変換します。平易な言葉、具体例、そして何よりも、なぜ別の案ではなくこのアプローチなのかを率直に説明します。

これは prd-to-spec と同じものではありません。SPEC は、エンジニアが実装するための実装契約です（表、エンドポイント、スキーマなど）。設計ドキュメントは意思決定の記録です。あるアプローチを提案し、トレードオフを明らかにして、誰かがコードを書き始める前に、チームが同じ事実に基づいて合意できるようにします。「どう作るべきか、そしてなぜか」が問われているなら設計ドキュメントを、「実装に必要な正確な契約を示してほしい」が問われているなら SPEC を作成します。

設計の哲学は、Go の公式 proposal 5 件（ジェネリクス／エラーラッピング／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：設計ドキュメントの構成

これは Go の proposal 5 件からまとめた標準的な骨子です。セクション名は維持し、本当に当てはまらないセクションは省いてください（省略が特に目立つ場合は、その理由も記載します）。

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…」のように、責任を曖昧にする表現は避けます。

文

• 判断は短文で、論証は長文で書きます。最初にごく短い文で結論を述べ（「このコードにはバグがあります。」）、続けて、仕組みを情報量の多い長文で説明します。
• 長文と短文を交互に使ってリズムを作ります。回りくどい長文ばかりにならないようにします。

段落

• 1 段落では 1 つのことだけを扱い、主張を段落の冒頭に置きます（結論を先に述べます）。
• 小見出しは名詞句ではなく、完全な主張を表す文にします。
  • 古いコードには影響せず、コンパイル結果も以前とまったく同じです と書き、互換性 とは書きません。
  • 読者は見出しだけで、論証の流れ全体を追えるようになります。

トーン

• 抑制の効いた率直さを保ち、時には自嘲も交えます。代償を認め、自分たちも失敗したことを認めるほうが、形容詞を並べるより説得力があります。
• 強調は控えめに使います。文書全体で最も重要な箇所だけに太字または斜体を一度使えば、かえってよく目立ちます。

---

ステップ 5：レビューと反復

ドキュメントを提示し、特に重要なセクションへのフィードバックを促します。

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

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

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

---

ステップ 6：保存

设计文档保存到哪里？

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

---

対応関係：PRD → 設計ドキュメント

PRD の部分	設計ドキュメントの部分	変換方法
Problem / 背景	Background	実際の課題となっているコードや状況を特定し、定量化します
Goals / 目標	Abstract + Background	最も重要な約束として抽出し、概要に織り込みます
User Stories / 要件	Design	段階的な設計例に変換します
Technical Considerations	Design + Rationale	制約 → 設計上の決定 + トレードオフの論証
Non-Goals	Rationale	「Y の理由で X は実施しません」と記述します
Risks / リスク	Compatibility + Implementation	リスク → 互換性への影響 + 移行／段階的リリースの計画
暗黙の代替案	Rationale	明示的に列挙し、採用しない理由を説明します

---

品質基準

優れた設計ドキュメントは、次のチェック項目を満たす必要があります。

• タイトルは名詞句ではなく、「何をするか」を示す結論の文であり、議論へのリンクが付いている
• 概要に最も重要な約束／制約が織り込まれている
• Background では、形容詞ではなく、具体例や実際のコードを使って課題を説明している
• Design は「宣言 + 例 + 境界」に従い、段階的に説明している
• Rationale では、少なくとも 1 つの却下した案とその理由を積極的に列挙している（最も重要なチェック項目）
• 破壊的変更がある場合、Compatibility で正面から認め、影響を列挙している
• Implementation では、漠然と「リスクは制御可能」と主張するのではなく、データ／ツールを使って実現可能性を裏付けている
• 文体：決定には「私たち」を使い、動作はコードで示し、主語のない受け身表現を避ける。長文と短文を織り交ぜ、小見出しは主張を示す文にする
• 「TBD / TODO」がない。解決するか、Open Questions に移す

---

例外ケースとフォールバック

状況	対応
PRD が曖昧、または不完全	ステップ 3 で追加の質問を行い、不足項目を Open Questions / 仮定に記載します
実際の課題を示すコードを引用できない	信頼できる最小限のサンプルコードで代用し、作成した例であることを明記します
代替案がない	「最も素朴な方法は何か、それではなぜ不十分なのか」を強制的に検討します。必ず却下されたベースライン案があります
破壊的変更ではない	Compatibility で「純粋な追加であり、破壊的変更はありません」と一言で説明し、無理に内容を付け足す必要はありません
最終的に案が却下された	それでも質の高い文書にします。「この道がなぜ行き詰まったのか」を記録すること自体が価値の高い成果であり、Status は Rejected とします
機能が大きすぎる	境界に沿って複数の設計ドキュメントに分割し、相互にリンクします
ユーザーが実装契約だけを求めている	/prd-to-spec の利用を提案するか、先に to-design を行ってから prd-to-spec に進みます

---

避けるべきアンチパターン

• 選んだ案だけを論証しないでください。 却下した代替案を書かなければ、文書の価値は半減します。
• 形容詞で課題を説明しないでください。 「現状はひどい」では説得力がありません。実際のバグを示すコードのほうが効果的です。
• 影響を隠さないでください。 パフォーマンスの低下、動作の変更、移行コストなどはすべて明記し、移行手順も示してください。
• タイトルを名詞句にしないでください。 「互換性」ではなく、「既存コードに影響せず、コンパイル結果も完全に同一です」とします。
• 主語のない受け身表現を使わないでください。 決定には責任者が必要です。主語には「私たち」を使います。
• SPEC のように書かないでください。 設計ドキュメントで説明するのは「なぜこの案を選んだのか」と「トレードオフ」であり、フィールド単位の実装契約ではありません。
• 案が却下される可能性があっても、手を抜かないでください。 文書の品質と提案が採用されるかどうかは関係ありません。

---

他のスキルとの関係

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

• /prd は PRD を作成します（本スキルへの入力）
• /to-design は設計ドキュメントを作成します。案を論証し、トレードオフを明らかにし、認識をそろえます（本スキル）
• /prd-to-spec は実装レベルの SPEC を作成します。フィールド、インターフェース、schema 契約を扱います
• /code-to-spec は既存のコードから逆方向に SPEC を作成します（相互補完：順方向と逆方向）

設計ドキュメントを書く究極の目的は、「他の人を自分に賛成させること」ではなく、「全員が同じ事実とトレードオフを踏まえて決定できるようにすること」です。