Claude Code

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）。

RED-GREEN-REFACTOR の流れ： ①失敗するテストを先に書く → ②本当に失敗することを確認（RED）→ ③コミット → ④テストが通る最小限の実装（GREEN）→ ⑤整理（REFACTOR）。テストは「セッションが長引いても正確であり続ける外部の判定基準」として機能します（元記事1・4・5）。

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

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

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

重要な禁則： 同ブログは「テストを削除・編集してはならない。機能の欠落やバグの見逃しにつながるため」と明言しています。Claude が「テストを消して緑にする」ことを防ぐルールは、テストシナリオ運用の必須事項です（元記事2）。

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

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

採点者と実装者を分ける

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

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

当社の視点： ハシトシステムでは、テストシナリオを「AI に任せる前提の仕様書」と捉えています。期待値が明確で、機械的に合否を返せるシナリオを先に用意することが、AI 活用開発の生産性と品質を同時に引き上げる鍵になります。テスト戦略の設計からご相談いただけます。

よくある質問（FAQ）

Claude Code でテストシナリオを組むうえで最も重要なことは？

Anthropic 公式が最重要原則として挙げるのは「Claude に検証手段を与えること」です。検証とは、テストスイート、ビルドの終了コード、リンター、出力を期待値と比較するスクリプト、デザインと比較するスクリーンショットなど、会話の中で Claude が読み取れる信号全般を指します。Claude は作業し、チェックを実行し、結果を読み、合格するまで反復します。そのためプロンプトには入力と期待値を伴う具体的なテストケースを含めるのが効果的です。

Claude Code に TDD をきちんと守らせるには？

Claude は放っておくと実装を先に書きがちなので、RED → GREEN → REFACTOR の順序を明示的に指示します。失敗するテストを先に書き、本当に失敗することを確認（RED）してからコミットし、テストが通る最小限の実装（GREEN）を行い、整理（REFACTOR）します。各フェーズをサブエージェントに分離し、テスト失敗を確認するまで GREEN に進むなといったブロッキング指示でステップ飛ばしを構造的に防ぐ手法も有効です。

ユニットテストだけでは不十分なのですか？

不十分なことがあります。Claude はコード変更やユニットテスト、curl での確認まで行っても、機能がエンドツーエンドで動いていないことを認識できない場合があります。そこでブラウザ自動化ツールを与え、実ユーザーと同じようにアプリを操作してテストさせると、コードだけからは分からないバグを特定・修正でき性能が向上します。なお、テストを削除・編集してはならない（機能の欠落やバグの見逃しにつながる）という禁則も重要です。

参考元記事

  1. Anthropic「Best practices for Claude Code」(公式ドキュメント) — https://code.claude.com/docs/en/best-practices
  2. Justin Young / Anthropic「Effective harnesses for long-running agents」(2025年11月26日) — https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents
  3. Nathan Onn「How to Make Claude Code Test and Fix Its Own Work (The Ralph Loop Method)」(2026年2月13日) — https://www.nathanonn.com/claude-code-testing-ralph-loop-verification/
  4. Natalie Lunbeck / Shipyard「E2E Testing with Claude Code」(2025年7月3日) — https://shipyard.build/blog/e2e-testing-claude-code/
  5. Alexander Opalic「A Claude Code TDD Skill: Forcing Red-Green-Refactor Discipline」(2025年11月30日) — https://alexop.dev/posts/custom-tdd-workflow-claude-code-vue/
  6. Claude Fast「Claude Code Workflow: Create Tight Feedback Loops」 — https://claudefa.st/blog/guide/development/feedback-loops
← 技術ブログ一覧へ戻る