design-doc

name	design-doc
description	ソフトウェア設計ドキュメント (Design Doc) を記述する。仕様検討後に Design Doc としてまとめる、仕様を書き下す際に漏れや観点を洗い出す、ユーザーの指示に基づいて設計する、といった用途で使う。/design-doc で起動。出力は日本語。
reference	https://refactoringenglish.com/excerpts/write-an-effective-design-doc/

Design Doc

ドキュメント本文は日本語で書く。セクション見出しは英語名 (Objective, Background, ...) を主とし、必要に応じて日本語を併記する。

中心原則: 間違いの代償 (Cost of Being Wrong)

設計判断を Design Doc に書くか、未決定事項を質問するか提案で済ませるか、どのセクションを設けるか。すべて 「その判断を間違えたらどれだけ痛いか?」 で決める。

• 代償が大きい → 詳しく書き、未決定ならユーザーに質問して決める。例: 言語選定。C++ で 20 万行書いた後に Ruby on Rails が正解だったと気づいても手遅れ
• 代償が小さい → 簡潔に決め打ちし、Design Doc では議論しない。例: 一覧のページネーション (「もっと読む」か無限スクロールか)。ユーザーの反応で間違いと分かっても数時間で直せる

代償が小さい判断を AI が決め打ちで埋めたが後で見直したいものは、Open Issues に残す。

進め方

1. 対象の種類を把握する (利用者がいる機能か / 内部リファクタリングか / リスクのある領域か等)。種類によって要るセクションが変わる
2. 骨格セクションを揃え、対象に照らして該当する内容次第セクションを cost of being wrong で選ぶ
3. 仕様が薄い箇所を埋める。cost が高い未決定事項は AskUserQuestion でまとめて質問し、各選択肢に「なぜこの判断が重いか」を添える。cost が低い箇所は AI が提案して埋める
4. 書き上げたら品質基準で自己点検する

ユーザーに明確な仕様がある部分はそれに忠実に従い、勝手に変えない。仕様が薄い部分だけ AI が cost of being wrong に基づいて補う。両者は 1 つの Design Doc 内に混在してよい。

非対話のセッション (自動化や、質問に答えが返らない状況) では質問を諦め、cost が高い項目も妥当な値を仮置きして埋める。仮置きした項目は Open Issues に「要確認」として残し、何を仮定したかを明記する。

依頼が「漏れの洗い出し」なら、下記セクション群をチェックリストとして使い、欠けている観点 (特に cost が高い未決定事項) を指摘する。Design Doc 全体を書かず観点提示だけでよい。

セクションの選び方

すべての Design Doc にすべてのセクションが要るわけではない。 骨格はほぼ常に書く。内容次第セクションは cost of being wrong で取捨し、シナリオもセキュリティも対象次第で省く (内部ライブラリにユーザーシナリオは不要、外部入力のないバッチにセキュリティ節は過剰)。該当しないセクションは省く (空欄や N/A で埋めない)。

省略は基本サイレントでよい (省いたセクションを文書内で列挙しない)。例外として、読み手が「なぜ無いのか」を当然疑う主要セクション (典型は Scenarios や Security) を意図的に省くときだけ、Background か Non-Goals に一行だけ省略理由を添えてよい。省略専用の節は作らない。

---

各セクションの書き方

骨格 (ほぼ常に書く)

Title

文書冒頭の H1 として、短く・特徴的で・印象に残るプロジェクト名を置く。良い名前の条件は、声に出しやすい (short)・どのプロジェクトか分かる (distinctive)・概念を表す (evocative)。

• ✕ Project Flying Silver Horse (冗長で意味をなさない)
• ◯ RecencyBank (目的を表し、口頭で言いやすい)

固有名なので「見出しは英語名を主」ルールの対象外。

Metadata

Title 直下に key-value で置く。

- Author: 名前 (連絡先)
- Status: Draft / Design-complete, ready for implementation / ...
- Created: YYYY-MM-DD
- URL: 正式な参照先 (発行後に記入)

Objective

プロジェクトの目的を一文で。どんな立場のステークホルダーにも分かる平易な言葉で、1 ページ目に置く。

例: Trogdor Web サーバと Postgres データベースの間にキャッシュ層を追加し、アプリケーションのパフォーマンスを改善する。

Background

なぜこのプロジェクトをやるのか、何の問題を解くのか、過去に試みがあったか。判断の基準として効く文脈を書く。

書く分量の目安は 「読む前に同僚に口頭で説明するとしたら何を伝えるか」。それが 1 ページ目に載っているべき内容。

可能なら数字と観測で裏付ける。「遅い」より「レスポンスが 100ms から 600ms に悪化した」「ページロード時間の 80% が DB 参照」「参照の 95% が全体の 3% の行に集中」のように具体で書くと、後段の判断の根拠になる。

Goals

実装ではなくインパクトで書く。プロジェクトがユーザー・チーム・会社にどう利益をもたらすかを述べる。各項目は動詞始まりにする (最小化する、共有できるようにする、維持する)。

• ✕ Kubernetes をインフラに導入する (実装)
• ◯ 新バージョンのデプロイに起因する障害を最小化する (インパクト)

例:

• 家族の写真や動画を親族や親しい友人と共有できるようにする。
• 複雑さを最小化し、PC に不慣れな親族でも安心して使えるようにする。
• 全データを非公開に保ち、許可されたユーザーだけがアクセスできるようにする。

Non-Goals

スコープ外を明示し、読み手が「これも入っている」と誤解しそうな項目を否定形で打ち消す。簡潔な理由を添えてよい。

