spec-driven-development

AI ソフトウェアファクトリーのための仕様駆動開発

仕様を AI コード生成パイプラインへの実行可能な入力とするソフトウェア開発の手法です。ファクトリーモデルでは、仕様が設計図となり、AI エージェントが組み立てラインとなり、検証が品質管理となります。ゲートで、欠陥が積み重なる前に検出します。

パイプラインの概要

INCEPTION → [SPECIFY] → REVIEW → [DECOMPOSE] → REVIEW → [IMPLEMENT] → REVIEW → [VERIFY] → DELIVER
                 ↑         ↑          ↑            ↑           ↑           ↑          ↑         ↓
            Phase 1    Gate 1    Phase 2       Gate 2    Phase 3      Gate 3    Phase 4   Gate 4

各フェーズは、次のフェーズが始まる前にゲートを通過します。ゲート 1 で検出した欠陥の修正には数分かかりますが、同じ欠陥がゲート 4 で見つかると、修正に数時間かかります。

既存の承認済み PRD、アーキテクチャ文書、またはイシュー一式が、references/factory-review-lanes.md に記載された最低限の引き継ぎ要件を満たしている場合は、それを仕様として使用してください。 このワークフロー全体を通じて、SPEC.md はその正式な仕様を指します。新しいファイルを作成したり、重複するコピーを用意したりする必要はありません。同等の内容とトレーサビリティを検証してください。 書式固有のスクリプトは、想定される入力形式が当てはまる場合にのみ実行してください。それ以外の場合は、同等の内容チェックと不足情報を明示的に記録してください。

SDD の基本原則

1. 重要な意図を明確にする。 仕様は読みやすく、テスト可能な状態に保ちます。エージェントは確認を求められます。未解決の重要な選択事項には担当者を割り当て、その決定境界に達する前に、依存する作業を停止する必要があります。
2. 簡潔さより完全性を優先する。 受け入れ基準が 1 つでも欠けていれば、それは機能が 1 つ欠けているのと同じです。エッジケースを事前に仕様化するには数分かかりますが、本番環境で発見すると数時間から数日かかります。
3. 説明の詳しさよりテスト可能性を優先する。 明確な合格または不合格を判定できない AC は AC ではなく、単なる期待です。
4. ゲートで欠陥を早期に検出する。 ゲート 1（仕様レビュー）での修正には数分かかります。ゲート 4（受け入れレビュー）での修正には数時間かかり、実装全体を破棄する必要が生じる場合もあります。
5. 仕様を唯一の信頼できる情報源とする。 下流の成果物はすべて仕様にトレースできる必要があります。明示的に記録されていない逸脱は欠陥です。
6. 仕様をテストオラクルの指針とする。 Gherkin 形式の AC は実行可能なテストケースにできる場合がありますが、それでも実装、カバレッジ、オラクルのレビューが必要です。独立したシナリオや非公開のシナリオによって、目に見える例に潜む不足を明らかにできます。

読み込みガイド

