spec-driven-workflow

仕様駆動ワークフロー — 強力

概要

仕様駆動ワークフローでは、交渉の余地のない単一のルールを徹底します。コードを書く前に、必ず仕様を書くこと。 並行してではありません。後でもありません。先に書きます。

これはドキュメントではありません。これは契約です。仕様では、システムが必ず行うべきこと、行うことが推奨されること、そして明示的に行わないことを定義します。記述するすべてのコードは、仕様内の要件にたどり着ける必要があります。すべてのテストは、受け入れ基準にたどり着ける必要があります。仕様にないものは、実装しません。

仕様を先に書くことが重要な理由

1. 手戻りをなくします。 欠陥の60～80％は実装ではなく、要件に起因します。仕様の曖昧さを見つけるのにかかるのは数分ですが、本番環境で見つけると数日かかります。
2. 明確化を促します。 システムが何をすべきかを平易な言葉で書けないなら、コードを書くのに十分なほど問題を理解できていません。
3. 並行作業を可能にします。 仕様が承認されれば、フロントエンド、バックエンド、QA、ドキュメントの作業をすべて同時に開始できます。
4. 責任を明確にします。 仕様は完了の定義です。機能が「完成」しているかどうかを議論する必要はありません。受け入れ基準を満たすか、満たさないかのどちらかです。
5. TDDに直接つながります。 Given/When/Then形式の受け入れ基準は、1対1でテストケースに変換できます。仕様そのものがテスト計画です。

鉄則

NO CODE WITHOUT AN APPROVED SPEC.
NO EXCEPTIONS. NO "QUICK PROTOTYPES." NO "I'LL DOCUMENT IT LATER."

仕様が作成され、レビューされ、承認されるまでは、実装を開始しません。例外はありません。

---

仕様の形式

すべての仕様は、この構成に従います。省略できるセクションはありません。該当しない場合は、「N/A — [理由]」と記載し、レビュー担当者が検討漏れではなく、検討したうえでの判断だとわかるようにします。

必須セクション

#	セクション	主なルール
1	タイトルとメタデータ	作成者、日付、ステータス（Draft/In Review/Approved/Superseded）、レビュー担当者
2	背景	この機能が存在する理由。根拠（メトリクス、チケット）を含む2～4段落。
3	機能要件	RFC 2119のキーワード（MUST/SHOULD/MAY）。FR-Nの形式で番号を付けます。それぞれが独立しており、テスト可能であること。
4	非機能要件	パフォーマンス、セキュリティ、アクセシビリティ、スケーラビリティ、信頼性。すべて測定可能な閾値を設けます。
5	受け入れ基準	Given/When/Then形式。各ACは、少なくとも1つのFR-*またはNFR-*を参照します。
6	エッジケース	EC-Nの形式で番号を付けます。すべての外部依存関係について、障害時の動作を網羅します。
7	APIコントラクト	TypeScript形式のインターフェース。成功時とエラー時の応答を網羅します。
8	データモデル	フィールド、型、制約を含む表形式。要件に登場するすべてのエンティティにモデルを定義します。
9	対象範囲外	除外事項とその理由を明示します。実装中のスコープクリープを防ぎます。

RFC 2119のキーワード

キーワード	意味
MUST	絶対的な要件です。これを満たさなければ適合しません。
MUST NOT	絶対的な禁止事項です。
SHOULD	推奨事項です。省略する場合は、文書化した正当な理由が必要です。
MAY	任意です。実装者の裁量に委ねられます。

セクションごとの例、良い要件と悪い要件のパターン、機能タイプ別のテンプレート（CRUD、統合、移行）を含む完全なテンプレートについては、spec_format_guide.mdを参照してください。

認証、CRUD、検索、ファイルアップロード、支払い、通知、アクセシビリティのシナリオを網羅する、Given/When/Then形式の受け入れ基準のパターン集については、acceptance_criteria_patterns.mdを参照してください。

---

自律性の境界に関するルール

このルールでは、エージェント（人間またはAI）が、いつ作業を止めて指示を求めなければならないか、またいつ自律的に進めてよいかを定めます。

次の場合は停止して確認してください：

1. スコープクリープを検出した場合。 実装に仕様書に記載されていない内容が必要です。明らかに必要に思えても、停止してください。仕様書では意図的に除外されている可能性があります。

