writing-design-docs

設計ドキュメントの書き方

必須の前提知識: technical-writing スキル（まず読むこと、厳格なルール、真実に関するルール、スタイル）。

概要

設計ドキュメントとは、議論可能な形にされた提案です。結論を先に示し、自明でない選択のすべてを「Why & What」ボックスにまとめ、コストを便益の隣に明記し、事実と提案を区別します。

いつ呼び出すべきか、そうでないか

変更を主張したり設計を記録したりするもの、すなわち提案書、RFC、設計ドキュメント、仕様書、移行計画、「〜すべきか」を扱う文書には呼び出します。すでに下された決定を記録する場合（recording-decisions）、手順を書く場合（writing-runbooks）、ステータスレポートには呼び出しません。

プレッシャーがかかった状況でも、提案はその数値と明示されたコストによって説得し、文体に関するルールは締め切りが何であれ守られます（technical-writing のルールであり、「パンチの効いた表現」はそれを上書きしません）。出典のない事実が提供された場合は、**[source wanted: ...]** とマークして書き続けます（technical-writing スキルの references/truth.md を参照してください）。引用をでっち上げてはいけませんし、その事実を黙って落としてもいけません。

骨子

# Title: what the document does

**Subtitle pinning the scope in one sentence**

|                |                                            |
| -------------- | ------------------------------------------ |
| **Status**     | Draft / Request for comments               |
| **Owner**      | [team or role]                             |
| **Scope**      | [explicit, including what falls outside]   |
| **Related**    | [links to sibling documents]               |
| **Audience**   | [who must read this]                       |

---

## 1. Summary
[The conclusion immediately. Not the occasion, not the method.]

## 2. [Context / what was analyzed]
## 3. [The analysis, split per question]
## n. Open questions
## n+1. Benefits and costs
[Both. Benefits alone reads as a sales pitch.]
## n+2. Residual risks and what not to do
[Only when the design hands work to other teams.]

---

*Closing line: which parts are fact and which are proposal, and where input is wanted.*

構成のルール

• 章に番号を振り、ch. 7.1 のように引用します。
• 目標と非目標の両方。 非目標（または「明示的に変更しない」）セクションでは、変更されないままの内容を述べます。
• 用語が曖昧な場合は振る舞いの前に定義。 「responded」「eligible」「stale」を使う前に確定させます。
• 根拠セクションでは、設計が依拠する事実を確定します。事実と出典の表を、特定のコミットに対して検証します。検証済みの事実と、これから構築するものを区別します。
• 付録にはアルファベット（付録 A、B）を付け、本文を埋もれさせてしまうものを収めます。設定例、用語集、一覧などです。
• 事実は一か所にのみ置きます。 リンクを張り、繰り返してはいけません。同じリポジトリ内のドキュメント間であっても同様です。
• 未完成の部分は省略するのではなく **[DRAFT - input wanted]** でマークします。
• 未解決の問いには担当者を付けます。名前、役割、または明示的な「〜が記入予定」です。
• **残存リスクと「やってはいけないこと」**は、設計が他者に作業を引き渡す場合にドキュメントを締めくくります。
• 行数の予算はありませんが、繰り返しや強調による冗長な長さは削ります。およそ 800 行を超えたら分割し、本体のドキュメントから各部分へリンクさせます。

Why & What ボックス

自明でない選択のすべてにこれを付けます。読者は結論ではなく、このボックスに反応するのです。

> **Why & What - [the choice in four words]**
>
> **What:** [the choice, one sentence, no justification]
>
> **Why:** [the reasoning. Also name what the choice does NOT solve.]
>
> **Alternatives considered:**
> - *[Alternative]:* [its strongest argument, and why it still lost]
>
> **Fallback:** [what survives if this does not work]

• 最も強い反論を示さずに退けられた代替案は、ストローマンです。その反論を明記してください。
• その選択が解決しないことを認めると、ドキュメントの信頼性が増します。
• 誰も異議を唱えないような選択にボックスは不要です。それはノイズです。
• ドキュメントの他のどこにも現れない代替案は、ボックスに属しません。読者はそれを検討しようとしないからです。そのような却下が 1 つなら正当化できますが、短いものが何個も続くなら、ボックスは水増しされています。

トーン

• ドキュメントは提案であり続けます。「私たちは提案します」「それが説得力を持つかどうかはあなた次第です」であって、「これが働き方になります」ではありません。方向性を定め、詳細な選択は開かれたままにします。
• 何がコストになるのかを明記します。便益の章はその代償で締めくくります。何が難しくなるのか、何を人々が学び直さねばならないのか、どの自由が失われるのか。
• 最上級表現や約束めいた言葉遣いは使いません。具体的な数値と検証可能な記述を用います。
• 期待される結果がネガティブであることもあります。その場合は最初にそう述べます。「期待される結果は、現在のキューが提案された書き直しに勝つことです。それは有用な結果です。」

完全性チェック

仕様や計画をレビュアーや実行者に渡す前に、5 つの曖昧さの欠陥を確認してください。

1. 未解決のプレースホルダー: 文字通りの TBD、TODO、「後で記入」、または明らかに不完全な文 (明示された **[DRAFT - input wanted]** ブロックは意図的なものです。マークのない欠落は欠陥です)。
2. 受け入れ基準の欠如: 具体的で独立して検証可能な成功条件がない要件。
3. 未定義の参照: 言及されているものの、どこにも定義されていない型、エンドポイント、コンポーネント、またはテーブル。
4. 検証可能な出力がない: レビュアーが検査できるものを何も生み出さないタスク (ファイルパスも、コマンドも、観察可能な動作もない)。
5. 方法のない内容: 実装可能な方向性のない成果 («適切にエラーを処理する» で、適切の定義がない)。

実行計画の場合は、タスクごとに次を追加してください: 目標、正確なファイル、示された変更、具体的なシナリオを含むテスト、および検証コマンド。混乱を招く残存物 (奇妙なディレクトリ名、レガシーエイリアス) は、不可解なままにせず説明してください。