参考資料	読み込むタイミング	ファイル
SDD の概要と理念	ソフトウェアファクトリーのメタファー、SDD と従来の要件定義の違い、仕様はコミュニケーション用の成果物ではなく実行可能な入力であるという基本原則など、「なぜ」について理解する必要があるとき	references/sdd-overview.md
AI ファクトリーのパイプライン	各フェーズの入力、出力、移行ルールを含む全 5 フェーズのパイプラインを確認するとき、またはパイプラインをゼロから設計するとき	references/ai-factory-pipeline.md
ファクトリーのレビュー・レーン	振る舞いの受け入れと保守性を分けるとき、または既存の計画成果物を適応させるとき	references/factory-review-lanes.md
仕様の品質ゲート	SPEC.md を作成し、ゲート 1 の前に検証する必要があるとき — 優れた仕様と曖昧な仕様を分ける 7 つのゲート	references/spec-quality-gates.md
レビュー記録と前提	判定を候補に紐づけるとき、暫定的な選択を追跡するとき、または保留中の指摘事項を解決するとき	references/review-records.md
フェーズゲートの方法論	レビューゲート（4 つのいずれか）を実施し、判断基準、判定形式、エスカレーションの手順を確認する必要があるとき	references/phase-gate-methodology.md
方法論選択マトリクス	どの仕様方法論（BDD、Formal、DbC、OpenAPI、ADR）が状況に適しているか、適用場面や AI 対応度の評価を確認するとき	references/methodology-matrix.md
AI 仕様の NFR エンコーディング	非機能要件（パフォーマンス、セキュリティ、オブザーバビリティ）を機械可読形式で表現する必要があるとき	references/nfr-encoding.md
フォーマット変換	仕様フォーマット間のマッピング（Gherkin ↔ OpenAPI ↔ SPEC.md ↔ JSON Schema）が必要なとき、または人間向け PRD を AI 対応の仕様に変換するとき	references/format-translation.md
批判とトレードオフ	SDD を「使わない場面」を判断する必要があるとき — 仕様がボトルネックになること、GIGO、ドリフト、仕様の過不足、形式手法のコストなど、率直な制約	references/critiques-and-tradeoffs.md
実例 — 完全な SPEC.md	出力の詳細度を調整するため、完成度の高い仕様を確認したいとき — パスワードリセット機能に関する適切な AC 形式、エッジケースの列挙、NFR のしきい値、データ契約、前提を紹介しています	references/example-spec.md

方法論のクイック選択

どの仕様方法論が状況に適しているかわからない場合は、このクイックリファレンステーブルを使用してください（詳しくは references/methodology-matrix.md を読み込んでください）。

懸念事項	選択肢	AI 対応度	生成される形式
REST API 契約	OpenAPI	非常に高い	YAML/JSON 仕様
イベント／メッセージのスキーマ（Kafka、RabbitMQ）	AsyncAPI	高い	YAML/JSON チャネル仕様
振る舞いの要件（システムが行うこと）	BDD / Gherkin	高い	Given/When/Then を含む .feature ファイル
インターフェースの正しさ（事前条件／事後条件／不変条件）	契約による設計	非常に高い	コード内のアサーション
分散システムの正しさ（合意形成、プロトコル）	TLA+ / Alloy	非常に高い（対象範囲は限定的）	数学モデル
アーキテクチャ上の決定（X を選んだ理由）	ADR	中程度	構造化された Markdown
システム構造（ボックスと線）	C4 モデル	中〜高	PlantUML / 構造化テキスト
ステークホルダーの生の意図	ユーザーストーリー	低い（精緻化が必要）	「私は…として…したい」

複合アプローチ： ほとんどのシステムでは、これらのうち 3〜4 つを組み合わせる必要があります。REST API には OpenAPI、イベントストリームには AsyncAPI、重要な振る舞いには Gherkin シナリオ、チーム間のインターフェース境界には DbC アサーションを使用します。

テンプレート

テンプレート	パイプラインのフェーズ	ファイル
SPEC.md	フェーズ 1 — 仕様の作成（SPECIFY）。最初に作成します。課題、スコープ、ユーザーストーリー、AC、エッジケース、NFR、データ契約を記述します	templates/SPEC.md
FACTORY-REVIEW.md	タスクの統合とリリース承認 — 同じ候補に対する動作面とエンジニアリング面の判定をそれぞれ行います	templates/FACTORY-REVIEW.md
REVIEW.md	ゲート 1-4 — フェーズゲートレビュー。各ゲートの移行時に使用します。仕様レビュー、計画レビュー、実装レビュー、受け入れレビューが対象です	templates/REVIEW.md
TASK-PLAN.md	フェーズ 2 — 作業の分解（DECOMPOSE）。承認済みの仕様から、タスクグループ、依存関係グラフ、タスクごとの AC、実装指示を抽出します	templates/TASK-PLAN.md
VERIFICATION.md	フェーズ 4 — 検証（VERIFY）。実装後に、AC の合否マトリクス、コンプライアンススコア、修正方法を記載した失敗報告書を作成します	templates/VERIFICATION.md