2. 曖昧さが30％を超える場合。 ある要件の30％を超える部分について、仕様書から正しい動作を判断できない場合、仕様書は不完全です。推測しないでください。

3. 破壊的変更が必要な場合。 実装によって既存の API コントラクト、データベーススキーマ、または公開インターフェースが変更されます。必ずエスカレーションしてください。

4. セキュリティへの影響がある場合。 認証、認可、暗号化、または PII の取り扱いに関わる変更には、明示的な承認が必要です。

5. パフォーマンス特性が不明な場合。 要件に「500ms 未満で完了しなければならない」とあるものの、それを測定または保証する方法がない場合は、推測で実装する前にエスカレーションしてください。

6. チーム間の依存関係がある場合。 仕様書で他のチームやサービスとの連携が必要な場合は、それを基盤に構築する前に依存関係を確認してください。

次の場合は自律的に続行してください：

1. 現在のタスクについて、仕様が明確で曖昧さがない。
2. すべての受け入れ基準をテストが満たしており、内部のリファクタリングを行っている。
3. 変更が非破壊的である。公開 API、スキーマ、動作に変更がない。
4. 実装が明確に定義された受け入れ基準をそのまま反映している。
5. エラー処理がコードベースですでに文書化されている確立されたパターンに従っている。

エスカレーション手順

停止が必要な場合は、次を提示してください：

## Escalation: [Brief Title]

**Blocked on:** [requirement ID, e.g., FR-3]
**Question:** [Specific, answerable question — not "what should I do?"]
**Options considered:**
  A. [Option] — Pros: [...] Cons: [...]
  B. [Option] — Pros: [...] Cons: [...]
**My recommendation:** [A or B, with reasoning]
**Impact of waiting:** [What is blocked until this is resolved?]

推奨事項なしにエスカレーションしてはいけません。自由回答形式の質問をしてはいけません。必ず選択肢を提示してください。

完全な判断マトリクスについては、references/bounded_autonomy_rules.md を参照してください。

---

ワークフロー — 6 フェーズ

フェーズ 1：要件の収集

目標： 何を、なぜ構築する必要があるのかを理解します。

1. ユーザーにヒアリングします。 次の質問をします：
   • どのような問題を解決しますか？
   • ユーザーは誰ですか？
   • 成功とはどのような状態ですか？
   • 明確に、何を構築すべきではありませんか？
2. 既存のコードを読みます。 変更を提案する前に、現在のシステムを理解します。
3. 制約を特定します。 パフォーマンス予算、セキュリティ要件、後方互換性を確認します。
4. 不明点を列挙します。 不明点はすべてリスクです。実装中ではなく、今のうちに明らかにします。

終了基準： プロジェクトに詳しくない人に、機能を2分で説明できます。

フェーズ 2：仕様書の作成

目標： 上記の「仕様書の形式」に従って、完全な仕様書を作成します。

1. テンプレートのすべてのセクションを埋めます。空欄のセクションを残してはいけません。
2. すべての要件に番号を付けます（FR-, NFR-, AC-, EC-, OS-*）。
3. RFC 2119 のキーワードを正確に使用します。
4. 受け入れ基準を Given/When/Then 形式で記述します。
5. TypeScript 形式の型を使って API コントラクトを定義します。
6. 対象範囲外に、明示的な除外項目を列挙します。

終了基準： 要件定義の会議に参加していない開発者に仕様書を渡しても、確認の質問をせずに機能を実装できます。

フェーズ 3：仕様書の検証

目標： 仕様書が完全で、一貫性があり、実装可能であることを確認します。

仕様書ファイルに対して spec_validator.py を実行します：

python spec_validator.py --file spec.md --strict

手動検証チェックリスト：

• すべての機能要件に、少なくとも1つの受け入れ基準がある
• すべての受け入れ基準がテスト可能である（主観的な表現がない）
• API コントラクトが、要件で言及されているすべてのエンドポイントを網羅している
• データモデルが、要件で言及されているすべてのエンティティを網羅している
• エッジケースが、すべての外部依存関係について障害モードを網羅している
• 対象範囲外の項目に、検討して却下した内容が明示されている
• 非機能要件に、測定可能な基準値がある

