spec-driven-development

仕様駆動開発

概要

SDDでは、仕様を信頼できる唯一の情報源とし、コードは仕様に従います。その逆ではありません。曖昧な説明でAIにプロンプトを与え、期待どおりの出力を祈るのではなく、まず正確な仕様を定義し、それに厳密に制約されたコードをAIに生成させます。

仕様がなければ、AIは何千もの細かな判断をひそかに行います。仕様があれば、それらの判断はコードを書く前に、明示的にあなたが行います。これにより、方針転換は手作業での書き直しではなく、体系的な再生成になります。

クイックスタート

1. /sdd:init — constitution.md を作成します（プロジェクトごとに一度、機能の仕様を書く前に実施します）
2. /sdd:research [description] — 既存コードの動作を file:line 形式の引用付きで把握します（新規開発の場合は省略します）
3. ACを書く前に、AIの暗黙の前提を明らかにし、修正します
4. /sdd:specify [description] — MoSCoWで優先順位付けしたACを含む spec.md を生成します
5. 各段階で人間の承認を得ながら、ゲートに従います：明確化 → 計画 → タスク → 実装 → 検証

手順の詳細：references/workflow-phases.md。

使用する場面

SDDが必要な兆候：

• AIが制約を無視したり、要件に合わないコードを生成したりする
• 同じプロンプトでも、セッションごとに異なる実装が生成される
• 要件が複雑で、関係者が複数いる、または複数の領域にまたがる懸念事項がある
• コードを書く前に、チームで技術的な理解を共有する必要がある
• 機能が認証、データモデル、APIコントラクト、またはデータベーススキーマに関わる

以下の場合は完全に省略します： 1行の修正、誤字の修正、使い捨てのプロトタイプ、および1日未満の単独での探索的な試作。

手続きのレベルを選ぶ

変更ごとに、同じプロセスが必要とは限りません。リスクをカバーできる最も軽いレベルを選びます。

	S — 軽量	M — 標準	L — 完全
使用場面	1回のセッションで完了し、ファイル数が3以下で、スキーマ／コントラクト／認証の変更がない	新しいエンドポイント、テーブル、またはユーザーに見える動作。複数のセッションにまたがる	認証、決済、マイグレーション、規制対象の領域、または不慣れなコード
成果物	IssueまたはPR本文にACを記載	spec.md、plan.md、contracts/、tasks.md	＋ research.md、decision_log.md、walkthrough.md
ゲート	マージ前のセルフチェック	1、2、3、5	0、R、1–5、C
批評役	なし	任意	必須

判断ルール： まずMから始めます。以下の条件をすべて満たす場合に限り、Sに下げます。1回のセッションで完了する、ファイル数が3以下、コントラクトやスキーマの変更がない、簡単に元に戻せる。以下の条件のいずれかに当てはまる場合は、Lに上げます。認証または決済、元に戻せないデータマイグレーション、規制対象の領域、または通話に参加している誰も読んだことのないコード。

どちらの失敗も、同じように大きな代償を伴います。Sの変更にLの手続きを適用すると「Markdownに溺れる」ことになり、Lの変更にSの手続きを適用することが、このスキルが存在する理由です。判断に迷ったときは、規模ではなく可逆性を基準にします。

レベルはプロジェクト単位ではなく、変更ごとに決めます。途中でレベルを上げるのは普通のことです。たとえばスキーマ変更が判明した時点で、SからMに引き上げます。レベルを下げることはありません。すでに必要だと判断したゲートを破棄することになるからです。

重要な実践：曖昧な要件を具体化する

ACを書く前に、曖昧な要件を測定可能な目標に変換します。「速くする」は「4G接続でLCP < 2.5s」のようにします。ACに対する失敗テストを書けない場合、そのACは十分に具体的ではありません。 変換例： references/artifact-templates.md → Writing Concrete Acceptance Criteria。

---

ディレクトリ構成

constitution.md            # Immutable project principles (one per project)