例:

• 商用の写真共有アプリは作らない。
• 過去アップロードの URL リンクは保持しない。
• 複数の家族が同一サーバを共有することは許可しない。

内容次第 (該当時のみ・設計の表現)

Scenarios

完成後のシステムが現実でどう動くかを、読み手に絵として見せる。利用者の操作や外部とのやり取りがある対象で書く。番号付きの手順が有効。

例:

1. 親が Web アプリを開く。
2. メインページで最も目を引く UI 要素 (CTA) が「アップロード」ボタンで、親はそれをクリックする。
3. ...

Diagrams

データフローやコンポーネント関係を図示する。後から編集できるツールを使う (Excalidraw, draw.io, Google Drawings、またはコードで書ける Mermaid / D2 / Graphviz)。ホワイトボードの写真は編集できず一生そのままになるので避ける。図のソース (描画ファイルやコード) へのリンクを必ず添え、チームが再現・改訂できるようにする。

Interfaces

人や他システムとの接点 (UI、API / CLI のセマンティクス、ファイル形式) を示す。内部実装の全詳細ではなく、表に見える契約面を重視する。UI は精密なモックより、簡単なスケッチや振る舞いの説明でよい。

Related Documents

テスト計画や機能仕様など、関連文書へのリンク。

Glossary

新メンバーや外部読者向けに、馴染みのない用語を定義する。

内容次第 (該当時のみ・技術仕様)

後から変えにくい判断ほど cost が高いので、ここに厚く書く。

Constraints

予算・インフラ・依存による主要な制約。

Dependencies / Infrastructure

言語、ハードウェア、永続ストレージ、サードパーティ。実装後に変えるのが難しい判断は何かを深く考え、そこに絞る。簡単に差し替えられるものは軽く扱う。

Service Level Objectives (SLOs)

「速い」「高性能」「モバイルで快適」といった曖昧な目標を、測定可能で客観的な数値にする。稼働率・レイテンシ・規模を、括弧で文脈を添えて書く。

例:

• 目標: 99% の可用性 (two nines)。
• ビューポート内のサムネイルは、1 Gbps 接続のデスクトップで 400ms 以内に表示する。

Timeline

作業を、利害関係者にとって意味のある成果物が出るマイルストーンに分ける。誤解を早く見つけられる順序を優先する (例: ダミーデータでも UI を先に見せれば、認識のズレを実装前に検出できる)。各マイルストーンに「実装するもの / まだ実装しないもの」を添えてよい。

内容次第 (該当時のみ・リスクとコンプライアンス)

リスクが小さい対象ではまるごと省く。

Security

考慮した脅威、攻撃面 (悪意あるデータを処理しうる箇所)、信頼境界を書く。脅威が起こりにくい・無関係と思っても、そう判断した根拠を残す。各脅威は脅威タイトル → Scenario: (状況と影響) → Mitigations: (緩和策の箇条書き) の形式で書く。

例:

未認証の攻撃者が S3 バケット内の写真を発見する

Scenario: バケットが公開設定だと、URL を推測した第三者が写真を閲覧できる。 Mitigations:

• バケットを非公開にし、署名付き URL でのみアクセスさせる。
• ...

Privacy

機微データの扱い、保持期間、アクセス制御、暗号化。解決策より先に「何が問題か」に焦点を当てる。

Legal

規制 (金融・医療等) の順守、OSS のライセンス選定。

Monitoring / Alerting

SLO をどう測定し、違反をどう検知するかを書く。少なくとも「サービスが落ちたらどう気づくか」「性能が 100 倍悪化したらどう気づくか」「何のイベントでアラート (page) するか」に答える。

例: 95 パーセンタイルのレイテンシが 3s 以上で page。2 分平均の CPU が 90% 以上で page。

Logging

記録する重要イベント、ログレベル、保持期間、アクセス制御、機微データの除外。

内容次第 (該当時のみ・課題管理)

Open Issues

未解決の設計上の問題を、問題文 → 検討した選択肢 → 直近の次の一手の形で書く。「設計の欠陥」「複数案で迷っている」「情報待ち」が対象。

レビューで誤解された点は脇の会話で済ませず文書本文に取り込む。欄外の議論が 2〜3 往復しても決着しなければ、ここに移す。

Resolved Issues

決着した Open Issue を、決定を要約して移す。議論の全体を後世のために残す。

例: Decision: Sendamatic を使う。合わなければ Amazon SES。 Criteria: (評価基準のリスト) Candidates (魅力度の降順): (ランク付けした候補)

Alternatives Considered

却下した案、特に有力だった案や深く調べた案を pro/con で書く。網羅は不要で数行で十分。検討に値しなかった案は Definitely not: でまとめてよい。

例:

Google Photos

• Pros: 写真が収まれば無料
• Cons: Google への依存を避けたい

---

品質基準

書き上げたら次で自己点検する。

• 外部の文脈なしで読めること。 前提知識のない読者が必要な文脈を 1 ページ目で得られる。導入は逆ピラミッド (新聞記事の構造) で書く: まず goals と具体的な scenario を置き、広い読者 (他チーム・メンター・評価者) に通じる言葉で書き、深くなるほど前提を増やす。専門用語は誰にでも分かる言葉に置き換える
• 重要な詳細は書くが、実装そのものを書かない。 あらゆる詳細を書き切ると設計フェーズで実装を書いたことになり、Design Doc の意味がなくなる
• 図に投資する。 コンポーネント関係・データフロー・複雑な処理を視覚的に示す