cavekit-validation-first

検証優先の設計

核心となる原則：エージェントが検証できないものは、達成されません

すべての仕様要件には、エージェントが自動的に検証できるテスト可能な受け入れ基準を含める必要があります。これは任意ではありません。SDD を機能させる基盤です。

なぜでしょうか？ AI エージェントの動作は非決定的です。自動検証がなければ、エージェントの出力が正しいかどうかを判断する方法がありません。検証ゲートを設けることで、「エージェントがコードを生成した」という状態から、「仕様を満たしていることを証明できるコードをエージェントが生成した」という状態にできます。

検証優先のルールは、あらゆる段階に適用されます。

• 仕様要件にはテスト可能な受け入れ基準が必要です
• 計画では各タスクをどのゲートで検証するかを定義する必要があります
• 実装は、完了とみなされる前に適用対象のすべてのゲートを通過する必要があります
• イテレーションでは、ゲートを通じて測定可能な進捗を示す必要があります

---

検証ゲートの順序

すべての実装は、順番に並んだ6つのチェックポイントを通過する必要があります。後のゲートほど実行コストが高いため、早い段階で失敗を見つければ、大幅に時間を節約できます。

ゲート1：コンパイルチェック

内容： プロジェクトがエラーなくコンパイル／トランスパイルできること。

# Generic pattern — substitute your project's build command
{BUILD_COMMAND}

重要な理由： コードをビルドできなければ、ほかの検証はできません。これは最も低コストのチェックです。

検出できる問題：

• 構文エラー
• インポート／依存関係の不足
• 型エラー（型付き言語の場合）
• 設定エラー

受け入れ基準のパターン：

- [ ] `{BUILD_COMMAND}` completes with exit code 0
- [ ] No warnings related to {domain} (warnings in other domains are acceptable)

ゲート2：分離された単体検証

内容： 変更したすべてのファイルについて、単体テストが成功すること。

# Generic pattern
{TEST_COMMAND}

# Or targeted at changed files
{TEST_COMMAND} --filter {changed-files}

重要な理由： 単体テストは、個々の関数やモジュールを分離して検証します。実行が速く、決定的で、ロジックエラーを検出できます。

検出できる問題：

• 関数の動作の誤り
• 処理されていないエッジケース
• 既存コードへの変更によるリグレッション
• 契約違反（戻り値の型の誤り、フィールドの欠落）

受け入れ基準のパターン：

- [ ] All existing unit tests pass
- [ ] New unit tests cover all acceptance criteria for R{N}
- [ ] No test relies on external services or network access

ゲート3：コンポーネント間の統合

内容： エンドツーエンドテストと統合テストで、コンポーネントが連携して動作することを検証します。

# Generic pattern
{TEST_COMMAND} --e2e

# Or with a specific test runner
{E2E_TEST_COMMAND}

重要な理由： 単体テストはコンポーネントを分離して検証します。統合テストは、それらが連携して動作することを検証します。多くのバグは統合境界でのみ発生します。

検出できる問題：

• コンポーネント間の API 契約の不一致
• モジュール境界をまたぐデータフローのエラー
• 認証／認可の統合に関する問題
• 実際の（または現実的な）データを使ったデータベースクエリのエラー

受け入れ基準のパターン：

- [ ] User can complete {workflow} end-to-end
- [ ] API endpoint returns correct response for {scenario}
- [ ] Error propagation works correctly from {source} to {destination}

ゲート4：リソースと速度のベンチマーク

内容： パフォーマンスベンチマークが定義されたしきい値を満たすこと。

# Generic pattern
{BENCHMARK_COMMAND}

# Or specific checks
{TEST_COMMAND} --performance

重要な理由： 機能的な正しさは必要ですが、それだけでは不十分です。正しい出力を生成できても、パフォーマンスのリグレッションによって機能が使いものにならなくなる場合があります。

検出できる問題：

• 応答時間のリグレッション
• メモリリークや過剰なメモリ割り当て
• メインスレッドをブロックする、CPU 負荷の高い処理
• データベースクエリのパフォーマンス低下

受け入れ基準のパターン：

- [ ] API response time < {N}ms at p95 under {M} concurrent users
- [ ] Page load time < {N}s on simulated 3G connection
- [ ] Memory usage does not exceed {N}MB during {operation}
- [ ] No operation blocks the main thread for > {N}ms

注： すべてのタスクにパフォーマンスゲートが必要なわけではありません。次の場合にゲート4を適用してください。

• 仕様でパフォーマンス要件が明示されている
• 変更が既知のホットパスに関わる
• 大規模なデータ処理を伴う機能である