終了基準： 仕様書のバリデーター評価が80以上で、手動チェックリストの項目がすべて合格しています。

フェーズ 4：テストを生成する

目標： 実装コードを書く前に、受け入れ基準からテストケースを抽出します。

承認済みの仕様に対して test_extractor.py を実行します。

python test_extractor.py --file spec.md --framework pytest --output tests/

1. 各受け入れ基準から、1つ以上のテストケースを作成します。
2. 各エッジケースから、テストケースを作成します。
3. テストはスタブです。アサーションは定義しますが、実装は定義しません。
4. すべてのテストは最初に失敗しなければなりません（TDD のレッドフェーズ）。

終了基準： すべてのテストが「not implemented」または同等のエラーで失敗するテストファイルがあること。

フェーズ 5：実装する

目標： 受け入れ基準を1つずつ満たし、失敗しているテストを成功させるコードを書きます。

1. 受け入れ基準を1つ選びます（最も簡単なものから始めます）。
2. 最小限のコードで、その基準のテストを成功させます。
3. テストスイート全体を実行し、リグレッションがないことを確認します。
4. コミットします。
5. 次の受け入れ基準を選び、繰り返します。

ルール：

• 仕様にないものは実装しないでください。
• すべての受け入れ基準を満たす前に最適化しないでください。
• すべての受け入れ基準を満たす前にリファクタリングしないでください。
• 要件の不足に気づいた場合は、作業を停止し、まず仕様を更新してください。

終了基準： すべてのテストが成功し、すべての受け入れ基準を満たしていること。

フェーズ 6：自己レビュー

目標： 完了とする前に、実装が仕様に一致していることを確認します。

以下の自己レビューのチェックリストを確認してください。項目に1つでも不備があれば、タスクの完了を宣言する前に修正してください。

---

自己レビューのチェックリスト

実装を完了とする前に、以下のすべてを確認してください。

• すべての受け入れ基準に、それを満たすテストがある。 例外はありません。AC-3 がある場合、AC-3 のテストがあり、成功することを確認してください。
• すべてのエッジケースにテストがある。 EC-1 から EC-N まで、すべてに対応するテストケースがあることを確認してください。
• スコープが逸脱していない。 実装に、仕様にない機能が含まれていないことを確認してください。何かを追加した場合は、仕様を更新するか、その追加を削除してください。
• API コントラクトと実装が一致している。 コードのリクエスト／レスポンスの形式が、仕様と完全に一致していることを確認してください。フィールド名、型、ステータスコードなど、すべてが対象です。
• エラーシナリオがテストされている。 仕様で定義されたすべてのエラーレスポンスを発生させるテストがあることを確認してください。
• 非機能要件が検証されている。 仕様に < 500ms とある場合、しきい値を満たすことを示す根拠（ベンチマーク、負荷テスト、プロファイリング）があることを確認してください。
• データモデルが一致している。 データベーススキーマが仕様と一致していることを確認してください。余分なカラムや、欠けている制約がないことも確認してください。
• スコープ外の項目が実装されていない。 「スコープ外」セクションの内容が実装に紛れ込んでいないか、もう一度確認してください。

---

TDD ガイドとの連携

仕様駆動ワークフローと TDD は、対立するものではなく、相互に補完するものです。

Spec-Driven Workflow          TDD (Red-Green-Refactor)
─────────────────────         ──────────────────────────
Phase 1: Gather Requirements
Phase 2: Write Spec
Phase 3: Validate Spec
Phase 4: Generate Tests  ──→  RED: Tests exist and fail
Phase 5: Implement       ──→  GREEN: Minimal code to pass
Phase 6: Self-Review     ──→  REFACTOR: Clean up internals

引き継ぎ： 仕様駆動ワークフローは、テストスタブを生成します（フェーズ 4）。そこから TDD に引き継ぎます。仕様は何をテストするかを示し、TDD はどのように実装するかを示します。

以下には engineering-team/tdd-guide を使用します。

• レッド・グリーン・リファクターサイクルの規律
• カバレッジ分析と不足箇所の検出
• フレームワーク固有のテストパターン（Jest、Pytest、JUnit）

以下には engineering/spec-driven-workflow を使用します。