specs/
  [feature-branch-name]/
    research.md        # How the system works TODAY, cited file:line   (0.5)
    spec.md            # Requirements — WHAT and WHY, MoSCoW           (1)
    plan.md            # Implementation strategy — HOW                 (2)
    data-model.md      # Entities, relationships, schemas              (2)
    contracts/         # Interfaces — LOCKED after Gate 2              (2)
    tasks.md           # Atomic executable task list                   (3)
    progress.md        # Optional: state across context resets         (4)
    validation.md      # Traceability matrix                           (5)
    walkthrough.md     # Optional: narration for reviewers             (5)
    decision_log.md    # Optional: rationale for key decisions
  archive/             # Completed specs, kept after the feature ships

すべての成果物は、コンパクションのチェックポイントでもあります。各段階でのまとまりのない探索を、次の段階に必要な唯一のテキストに集約します。

---

フェーズ0 — 憲章 (プロジェクトごとに一度)

実行： /sdd:init → プロジェクトルートに constitution.md を作成します。

すべての機能に適用される、変更不能な制約をまとめたバージョン管理対象のドキュメントです。アーキテクチャの原則、技術スタック、セキュリティ上の制約、命名規則、および明示的に禁止されたパターンを記載します。AIエージェントはこれに違反することを禁じられており、すべての実装プロンプトに全文が含まれます。

プロジェクトの根本的な方針が変わった場合に限り更新します。機能ごとの更新は行いません。

---

フェーズ 0.5 — 調査 (機能ごとに条件付き)

実行: /sdd:research [feature description] → specs/[feature]/research.md

要件を起草する前に、関連するシステムの部分が現在どのように動作しているかを簡潔にまとめたマップです。

実行するタイミング： 自分が書いていない、または覚えていないコードに機能が関わる場合、複数の有効なアーキテクチャが存在する場合、あるいはリファクタリングや移行を行う場合です。新規コードを作成する場合や、すべての接点を記憶から挙げられる場合は、省略します。

4つのルール：

• すべての主張に file:line を引用します。 引用のない調査結果は推測です。
• 負荷の高い作業はサブエージェントに割り当てます。 Glob、grep、ファイル全体の読み取りは分離されたコンテキストで実行し、簡潔にまとめた要約のみを戻します。
• 存在するものを記述し、あるべき姿は記述しません。 要件はフェーズ 1 で扱います。
• 約200行以内に収めます。 それを超えると、簡潔なまとめではなく未加工のダンプになります。

このフェーズが最も効果的な理由： 約200行の調査をレビューすれば、何千行もの誤ったコードを防げます。コードをレビューすれば、誤った1行をその都度防げます。ゲート R は、実際のコードを自分で読む価値がある唯一のゲートです。

詳細：references/workflow-phases.md → Phase 0.5。

---

5フェーズのワークフロー (機能ごと)

フェーズ	実行	読み込むもの	生成物	ゲート
1 — 仕様策定	/sdd:specify [description]	research.md、ユーザーの意図	spec.md	ゲート 1
1b — 明確化	/sdd:clarify	spec.md	解決済みの [NEEDS CLARIFICATION]、新たなエッジケースの AC	（ゲート 1 の一部）
2 — 計画	/sdd:plan	spec.md、constitution.md、research.md	plan.md、data-model.md、contracts/	ゲート 2
3 — タスク	/sdd:tasks	plan.md、contracts/	tasks.md	ゲート 3
4 — 実装	タスクごとに /sdd:next-task	1つのタスクとその AC、コントラクト	コード、テスト、コミット	ゲート 4（タスクごと）
5 — 検証	/sdd:validate	すべての成果物とコード	トレーサビリティマトリクス、乖離レポート、ウォークスルー	ゲート 5 + ゲート C

すべてのゲートは人間による承認ポイントです。 AI が自身の出力を承認することはできません。ゲート 0、R、1〜5、C の完全なチェックリストは、/sdd:checklist [domain] とともに references/quality-gates.md にあります。これは、ソフトウェアではなく仕様をテストする機能ごとのチェックリストを生成します。

客観的に判断できるルールは、リクエストのままにせず、自動的に適用する必要があります。書き込み前のフックで contracts/ の凍結を実効性のあるものにでき、constitution.md から、ツールが自動的に読み取る AGENTS.md を生成できます。機械化してはならないものも含め、references/enforcement.md を参照してください。

各フェーズのルールと禁止事項