ゲート5：起動スモークテスト

内容： アプリケーションが正常に起動し、基本的なスモークテストが成功すること。

# Generic pattern — start the application
{START_COMMAND}

# Verify it is running
curl -f http://localhost:{PORT}/health

# Or run smoke tests
{SMOKE_TEST_COMMAND}

重要な理由： コードはビルドでき、すべてのテストに合格していても、起動に失敗することがあります。起動の検証により、設定の問題、環境変数の不足、ポートの競合、起動時の競合状態を検出できます。

検出できる問題：

• 環境変数または設定の不足
• ポートの競合やバインドエラー
• 起動時の初期化失敗
• 実行時依存関係の不足
• データベースのマイグレーションに関する問題

受け入れ基準のパターン：

- [ ] Application starts with `{START_COMMAND}` and responds to health check
- [ ] Main screen/page renders without errors
- [ ] No error-level entries in application logs during startup
- [ ] Application shuts down gracefully on interrupt signal

ゲート 6：手動監査

内容： 人間が出力をレビューし、品質、設計意図、自動化が難しい要件を確認します。

重要な理由： 自動化できないこともあります。UX の品質、アーキテクチャの洗練度、命名の一貫性、ドキュメントの明確さなどです。ゲート 6 では、人間が最終的な品質フィルターとして機能します。

検出できる問題：

• 主観的な品質の問題
• 技術的には正しいものの、戦略的には誤っているアーキテクチャ上の決定
• 過剰なエンジニアリング、または不十分なエンジニアリング
• 自動化ツールが見逃すセキュリティ上の懸念
• 技術的には満たしていても、仕様の意図に沿っていない要件

実際の動作：

1. エージェントがゲート 1～5 を完了し、結果を報告します
2. 人間が仕様の意図に照らして実装をレビューします
3. 人間が課題または仕様の更新としてフィードバックを提供します
4. フィードバックにコードの変更が必要な場合、修正ループに入ります：
   • 不足していた要件を仕様に追加します
   • イテレーションループを再実行します
   • 更新された仕様から修正が反映されることを確認します

受け入れ基準のパターン：

- [ ] Implementation reviewed by human for spec intent alignment
- [ ] No architectural concerns raised
- [ ] Code style consistent with project conventions

---

ゲートの概要表

ゲート	目的	コマンドのパターン	標準的な所要時間	自動化
1. コンパイル	コードが問題なくコンパイルされる	{BUILD_COMMAND}	数秒	はい
2. 単体検証	個々の関数が正しく動作する	{TEST_COMMAND}	数秒～数分	はい
3. 統合	モジュールが想定どおりに連携する	{E2E_TEST_COMMAND}	数分	はい
4. ベンチマーク	速度とリソース使用量が予算内に収まる	{BENCHMARK_COMMAND}	数分	はい
5. スモークテスト	アプリケーションが起動し、応答する	{START_COMMAND} + ヘルスチェック	数秒	はい
6. 手動監査	設計意図と品質基準を満たす	人間による確認	可変	いいえ

詳細な例を含む検証ゲートの全リファレンスについては、references/validation-gates.md を参照してください。

---

仕様要件とゲートの対応付け

すべての仕様要件は、少なくとも 1 つの検証ゲートに対応付ける必要があります。仕様を作成する際（ck:cavekit-writing を参照）、各受け入れ基準には、どのゲートで検証するかを示してください。

対応付けのパターン

### R1: User Authentication
**Acceptance Criteria:**
- [ ] Valid credentials return session token — **Gate 2** (unit test)
- [ ] Invalid credentials return 401 error — **Gate 2** (unit test)
- [ ] Session token grants access to protected endpoints — **Gate 3** (integration)
- [ ] Login page renders within 2s — **Gate 4** (performance)
- [ ] Application starts with auth module loaded — **Gate 5** (launch)

対応付けのない要件は検証されない

要件をどのゲートにも対応付けられない場合、次のいずれかの問題があります：

1. 要件が曖昧すぎる — 具体的でテスト可能な基準を使って書き直します
2. 検証インフラが不足している — ゲートを追加します（例：E2E テストがない場合、ゲート 3 はまだ存在しません）

いずれの場合も、対応付けのない要件がエージェントによって確実に満たされることはありません。

---

Hunt フェーズ間のフェーズゲート

フェーズゲートは、Hunt の各フェーズ間に必ず設ける検証チェックポイントです。次のフェーズが前のフェーズの出力を基に進む前に、その出力が確かなものであることを確認します。

フェーズゲートの定義

