Claude Code（Claude CLI）でのテストシナリオ構築

AI エージェントに任せた開発の品質を決めるのは、コード生成能力よりも「検証の仕組み」です。Claude Code（Claude CLI）でテストシナリオをどう組み立てるか、海外の公式・実践ブログの調査をもとに解説します。

本記事は、英語圏の公式ドキュメント・技術ブログを当社が調査し、要点を日本語でまとめたものです。各手法の出典は記事末尾の「参考元記事」に記載しています。詳細は必ず元記事をご確認ください。

核心は「Claude が自分で回せる検証ループ」

Anthropic 公式が最重要原則として挙げるのが「Claude に検証手段を与えること」です。検証とは「会話の中で Claude が読み取れる信号を返すもの全般 — テストスイート、ビルドの終了コード、リンター、出力を期待値と比較するスクリプト、デザインと比較するスクリーンショット」を指します。Claude は「作業し、チェックを実行し、結果を読み、合格するまで反復する」のです（元記事1）。

そのため、プロンプトには具体的なテストケースを含めるのが効果的です。たとえば「メール検証関数を実装して」ではなく、次のように書きます。

validateEmail 関数を書いて。テストケース例：user@example.com → true、invalid → false、user@.com → false。実装後にテストを実行して。

TDD は「明示的に強制」する

Claude は放っておくと実装を先に書きがちです。そこでRED → GREEN → REFACTOR の順序を明示的に指示します。Shipyard のブログは「機能を書く前にテストを書くプロセスが、より高品質な結果を生む」とし、E2E は Cypress や Playwright で書かせると述べています（元記事4）。

alexop.dev は、各フェーズをサブエージェントに分離し、「テスト失敗を確認するまで GREEN フェーズに進むな」といったブロッキング指示でステップ飛ばしを構造的に防ぐ「TDD スキル」を紹介しています。テスト作成エージェントは「実行時にテストが必ず失敗すること — 返す前に確認せよ」を義務付けられます（元記事5）。

ユニットテストだけでは足りない — E2E 検証

Anthropic のエンジニアリングブログは、見落としがちな失敗モードを明確に指摘しています。「Claude はコード変更を行い、ユニットテストや curl での確認までするが、機能がエンドツーエンドで動いていないことを認識できないことがあった」。

その解決策がブラウザ自動化ツールを与えること。エージェントが実ユーザーと同じようにアプリを操作してテストするようにしたところ、「コードだけからは分からないバグを特定・修正できるようになり、性能が劇的に向上した」と報告されています。各セッションの開始時には、開発サーバーを起動して初期ヘルスチェック（チャットを送って応答が返るか）を行い、壊れた状態を検知する工夫も紹介されています（元記事2）。

長時間の自律実行：状態ファイルと再試行上限

多数のシナリオを自律的に回す場合、状態ファイルでテストごとの結果を追跡します。Nathan Onn 氏の「Ralph Loop」では status.json に各テストケースの状態（pending / pass / fail / knownIssue）と修正試行回数を記録し、Claude の永続的な記憶として使います。ループは「テスト選択 → ブラウザで実行 → 合格なら次へ、失敗なら修正して再テスト」で進み、修正は最大3回まで、それを超えたら known_issue にすることで無限ループを防ぎます。完了は <promise>ALL_TESTS_RESOLVED</promise> のような明示シグナルでのみ宣言させます（元記事3）。

採点者と実装者を分ける

品質を高める定番が、「コードを書いたエージェントに自分の成果を採点させない」ことです。検証用サブエージェントや、フレッシュなコンテキストの別セッション（Writer/Reviewer パターン）に結果を反証させ、テストへの過剰適合を見抜きます。ただし公式は「ギャップを探せと指示されたレビュアーは、健全な成果に対しても何かしら報告しがち。正確性や要件に関わるギャップだけを挙げよと伝えること」と注意を促しています（元記事1）。

テストシナリオ構築のチェックリスト

• プロンプトに具体的なテストケース（入力と期待値）を含める
• TDD はRED の確認を必須化して明示的に強制する
• ユニットだけでなくブラウザ自動化で E2E 検証する
• テストの削除・改変を禁止するルールを置く
• 自律実行は状態ファイル＋再試行上限＋完了シグナルで制御
• 実装者と検証者を分離し、Hook で検証を確実に発火させる

実際の設定・使い方の例

ここまでのテスト戦略を、実際のファイルとコマンドに落とし込んだ例を示します。いずれも Claude Code の標準的な構成要素です。

1. settings.json でテストコマンドを許可する

.claude/settings.json の permissions でテスト実行を allow にしておくと、Claude が確認なしにテストを回して合否を読み取れます。破壊的コマンドは deny で塞ぎます。

{
  "permissions": {
    "allow": ["Bash(npm test:*)", "Bash(npm run lint:*)", "Bash(git*)"],
    "deny": ["Bash(rm -rf*)"]
  }
}

2. カスタムコマンドで RED-GREEN-REFACTOR を促す

.claude/commands/verify.md にプロンプトを書くと、/verify として呼び出せます。$ARGUMENTS で対象を渡せます。

次の対象を TDD で実装して: $ARGUMENTS

1. まず失敗するテストを書く（RED）
2. テストを実行し、本当に失敗することを確認する
3. テストが通る最小限の実装を書く（GREEN）
4. テスト出力を見せてから整理する（REFACTOR）
※ 既存のテストは削除・改変しないこと

3. PostToolUse フックで整形を自動化する

settings.json の hooks に整形コマンドを登録すると、ファイル編集のたびに決定論的に発火します。「助言」ではなく「強制」で品質を担保できます。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{ "type": "command", "command": "npm run format" }]
      }
    ]
  }
}

4. CI からヘッドレスで検証を回す

-p（--print）を付けると対話に入らず1回だけ実行するので、CI パイプラインからテストシナリオの実行を依頼できます。

claude -p "テストスイートを実行し、失敗があれば原因を要約して"