スクリプト

スクリプト	実行するタイミング	ファイル
spec-quality-check.sh	SPEC.md の作成または編集後 — 必須セクション（課題の説明、スコープ、AC、エッジケース、NFR、前提条件）がすべて存在することを検証します	scripts/spec-quality-check.sh
spec-to-tasks.sh	TASK-PLAN.md の作成後 — 仕様のすべての AC に、それをカバーするタスクへの参照があることを検証します	scripts/spec-to-tasks.sh

トリガー条件

次の場合にこのスキルを読み込みます。

• ソフトウェアファクトリーを構築している — AI エージェントがゲート付きパイプラインを通じて、構造化された仕様からコードを生成するシステム
• 仕様をもとに実装を進める AI コード生成パイプラインを設計または改良している
• AI エージェント（人間だけではなく）が利用する仕様を作成する必要がある
• プロジェクト向けに仕様策定手法（BDD、Formal、OpenAPI-first）を評価している
• SPEC.md、TASK-PLAN.md、REVIEW.md、または VERIFICATION.md のテンプレートが必要である
• 仕様に照らして AI 生成コードをレビューまたは検証している

クイックリファレンス：パイプラインのステップ

ステップ	アクション	読み込むリファレンス	生成物
1	承認済みの同等の仕様を再利用するか、SPEC.md を作成し、不足している引き継ぎ情報を補います	references/spec-quality-gates.md（ゲート 1 の前に検証）	SPEC.md
2	対応している形式なら spec-quality-check.sh を実行します。対応していない場合は、同等の内容チェックを実施した記録を残します	—	検証レポート
3	ゲート 1 — 品質ゲートに照らして仕様をレビューし、REVIEW.md を作成します	references/spec-quality-gates.md、references/phase-gate-methodology.md	REVIEW.md（APPROVED/CONDITIONS/REJECTED）
4	承認済みの仕様を TASK-PLAN.md に分解します — 各タスクを仕様のセクションに対応付けます	references/ai-factory-pipeline.md（Decompose フェーズ）	TASK-PLAN.md
5	ゲート 2 — 依存関係が適切に記述されているか、仕様が網羅されているかをタスク計画についてレビューします	references/phase-gate-methodology.md	REVIEW.md
6	各タスクを実装します — エージェントのセッションごとに 1 つのタスクを担当します	—	コード/PR
7	ゲート 3 — 仕様への準拠を検証し、統合前にエンジニアリング面の個別レーンの結果を記録します	references/phase-gate-methodology.md	REVIEW.md
8	すべての AC に対して検証を実行し、VERIFICATION.md を作成します	—	VERIFICATION.md
9	ゲート 4 — 検証レポートをレビューし、BLOCKING の失敗がない場合にのみリリースします	references/phase-gate-methodology.md	最終承認

手法の詳細については、references/sdd-overview.md（基本方針）または references/ai-factory-pipeline.md（並列実行を含むパイプライン全体の詳細）を読み込みます。

パイプラインモードとエントリーポイント

パイプラインの開始フェーズ

必ずしも SPECIFY から始める必要はありません。すでに用意できているものに応じたフェーズから開始してください。

手元にあるもの	開始フェーズ	最初に使うもの
漠然としたアイデア、会話、または PRD	フェーズ 1 — SPECIFY	templates/SPEC.md + references/format-translation.md
インタラクション契約を含む承認済みのプロダクトスコープ	フェーズ 1 — SPECIFY	product-design-and-ux の引き継ぎ資料 + templates/SPEC.md
明確で承認済みの仕様書、または同等の計画成果物	フェーズ 2 — DECOMPOSE	templates/TASK-PLAN.md + references/ai-factory-pipeline.md
仕様書 + 承認済みのタスク計画	フェーズ 3 — IMPLEMENT	タスクごとの指示を含むタスクカード
検証が必要な既存コード	フェーズ 4 — VERIFY	templates/VERIFICATION.md