遷移	ゲート条件	確認方法
Spec → Plan	すべてのドメインに、テスト可能な受け入れ基準を含む仕様がある	cavekit-overview.md を確認します。すべての R{N} に AC 項目があること
Plan → Implement	計画が仕様を参照し、順序を定義し、テスト戦略を含んでいる	計画ファイルを確認します。すべてのタスクが仕様要件に対応していること
Implement → Iterate	コードがビルドでき（ゲート 1）、テストが合格し（ゲート 2）、実装の追跡情報が最新である	{BUILD_COMMAND} と {TEST_COMMAND} を実行し、実装の追跡情報を確認します
Iterate → Monitor	収束を検出：イテレーションを重ねるごとに変更が減少している	直近 3～5 回のイテレーション間で差分を比較します
Monitor → Spec	ギャップが見つかった、または新しい要件が特定された	ギャップ分析で、未達成の受け入れ基準を特定します

フェーズゲートの適用

フェーズゲートはイテレーションループによって適用されます。プロンプトにフェーズゲートのチェックが含まれている場合、エージェントは次の処理を行います：

1. フェーズの終了時にゲートチェックを実行します
2. 合格／不合格のステータスを報告します
3. ゲートが不合格の場合、エージェントは次のフェーズに進みません
4. 代わりに、ゲートに合格するまで現在のフェーズを繰り返します

例：Implement → Iterate ゲート

## Exit Criteria (Phase Gate)
Before reporting completion:
- [ ] `{BUILD_COMMAND}` succeeds with exit code 0
- [ ] `{TEST_COMMAND}` passes with no new failures
- [ ] All files created/modified are listed in impl tracking
- [ ] All dead ends encountered are documented
- [ ] Test health table is updated with current counts

---

マージプロトコル

エージェントチーム（Agent ツールを使って isolation: "worktree" で複数のエージェントをディスパッチする場合）で作業するときは、マージプロトコルに従うことで、異なるエージェントの作業を統合する際に検証ゲートが壊れるのを防ぎます。

プロトコル

Agent A completes work in its isolated branch
Agent B completes work in its isolated branch
Agent C completes work in its isolated branch

Merge sequence (one at a time):
1. Merge Agent A's branch → main
2. Run: {BUILD_COMMAND} → must pass
3. Run: {TEST_COMMAND} → must pass
4. Run: Launch verification → must pass
5. If all pass → proceed
6. If any fail → fix before merging next branch

7. Merge Agent B's branch → main
8. Run: {BUILD_COMMAND} → must pass
9. Run: {TEST_COMMAND} → must pass
10. ...repeat for each agent branch

なぜ一度に1つずつマージするのですか？

すべてのエージェントブランチを同時にマージしてからテストを実行すると、どのマージが失敗の原因なのか特定できません。1つずつマージし、その都度検証することで、失敗の原因をすぐに特定できます。

マージプロトコルのルール

1. エージェントブランチは一度に1つだけマージします — 一括マージはしないでください
2. マージのたびにゲート1～3を実行します — ビルド、ユニットテスト、統合テスト
3. すべてのマージ後にゲート5を実行します — 統合済みコードベースで起動検証を行います
4. マージのたびにクリーンアップします：ワークツリーを削除し（git worktree remove <path>）、その後ブランチを削除します（git branch -D <branch>）。エージェントが変更を加えなかった場合、Claude Code はワークツリーを自動でクリーンアップします。変更がコミットされている場合は、呼び出し元がブランチを削除する前にワークツリーを削除する必要があります。
5. マージが検証に失敗した場合は、 次のマージに進む前に修正します

---

完了シグナル

完了シグナルとは、タスクまたはフェーズのすべての終了条件を満たしたときにエージェントが出力する特定の文字列です。これにより、自動化処理でエージェントの完了を検出できます。

完了シグナルの仕組み

1. プロンプトでシグナルを定義します：

   When ALL exit criteria are met, output exactly:
   <all-tasks-complete>
   

2. エージェントはすべての終了条件を確認した後、シグナルを出力します

3. 反復ループはシグナルを検出して、反復を停止します

完了シグナルのルール

• シグナルは、通常の出力には現れない一意の文字列でなければなりません
• エージェントはシグナルを出力する前に、すべての終了条件を確認しなければなりません
• シグナルは、セッションでエージェントが出力する最後の内容にする必要があります
• エージェントがすべての条件を満たせない場合、シグナルを出力せず、完了を妨げている要因を記録してください

完了シグナルを含むプロンプトの例

