writing-design-docs

設計ドキュメントの作成

構築するもの、その理由、動作をどのように検証するかを記録した、構造化された設計ドキュメントを作成します。出力先：docs/plans/YYYY-MM-DD-<topic>-design.md。このスキルは成果物を作成したら終了します。

プロセス

digraph design_doc {
    "Explore codebase & context" [shape=box];
    "Propose 2-3 approaches" [shape=box];
    "User selects approach" [shape=diamond];
    "Draft each section" [shape=box];
    "Write EARS requirements" [shape=box];
    "Present to user for review" [shape=box];
    "User approves?" [shape=diamond];
    "Write to docs/plans/" [shape=box];
    "Done" [shape=doublecircle];

    "Explore codebase & context" -> "Propose 2-3 approaches";
    "Propose 2-3 approaches" -> "User selects approach";
    "User selects approach" -> "Propose 2-3 approaches" [label="none fit"];
    "User selects approach" -> "Draft each section" [label="selected"];
    "Draft each section" -> "Write EARS requirements";
    "Write EARS requirements" -> "Present to user for review";
    "Present to user for review" -> "User approves?";
    "User approves?" -> "Draft each section" [label="revise"];
    "User approves?" -> "Write to docs/plans/" [label="yes"];
    "Write to docs/plans/" -> "Done";
}

アプローチの提案

ドラフトを作成する前に、解決策の選択肢を検討します。コードベースと関連ライブラリを調査してから、2〜3種類のアプローチを提案します。

• 推奨案を最初に示し、その理由を説明します
• 各アプローチについて、アーキテクチャの概要、長所、短所、工数の見積もりを示します
• よりシンプルで小規模な案と、より堅牢で拡張性の高い案をそれぞれ少なくとも1つ含めます
• 設計の方向性を決定する前に、ユーザーに選択してもらいます

設計ドキュメントのテンプレート

6つのセクションで構成します。詳細さは複雑さに応じて調整してください。「規模に応じたガイド」を参照してください。

1. 概要

2〜4文で、何を行うか、その理由を説明します。忙しいエンジニアがこれだけを読んでもプロジェクトを理解できる内容にします。

2. プロジェクトの目標と対象外

目標： 解決する問題と、必ず満たすべき不変条件を記載します。具体的に記述してください。「高速」ではなく「p99 が 200ms 未満」のように記述します。

対象外： 明示的にスコープ外とする、妥当な項目を記載します。目標を否定するのではなく、対応しないと決めた項目を示します。

3. 背景

• きっかけ：GitHub の Issue、Slack のスレッド、その他の発端
• コードベース：この作業に関連する既存のフォルダー、ファイル、設計ドキュメント
• 外部ドキュメント：サードパーティライブラリのドキュメントの URL
• 参考資料：設計の根拠となったブログ記事、RFC、その他の資料
• 影響範囲：変更対象となるモジュールやディレクトリ

4. システム設計

• アーキテクチャ概要：コンポーネント間の連携を説明します。必要に応じて図を使います。
• 新規または変更するインターフェース：クラス／構造体の定義、API の境界などを記載します。実装ではなく、形を示します。
• 主要な関数：重要な関数と、期待される動作を記載します。契約と不変条件も示します。
• 検討した代替案：採用しなかったアプローチを却下した理由を説明します。

5. 必要なライブラリとユーティリティ

外部依存関係：

パッケージ	バージョン	用途
name	^x.y.z	必要な理由

内部モジュール：

モジュール	パス	用途
name	src/path/	提供する機能

依存関係がない場合も、このセクションは省略せず、「なし」と記載します。

6. テストと検証

最も重要なセクションです。ここを最も詳細に記述してください。

受け入れ基準

すべての基準を EARS 形式で記述します。各基準はテスト可能で、曖昧さのないものにします。

エッジケース

関連する項目を網羅します。並行処理／競合状態、依存関係の障害、エラー処理／復旧、境界条件、セキュリティ上の考慮事項などです。

検証コマンド

正しさを確認するための具体的なコマンドを記載します。リンティングとフォーマットのチェックも含めます。

EARS クイックリファレンス

パターン	テンプレート	例
常時	THE SYSTEM SHALL [動作]	THE SYSTEM SHALL 保存データをすべて暗号化する
イベント駆動	WHEN [イベント] THE SYSTEM SHALL [動作]	WHEN リクエストがレート制限を超えた場合 THE SYSTEM SHALL HTTP 429 を返す
状態駆動	WHILE [状態] THE SYSTEM SHALL [動作]	WHILE サーキットブレーカーが開いている間 THE SYSTEM SHALL キャッシュ済みのレスポンスを返す
オプション	WHERE [機能] THE SYSTEM SHALL [動作]	WHERE 詳細ログが有効な場合 THE SYSTEM SHALL リクエスト本文を記録する
禁止事項	THE SYSTEM SHALL NOT [動作]	THE SYSTEM SHALL NOT 内部エラーの詳細をクライアントに公開する
複合条件	WHEN [a] AND [b] THE SYSTEM SHALL [動作]	WHEN キューが満杯で AND メッセージの優先度が高い場合 THE SYSTEM SHALL 優先度の低い最古のメッセージを破棄する

ルール： SHALL を使い、「should」や「may」は使いません。各要件は個別にテストできるものにします。曖昧な表現を避け、測定可能な基準を使います。

スケーリングガイド

セクション	小規模（約150語）	中規模（約400語）	大規模（約800語）
概要	2文	3文	4文
目標／非目標	各2～3項目	各4～5項目	不変条件を含む6項目以上
コンテキスト	リンクのみ	リンク＋ファイル一覧	リンク＋ファイル＋影響
システム設計	1段落	インターフェース＋関数	図＋API全体
ライブラリ	表または「なし」	表＋根拠	表＋代替案
テスト	EARS 3～5項目	EARS 8～12項目＋エッジケース	EARS 15項目以上＋包括的なエッジケース

よくある間違い

間違い	修正方法
テストを後回しにする	仕様でテストケースを定義し、レッド／グリーンのTDDを実施する
目標が曖昧	数値を加える：「p99を800msから200msに短縮する」
非目標がない	範囲が明記されていない場合は、範囲内と見なされる
実装を設計として扱う	コードではなく、契約と動作を記述する
コンテキストへのリンクがない	きっかけとなった情報にリンクする。将来の読者には理由が必要です

例

段階別の例については、examples/ を参照してください。

• small-cli-flag.md — --verbose フラグを追加する（最小限ながら完全）
• medium-api-endpoint.md — 認証とレート制限を備えた REST API
• large-event-system.md — リトライとDLQを備えた分散イベントパイプライン