フェーズ	ルール	禁止事項
1 — 仕様策定	すべての [MUST] AC は個別にテスト可能であること	実装の詳細 — 技術、関数、テーブルの名前は記載しない
2 — 計画	すべての [MUST] AC を、少なくとも1つのコンポーネントに対応付けること	AC による正当化のない抽象化、constitution.md に含まれない技術
3 — タスク	すべてのタスクで、満たす AC を明示し、テストを先に行うこと	約3ファイルを超えるタスク、または AC への参照がないタスク
4 — 実装	タスクごとに新しいコンテキストを1つ用意する — constitution.md 全体に加え、そのタスクの AC、コントラクト、計画のセクション、エンティティのみを含めること	contracts/ に触れること、spec.md の範囲外の振る舞いを追加すること、タスク間でコンテキストを引き継ぐこと
5 — 検証	まず仕様に合うようにコードを修正し、その後ウォークスルーを作成すること	コードに合うように仕様を編集すること

フェーズ 1 — 仕様化

spec.md を生成する前に Assumptions Surface Prompt を実行し、ロール、権限、エラー時の動作、スコープに関する暗黙の前提が受け入れ基準に固定される前に修正します。research.md が存在する場合、仕様がそれに矛盾してはなりません。

spec.md には、概要、ユーザーストーリー、境界（常に行うこと／先に確認すること／決して行わないこと）、[MUST] [SHOULD] [COULD] [WONT] を付けた Given／When／Then 形式の受け入れ基準、明示的な対象外項目、未解決の質問を記載します。エラーやエッジケースに関する受け入れ基準は必須です。正常系だけでは Gate 1 を通過できません。

完全仕様または差分仕様。 既存の動作を変更する場合、その動作を再定義する必要はありません。差分仕様ではベースラインを宣言し、変更点だけを列挙します。

モード	使用するケース	ヘッダー
Full	保持すべき既存の動作がない、新しい機能の場合	Mode: Full
Delta	すでに提供されている動作を変更、拡張、または削除する場合	Mode: Delta + Baseline:

差分仕様の受け入れ基準には、[ADDED]、[MODIFIED]、[REMOVED]、または [UNCHANGED] のラベルを付けます。最後のラベルは、変更によって壊してはならない動作に使用します。ベースラインには、以前の仕様、または以前の仕様がない場合は research.md に記載された調査結果を指定します。解決可能なベースラインがない差分仕様はレビューできません。references/workflow-phases.md → Delta Specs を参照してください。

contracts/ は Gate 2 の通過時点で凍結します。手順の詳細は references/workflow-phases.md、プロンプト形式（ファイルアクセスが可能なエージェント向けの A、ステートレスなインターフェース向けの B）は references/prompt-patterns.md、トレーサビリティマトリクス、ドリフトレポート、ウォークスルーの形式は references/output-formats.md に記載されています。

---

仕様のドリフト

ドリフトは、AI が仕様にない「妥当な前提」を置くと発生します。上記の各ルールは、それぞれ異なる前提を取り除くためにあります。憲章はプロジェクトレベルの前提を、調査は既存システムに関する前提を、明確化はアーキテクチャになる前の曖昧さを、凍結された契約はインターフェースに関する推測を、タスクごとにコンテキストを分けることは過去の作業から引き継がれる前提を取り除きます。

残りを補う習慣は 2 つあります。冗長さより具体性を優先すること。「リソースが見つからない場合は 404 を返す」は、3 段落の説明に勝ります。そして、タスクごとにコミットすること。そうすれば、ドリフトはいつでも 1 回のリバートで元に戻せます。

失敗パターンの詳細は references/anti-patterns.md を参照してください。

---

本当の制約はコンテキスト

AI エージェントはステートレス関数です。出力の品質は入力の品質によって制限されます。ここにある各フェーズ、ゲート、成果物はすべて、何を入力に含めるかを機械的に決定するものです。

• 各フェーズの成果物はすべて、情報を圧縮したものです。 research.md には 40 個のファイルを読んで得た内容が残り、plan.md には調査結果から残った内容が記載されます。それぞれ、意思決定に不可欠な事実をすべて維持しながら、およそ 95% を削減します。したがって、成果物の長さは品質の指標です。900 行の仕様は、圧縮をやめて情報をため込み始めています。
• 上限に達してからではなく、意図的に圧縮します。 使用率を 40〜60% の範囲に保ちます。コンテキスト不足で自動圧縮が発動すると、切迫した状況でどの詳細を失うかが自動的に決まります。