使用するパイプラインモード

すべての変更で 4 つのゲートすべてが必要なわけではありません。モードを選択してください。

モード	使用する場面	実行するゲート	仕様の詳細度
Full	新規機能、複数エージェントでの作業、高リスクな変更、複雑なインターフェース	4 つのゲートすべて	AC、NFR、データ契約、エッジケースを含む完全版の SPEC.md
Lightweight	単純なバグ修正、内容を十分に把握している変更、単一ファイルの編集	ゲート 1（簡易版）→ 実装 → ゲート 4（簡易版）	ユーザーストーリー 1 件、AC 1～3 件、簡略化した NFR
Minimal	プロトタイプ、スパイク、調査、使い捨てコード	なし — 正式なゲートを省略	ミニ仕様書：1 段落 + AC 3 件。NFR テーブルおよび契約なし

目安： 60 秒以内に修正方法がわかり、変更対象が 1 ファイルなら、Lightweight モードを使用してください。適切な解決策がわからない場合は、Full モードを使用してください。ゲートによって早い段階でミスを検出できます。

レビューの有効性と判断

候補／契約の識別と実行済みエビデンスには templates/REVIEW.md を使用し、 templates/SPEC.md の前提条件一覧を使用して、その ID をタスクに引き継ぎます。 関連する変更があった場合は、影響を受ける承認／エビデンスが無効になります。影響の大きい未解決の選択肢がある場合、 マージ／リリース前に依存する処理をブロックします。リスクが低く、取り消し可能な選択肢は、 既存の権限のもとでまとめて処理できます。安定した指摘 ID によって、すべての提案をチケット化せずに、 フォローアップの担当者と検証済みのクローズ状態を維持できます。 これらの引き継ぎ時には references/review-records.md を参照してください。バックログと権限の振り分けは BMad が担い、 ランタイム状態の整合性と適用はハーネスエンジニアリングが担います。

ゲートからの復旧と修正

ゲートで成果物が却下された場合はどうなるでしょうか。パイプラインは停止せず、反復します。

修正ループ

Artifact submitted → Gate review → REJECTED or CONDITIONS
                                         ↓
                              Return to current phase
                                         ↓
                              Patch specific findings
                                         ↓
                              Resubmit for re-review
                                         ↓
                              APPROVED → next phase

全面書き直しではなくパッチを適用する方法

各指摘は、範囲が限定された修正可能な問題を示しています。指摘箇所にパッチを適用してください。

指摘の重大度	対応	例
BLOCKING	直ちに修正します — 解決するまでゲートを通過できません	テスト不可能な AC を、PASS／FAIL が明確な条件に書き換える
CRITICAL	修正が必須です。指摘が 2 件以下で、例外を文書化している場合はゲートを通過できることがあります	ユーザーストーリーのセクションに不足しているエッジケースを追加する
MINOR	可能であれば次のフェーズの前に修正します。是正計画があればゲートを通過できます	データ契約にリクエスト／レスポンスのスキーマを追加する
INFO	今後の改善のために記録します。ゲート通過に対応は不要です	代替となるフィールド名を提案する

再レビューの範囲

パッチの適用後、レビュアーが範囲を決定します。

• 全体の再レビュー： REJECTED 判定の場合に必須です。パッチを適用した箇所だけでなく、成果物全体を再評価します。
• 対象を絞った再レビュー： CONDITIONS 判定の場合に可能です。影響を受けた指摘とその周辺のコンテキストのみをレビューします。

部分的な修正によるリスク： BLOCKING の指摘だけを修正して CRITICAL の指摘を放置すると、同じゲートで再び却下されます。ゲート 1 で数分で修正できる CRITICAL の指摘も、ゲート 4 で見つかると修正に数時間かかります。

よくある修正パターン

