google-design-docs

以完全透明的方式，为调查性新闻分析预处理后的数据。当记者已经准备好经过清洗与预处理的数据，等待进一步分析，并需从中挖掘出支持报道的规律、异常、关联性或统计发现时，可使用此技能。触发点包括分析数据、寻找规律、识别离群值、交叉核对记录、计算统计指标，或回答具体的调查性问题。此技能与“结构化数据预处理”技能相辅相成，更注重简单易懂的分析方法，而非复杂的算法——每项发现都必须能够向编辑清晰解释，并经得起严格的质询与检验。

SKILL.md

--- frontmatter

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

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

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

Google Design Docs

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

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

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

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

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

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

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

作成ワークフロー

Phase 1: 作成と反復

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

Phase 2: レビュー

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

Phase 3: 実装

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

Phase 4: 保守と学習

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

ドキュメント構成

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

必須セクション

セクション	内容
Context and Scope	客観的背景情報（簡潔に）
Goals and Non-Goals	達成目標と意図的に除外する領域
The Actual Design	概要から詳細へ段階的に展開
Alternatives Considered	各選択肢のトレードオフ分析
Cross-cutting Concerns	セキュリティ・プライバシー・可視性

推奨要素

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

ベストプラクティス

推奨:

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

避けるべきパターン:

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

文書の長さの目安

プロジェクト規模	推奨ページ数
小規模変更	1-3ページ
中規模機能	5-10ページ
大規模システム	10-20ページ

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

Resources

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