writing-technical-design-docs

技術設計ドキュメントの作成

• 設計ドキュメントは仕様書ではなく、意思決定の記録です。
• その役割は、作業を開始できるだけの厳密さを保ちつつ、計画を変更できる余地も残して、関係者の方向性をそろえることです。
• 完璧さではなく、方向性の正しさを目指します。今共有する60％のドラフトのほうが、3週間後に共有する95％のドラフトより、よいフィードバックを得られます。
• ドキュメントの作成に、実装の最初の一部より時間がかかるなら、作り込みすぎです。

原則

• 後戻りできない決定は議論し、後戻りできる決定は既定値を選びます。 後戻りできない決定は変更が難しいものです（データモデル、公開 API、永続化形式、ID 方式など）。十分に議論してください。後戻りできる決定は変更コストが低いものです（タイムアウト、再試行回数、内部モジュールの境界、ログ形式など）。既定値を示し、変更可能であることを伝えて先に進みます。後戻りできる決定について1段落を超えて議論する場合は、その議論を削ってください。誤った決定の変更コストが分からない場合は、後戻りできないものとして扱います。
• 不明点を明示し、数字を捏造しないでください。 「QPS は不明。第1週に測定する」と書き、「約500 QPS」とは書きません。レビュアーは不明点に異議を唱えられますが、作り上げた数字はドキュメントの信頼性を損ないます。
• 方向性を決め、代替案を1つ示してください。 選んだアプローチ、検討した代替案を1つ、採用しなかった理由を1行で示します。「Postgres LISTEN/NOTIFY を使用します。Kafka も検討しましたが、現在の規模では運用が複雑になるため採用しませんでした。」のように書きます。選択肢を並べ立てないでください。別の案を好むレビュアーがいれば、提案してくれます。
• 具体的に、ただし網羅しすぎないようにします。 重要なシナリオを主要なエッジケースとともに最初から最後まで記述し、それ以外は「同じパターンに従う」または「実装時に決定」と明記します。
• 自分だけが知っていることを書き残してください。 レビュアーや後から読む人が目にするのは、ドキュメントとリンク先のファイルだけで、この会話は見られません。そのため、会話で出た要件、制約、決定は、すべてドキュメントか、ドキュメントからリンクしたファイルに記載してください。

構成

これは基本形です。チーム独自のテンプレートがある場合は、そちらに組み込んでください。

1. 最初にステータスバナーを置きます： Status: Draft v0.1 (seeking [direction | implementation | rollout] feedback). これにより、レビュアーに行単位の修正を求めているのではないと伝えられます。
2. 決定事項から書き始めます： 問題の説明の直後に、選んだアプローチを3～5文で記載します。それ以外はすべて、その正当性を説明するか、詳細を補足する内容です。
3. 詳細度を示します： 厳密な説明が必要なセクションには [deep]、意図的に概要にとどめるセクションには [sketch] を付け、レビュアーがどこを重点的に確認すべきか分かるようにします。
4. 未解決の質問： 番号付きで記載し、それぞれに担当者と回答が必要な日付を付けます。正直な未解決の質問が5つあるほうが、0個よりもよいです。担当者とは、割り当て先であり、不明な事実ではありません。担当者を個人名で指定できない場合は、担当チーム、役割、または作成者を記載し、ドキュメントの日付を基に期限を提案してください。どちらにも TBD と書いてはいけません。
5. 最後に可逆性の表を置きます： 主要な決定それぞれについて、後戻りできるか、できないかを記載します。その後にセクションを追加してはいけません。

レビュー

• このセッションは作成者です。会話を保持しているため、自分のドラフトを自ら評価することはありません。独立レビューのルールに従ってください。
• ドラフトを返す前に、Skill ツールで reviewing-design-docs を呼び出し、批判的なレビューを行ってください。
• インストールされていない場合、またはここで実行できない場合（たとえば、ドラフトをファイルに保存できない場合）は、ドキュメントの後に区切り線を置き、その下に独立レビューを実施していないこと、その理由、次の手順を記載してください。次の手順は、ドラフトをファイルに保存してから /reviewing-design-docs <path> を実行することです。
• ドラフトを返し、その後に区切り線を置いてレビュー結果を一字一句そのまま記載してください。プロンプトのみの行がある場合は、それも含めます。指摘に対応するためにドラフトを修正してはいけません。どの指摘に対応するかはユーザーが決めます。
• Skill ツールがない場合は、スキル呼び出しのルールに従ってください。

このスキルを使わない場合

• **コンプライアンス、法務、安全性が極めて重要な仕様書：**方向性ではなく、正確さが求められます。完全かつ網羅的な仕様書を作成してください。
• **外部顧客に提供する公開 API の契約：**原則として後戻りできないため、網羅性を重視してください。
• **ポストモーテムやインシデントレポート：**過去を振り返り、事実を記録するものです。
• **最終承認済みのアーキテクチャ文書：**方向性はすでに決まっています。