失敗パターン	修正方法	防止策
テストできない AC（「対応する必要がある」「効率的である必要がある」などの曖昧な表現）	各 AC を、明示的な Given／When／Then と二値の結果を使って書き直します	提出前に Gate 1 のチェックを適用します
エッジケースの不足	ストーリーごとにエッジケースを列挙します。各ストーリーで最低 3 つ必要です	spec-quality-gates の「問題が起こりうる 5 つのこと」テストを使用します
曖昧な NFR（「高速である必要がある」「安全である必要がある」）	具体的な閾値と検証方法に置き換えます	nfr-encoding リファレンスの「これをテストにできるか？」テストを使用します
不完全な契約（エンドポイントは記載されているが、スキーマがない）	すべてのエンドポイントに完全なリクエスト／レスポンスのスキーマを追加します	提出前に Gate 5 を確認します
スコープクリープ（対象範囲内の項目が曖昧）	スコープの説明を明確にし、対象外の範囲を拡張します	「意図した範囲より多く含めてしまわないか？」テストを適用します

使用しない場合

• 目標が明確な小規模な変更が 1 つだけの場合 — 仕様策定パイプラインは省略し、直接実装します。まず作業を分類してください（bmad を参照）。
• パイプラインを取り巻く制御プレーンプロトコルが必要な場合 — 意図の所有者、作業の分類方法、自律性が安全なタイミング、レイヤー間での障害の振り分け方法には、意図の契約、作業分類、自律性のゲート設定、障害の振り分けに bmad を使用します。SDD は仕様の形式とゲートの仕組みを提供し、bmad は取り組み全体を実行するプロトコルを提供します。
• 問題自体が未検証の場合 — 未検討のアイデアに基づいて仕様を作成する前に、product-discovery に進んでください。

ツールに依存しない設計

このスキルが説明するのは方法論であり、特定のツールではありません。このパイプラインは次のツールで機能します。

• Claude Code — 仕様のコンテキストとして CLAUDE.md を使用し、計画後に実装するモードを使います
• Cursor — 仕様のコンテキストには Plan Mode と .cursorrules を、実装には Agent Mode を使用します
• Hermes Agent — ネイティブの SDD パイプライン（作成 → レビュー → 分解 → 検証）
• Devin / OpenHands — 仕様から導出したタスク計画に基づくタスク駆動型の実装
• GitHub Copilot Workspace — 仕様を構造化された Issue 本文として使用する、Issue 駆動型の方式
• droid (Factory) — 仕様の分解から作成するタスクカード

テンプレートは形式に依存しません（markdown）。引き継ぎの仕組み（CLAUDE.md、.cursorrules、AGENTS.md）は、使用するツールに合わせて調整してください。

実行可能なビジネスポリシー仕様

ビジネス条項を、繰り返し適用可能な適格性判定や振り分けの判断に変換する場合は、ビジネスポリシーのレシピを読み、リリース契約を使用してください。ポリシー所有者の権限、翻訳の忠実性を示す独立した証拠、明示的なレビュー経路を維持してください。このスキルのディレクトリから python3 scripts/business_policy.py --input evals/loan-request.json を実行すると、読み取り専用の合成デモを実行できます（Python 3.10 以降、標準ライブラリを使用）。契約テストを実行するには python3 -m pytest scripts/test_business_policy.py を実行してください（pytest が必要です）。決定論的に実行できても、生成された解釈が正しいことの証明にはなりません。

ビジネスルールについて、権威ある条項や所有者の承認を創作してはいけません。完全かつ有効な事実（false と zero の違いを含む）、所有者がレビューした優先順位、ソースから独立して導出したフィクスチャ、そして権威あるイベント日／スコープによって選択された適用可能な公開バージョンが正確に 1 つあることを必須としてください。呼び出し元が指定するバージョンによって、適用可能性の判定を迂回できてはいけません。事実が不足している場合や解釈が未確定の場合は、レビューに回してください。正の日数を求めるポリシーでは、ゼロを拒否する必要があります。実行の証拠がない場合、テストは未実行として報告してください。テストに合格しても、翻訳の正確性や 100％のコンプライアンスは保証されません。