## Exit Criteria
Complete all of the following before emitting the completion signal:
- [ ] All T- tasks are DONE or BLOCKED with documented blockers
- [ ] `{BUILD_COMMAND}` succeeds
- [ ] `{TEST_COMMAND}` passes with no new failures
- [ ] Implementation tracking is updated
- [ ] All dead ends are documented

When ALL criteria above are met, output:
<all-tasks-complete>

If you cannot meet all criteria, document what is blocking
and do NOT output the completion signal.

---

検証優先の設計パターン

パターン1：実装前にテストする

機能を実装する前に、テストを作成または生成します。テストによって「正しい」とはどういうことかを定義します。

1. Read spec requirement R{N} acceptance criteria
2. Generate test cases that verify each criterion
3. Run tests → all fail (RED)
4. Implement the feature
5. Run tests → all pass (GREEN)
6. Refactor if needed

これは、SDD 内での TDD です。既存の TDD スキルについては、superpowers:test-driven-development を参照してください。

パターン2：ゲートの段階的実行

ゲートは順番に実行します。先行するゲートが失敗した場合、後続のゲートは実行しません。

Gate 1 (Build) → FAIL → fix build errors → retry Gate 1
Gate 1 (Build) → PASS → Gate 2 (Unit Tests)
Gate 2 (Tests) → FAIL → fix failing tests → retry Gate 2
Gate 2 (Tests) → PASS → Gate 3 (Integration)
...

先行するゲートほどコストが低くなります。ビルドエラーの修正には数秒かかりますが、統合エラーの修正には数分かかります。まずはコストの低い問題から修正してください。

パターン3：ゲートの段階的な深度

すべての反復で、すべてのゲートを実行する必要はありません。フェーズに応じて段階的に深度を高めます。

フェーズ	必須ゲート	オプションのゲート
初期実装	1（ビルド）、2（ユニット）	—
中期実装	1、2、3（統合）	4（パフォーマンス）
後期実装	1、2、3、5（起動）	4
リリース前	1～6すべて	—

パターン4：リグレッションの防止

以前は通過していたゲートが失敗するようになった場合、P0 の問題として扱います。

1. 作業を中断します — 新しい機能を実装しないでください
2. リグレッションを特定します — どの変更が失敗の原因になったのでしょうか？
3. リグレッションを修正します — 通過していた状態に戻します
4. テストを追加します — そのリグレッションが再発しないようにします
5. 上流へ反映します — リグレッションによって仕様の不足が明らかになった場合は、仕様を更新します

---

他のスキルとの連携

superpowers:verification-before-completion との連携

既存の verification-before-completion スキルは、作業を完了とする前に検証するための汎用的なフレームワークを提供します。検証優先の設計では、これを SDD で使用する6つのゲートからなるパイプラインと、フェーズごとのゲートシステムで拡張します。

連携方法：

• superpowers:verification-before-completion は、エージェントが自分の作業を確認するようにします
• ck:validation-first は、実行するチェックとその順序を具体的に定義します

ck:cavekit-writing を使用する場合

すべての仕様要件には、検証ゲートに対応する受け入れ基準が必要です。仕様作成スキルは、それらの基準をどのように記述するかを定義します。検証ファースト設計は、それらをどのように検証するかを定義します。

ck:impl-tracking を使用する場合

検証結果は、実装トラッキングドキュメントの Test Health テーブルに記録されます。ゲートの失敗は Issues になります。ゲート関連の行き詰まりは Dead Ends セクションに記録されます。

ck:methodology を使用する場合

検証ゲートは、すべての Hunt フェーズにわたって継続的に機能します。フェーズゲートはフェーズ間の移行を制御します。イテレーションループは、ゲートの結果を収束シグナルとして使用します。

---

まとめ

1. エージェントが検証できないものは、満たされることはない — すべての要件には自動検証が必要です
2. 6 つのゲートを順番に: コンパイル → 単体検証 → 統合 → ベンチマーク → スモークテスト → 手動監査
3. 早い段階のゲートほどコストが低い — 問題はローンチ時ではなく、ビルド段階で捉えましょう
4. すべての仕様要件は少なくとも 1 つのゲートに対応する — 対応付けられていない要件は検証されません
5. フェーズゲートは Hunt の移行を制御する — 現在のフェーズがゲートを通過するまで先に進まないでください
6. マージは一度に 1 つずつ — 各マージの間に検証して、失敗箇所を特定しましょう
7. 完了シグナルが自動化を可能にする — すべてのゲートが通過したとき、エージェントは特定の文字列を出力します
8. リグレッションは P0 — 通過していたゲートが失敗し始めたら、先に進む前に停止して修正してください