---

name: google-design-docs description: | Googleスタイルのデザインドキュメント（設計書）作成ガイド。コーディング前にソフトウェアの実装戦略と重要な設計判断を記録するための非公式文書を作成する。

使用タイミング: (1) 新機能やシステムの実装前に設計を明文化したい時 (2) 適切な設計について不確実性がある時 (3) シニアエンジニアのレビューが有益な時 (4) 設計が曖昧または議論の余地がある時 (5) セキュリティ・プライバシーの検討が必要な時 (6) レガシーシステムの高レベルドキュメントが必要な時

トリガーフレーズ: 「設計書」「デザインドキュメント」「design doc」「実装前の設計」「アーキテクチャ文書」

Google Design Docs

ソフトウェアエンジニアの仕事はコード作成ではなく問題解決である。デザインドキュメントは変更が安価な段階で設計問題を発見し、組織全体でコンセンサスを得るための手段。

デザインドキュメントを書くべきか判断する

以下の3項目以上に該当する場合は作成を推奨:

• 適切な設計について不確実性がある
• シニアエンジニアの関与が有益
• 設計が曖昧または議論の余地がある
• セキュリティ・プライバシーの見落としリスクがある
• 将来のエンジニアのための高レベルドキュメントが必要

書かない場合: 実装が明白で「これが唯一の手段」と言える場合

デザインドキュメントの6つの機能

1. 早期発見: 変更が安価な段階での設計問題の発見
2. コンセンサス: 組織全体での合意形成
3. 横断的懸念: セキュリティ・プライバシーの検討確保
4. 知見の共有: シニアエンジニアの知見のスケーリング
5. 組織記憶: 設計判断の記録と将来の参照
6. ポートフォリオ: 技術力の証明

作成ワークフロー

Phase 1: 作成と反復

1. チーム内の協力者と共同で文書作成
2. コメント機能で明確化と改善を反復
3. 草稿段階で頻繁にフィードバックを求める

Phase 2: レビュー

• 軽量版: メーリングリスト/Slackでの配布
• 重量版: 正式な設計レビュー会議

Phase 3: 実装

• 現実との衝突で設計変更が必要になる
• 未リリースシステムは特にドキュメント更新を推奨

Phase 4: 保守と学習

• 新規エンジニアの最初の質問は「デザインドキュメントはどこか」
• 1-2年後の再読で成功と失敗から学習

ドキュメント構成

テンプレートと詳細例は references/template.md を参照。

必須セクション

推奨要素

• システムコンテキスト図
• API設計の概要（スキーマ全文コピーは避ける）
• データストレージ戦略
• 必要に応じてプロトタイプコード

ベストプラクティス

推奨:

• トレードオフ分析に焦点を当てる
• 図やダイアグラムで問題を視覚化
• プロトタイピングを設計プロセスに組み込む

避けるべきパターン:

• 「実装マニュアル」化（トレードオフなしの手順書）
• 過度な長さ（目安は10-20ページ、短い文書なら1-3ページ）
• 急速反復プロジェクトでの不必要な使用
• フォーマルなスキーマ定義の丸写し

文書の長さの目安

20ページを超える場合は分割を検討。

Resources

• references/template.md: デザインドキュメントのテンプレートとサンプル