モデル全体については references/ai-agent-patterns.md → Context Engineering を参照してください。

---

理解の負債

仕様は、正しさとは無関係な失敗パターン、つまり動作するが誰にも理解されていないコードを防ぎます。エージェントは人間が読むより何倍も速くコードを生成するため、チームは出荷する内容への理解が測定可能なほど低下する一方で、プルリクエストを大幅に多くマージします。この負債は、最初のインシデント、オンボーディング、またはリファクタリングが起きるまで表面化しません。

成果物が実際に読まれて初めて、SDD はこの負債を返済できます。差分をざっと見るのではなく、仕様と計画をレビューしてください。そうすれば、注意を情報密度の低い約 2000 行から、情報密度の高い約 400 行へ移せます。レビュー担当者が実装の仕組みより先に意図を読めるよう、仕様は同じ PR に含めてください。フェーズ 4 の後には順を追ったウォークスルーを依頼し、次の担当者が判断の根拠を引き継げるよう、仕様は削除せずアーカイブしてください。

Gate C はマージ前にこれを徹底します。

---

ユーザーとのやり取り

このワークフローでは大量の Markdown が生成されますが、そのほとんどは人間向けではなく、次のフェーズ向けです。この2つを混同することが、SDD が形式主義だと見なされる原因です。

• 成果物はファイルに書き込み、人間には判定を伝えます。 ディスクに書き込んだばかりの成果物全体を、レスポンスに貼り付けてはいけません。
• 判定を先に、根拠を後に伝えます。 ゲートの結果、差分レポート、検証の出力はすべて、合格／不合格と件数を最初に示し、その後に詳細を示します。
• 不確実性は二択で示します。 コードまたは引用した成果物で検証済みの場合は [CONFIRMED]、推測に基づく場合は [VERIFY] とします。確信度をパーセンテージで作り上げてはいけません。
• 出力の行数上限を守ります。 references/output-formats.md にあるユーザー向け出力には、形式とともにそれぞれ上限が定められています。

---

生きたドキュメント

• 決定が変わった場合： /sdd:amend を実行します。ファイルを手動で修正してはいけません。
• ワークフロー外でコードが変更された場合： /sdd:reconcile を実行します。
• コードと一緒に仕様をコミットします： 仕様ファイルは実装と同じ PR に含めます。
• 仕様にバージョンを付けます： 各 spec.md には Status と Version ヘッダーが必要です。
• 完了したらアーカイブします： 機能のリリース後、完了した仕様を specs/archive/ に移動します。

仕様とコードが食い違う3つの状況

これらを混同すると、仕様はいつの間にか虚構になります。実行するコマンドも、どちらを編集するかも異なります。

状況	原因	コマンド	変更対象
ドリフト	承認済みの仕様から実装が誤って乖離した	/sdd:validate	コード
仕様変更	要件が実際に変更された	/sdd:amend	仕様の連鎖、次にコード
整合	ホットフィックス、上流のリファクタリング、別チームによる変更など、ワークフロー外で意図的にコードが変更された	/sdd:reconcile	差分ごとに人間が決定

/sdd:reconcile が単独で何かを編集することはありません。差分を分類して変更方針を提案し、それぞれを人間が承認します。提案を自動承認すると、ドリフトを隠蔽する仕組みになってしまいます。references/anti-patterns.md → Anti-Pattern 21 を参照してください。

---

リファレンス一覧

リファレンスファイルはすべて、ここから1階層下にあります。現在のフェーズで必要なものだけを読み込みます。

必要なもの	ファイル
あらゆる成果物のテンプレート	references/artifact-templates.md
各フェーズのやり取りに使うプロンプト	references/prompt-patterns.md
フェーズごとの詳細な手順	references/workflow-phases.md
レビューチェックリスト、ドメイン別に生成されるチェックリスト、CI/CD	references/quality-gates.md
フック、コントラクトロック、ワークツリー、AGENTS.md ブリッジ	references/enforcement.md
ユーザーが読むすべてのものの形式	references/output-formats.md
コンテキストエンジニアリングとマルチエージェントのパターン	references/ai-agent-patterns.md
よくある失敗パターンと修正方法	references/anti-patterns.md
1ページのチートシート	references/quick-reference.md
トピック別ナビゲーション	references/INDEX.md