• 構築を始める前に、何を構築するかを定義する
• 受け入れ基準を作成する
• 完全性を検証する
• スコープを管理する

---

例

テストケースを抽出した完全な例（パスワードリセットの仕様）は、spec_format_guide.md にあります。9つのセクションすべて、要件の番号付け、受け入れ基準、エッジケース、および test_extractor.py が生成する対応する pytest スタブを示しています。

---

アンチパターン

1. 仕様の承認前にコーディングする

症状： 「仕様をレビューしている間にコーディングを始めます。」 問題： レビューで変更が見つかります。その時点で、却下された設計を実装したコードができてしまいます。 ルール： 仕様のステータスが「承認済み」になるまで、実装を開始してはいけません。

2. 曖昧な受け入れ基準

症状：「システムは適切に動作すること」または「UI は応答性が高いこと」。 **問題：**テストできません。「適切」とはどういう意味でしょうか。「応答性が高い」とはどういう意味でしょうか。 **ルール：**すべての受け入れ基準は、機械で検証可能でなければなりません。テストを書けない場合は、その基準を書き直してください。

3. エッジケースの不足

**症状：**正常系は指定されていますが、エラー時の動作は指定されていません。 **問題：**開発者がその場でエラー処理を考えることになり、動作に一貫性がなくなります。 **ルール：**外部依存関係（API、データベース、ファイルシステム、ユーザー入力）ごとに、少なくとも 1 つの失敗シナリオを指定してください。

4. 事後ドキュメントとしての仕様書

症状：「機能が完成したので、今から仕様書を書きましょう」。 **問題：**これは仕様書ではなく、ドキュメントです。何を構築すべきだったかではなく、何が構築されたかを説明しています。設計がすでに確定しているため、設計上の誤りを防ぐことはできません。 **ルール：**コードを書いた後に作成した仕様書は、仕様書ではありません。ドキュメントとして再分類してください。

5. 仕様を超えた過剰な作り込み

症状：「作業中に、ついでにこれも追加しました……」。 **問題：**テストされていないコードです。レビューされていない設計です。「おまけ」機能に潜在的なバグが入り込む可能性があります。 **ルール：**仕様にないものは、構築しません。追加機能には、新しい仕様書を作成してください。

6. 要件トレーサビリティのない受け入れ基準

**症状：AC-7 が存在するものの、FR- または NFR- を参照していません。 **問題：**孤立した基準は、要件が不足しているか、その基準が不要であることを意味します。 *ルール：すべての AC- は、少なくとも 1 つの FR- または NFR- を参照しなければなりません。

7. 検証の省略

症状：「仕様書に問題はなさそうなので、そのまま始めましょう」。 **問題：**実装中にセクションの不足が判明すると、作業が大幅に遅れます。 **ルール：**実装を始める前に、必ず spec_validator.py --strict を実行してください。すべての警告を修正してください。

---

相互参照

• engineering-team/tdd-guide — レッド・グリーン・リファクタリングのサイクル、テスト生成、カバレッジ分析。このワークフローのフェーズ 4 の後に使用してください。
• engineering/focused-fix — 機能の詳細な修正。仕様駆動型の実装にシステム上の問題がある場合は、診断に focused-fix を使用してください。
• engineering/rag-architect — 機能に検索またはナレッジシステムが関係する場合は、仕様内の技術設計に rag-architect を使用してください。
• references/spec_format_guide.md — セクションごとの解説を含む完全なテンプレート。
• references/bounded_autonomy_rules.md — 続行するか停止するかを判断するための完全な決定マトリックス。
• references/acceptance_criteria_patterns.md — Given／When／Then 形式の基準を作成するためのパターンライブラリ。

---

ツール

スクリプト	用途	主なフラグ
spec_generator.py	機能名／説明から仕様書のテンプレートを生成	--name、--description、--format、--json
spec_validator.py	仕様書の完全性を検証（0～100 点）	--file、--strict、--json
test_extractor.py	受け入れ基準からテストのスタブを抽出	--file、--framework、--output、--json

# Generate a spec template
python spec_generator.py --name "User Authentication" --description "OAuth 2.0 login flow"

# Validate a spec
python spec_validator.py --file specs/auth.md --strict

# Extract test cases
python test_extractor.py --file specs/auth.md --framework pytest --output tests/test_auth.py