Claude Code 検証ループとは？「できました」を信じない仕組みの作り方

Claude Codeの検証ループとは何か

公式ブログ「Building verification loops in Claude Code with skills」（2026年7月22日）は、検証ループをこう定義している。

A repeating cycle where an AI agent checks its own work — running tests, linters, or custom checks — and fixes what fails before moving on.

文脈収集 → 行動 → 結果の検証、この3段階を繰り返すことで、Claudeは失敗を自分で検出して修正してから次へ進む。公式Best Practicesの「Give Claude a way to verify its work」セクションにも同じ思想が書かれている。

Claude stops when the work looks done. Without a check it can run, “looks done” is the only signal available, and you become the verification loop: every mistake waits for you to notice it.

検証の仕組みがなければ、確認係はあなた自身になる。Claude Codeの検証ループとは、その確認作業をClaudeのループ内に閉じ込め、パス／フェイルの信号が出るまでClaudeが自分で回し続ける構造のことだ。

「チェック」として使えるものは何か。公式は次を列挙している。

• テストスイート（ユニット・統合）
• ビルドの終了コード
• リンター
• 出力をフィクスチャと比較するスクリプト
• デザインと比較するブラウザのスクリーンショット

共通点は「会話内でClaudeが読める、パス／フェイルの信号を返すもの」であること。テストが通った、ビルドが成功した、スクリーンショットの差分がゼロだった――それが証拠になる。

変更内容を人がレビューする前に確かめたいときは、Claude Codeのレビュー系コマンドで解説しています。

関連記事Claude Codeが動かないときは？

なぜ必要か：「できました」は「見た目が完了した」でしかない

公式Best Practicesはこの問題を「trust-then-verify gap」と呼ぶ。もっともらしい実装がエッジケースを扱っていない、という典型的な落とし穴だ。公式の勧告は明快だ。

Always provide verification (tests, scripts, screenshots). If you can’t verify it, don’t ship it.

実際の開発でも、この落とし穴には繰り返しはまりやすい。具体的な場面を2つ挙げる。

1つ目はアバター映像の開発だ。Claudeは静止画を送る切り離したテストで「直った」と報告し続けた。しかし実際の画面では映像が毎フレーム変わる実環境であり、そこでは別の挙動が出て直っていなかった。都合のよい代替テストで完了を宣言する構造が問題だった。

2つ目はWebサイト運用だ。Claudeが「3件反映しました」と報告したにもかかわらず、実際には反映されていなかった。状態を変える操作（ファイル・DBへの書き込み）で、実行後に読み戻して確認するステップが抜けていた。

どちらも根は同じだ。Claudeは作業した経路から見えるものしか確認しない。実際のユーザーが踏む経路で確認しなければ、「できた」は単に「自分から見て完了に見えた」を意味するに過ぎない。

対策として、Claude Codeが毎回読むプロジェクト指示ファイル（CLAUDE.md）に次の4つを明文化しておく。

1. 「できた」「直った」と報告する前に、ユーザーが実際に使う経路で本物の結果を自分で確認する（切り離したテストや都合のよい代替で済ませない）。
2. 検証をユーザーに丸投げせず、証拠（実出力の画像・数値）を添えて報告する。
3. 一つ直したら関連する全ケースを毎回検証する。
4. 検証方法が誤りと分かったら、二度と使わない。

加えて、状態を変える操作には「実行 → 読み戻し → 確認」のセットを必須にしている。ファイル編集の直前に自動でバックアップを取るPreToolUseフックも運用しており、誤った操作を安全に巻き戻せる体制を整えている。

検証ループは「Claudeに確認させる仕組み」ではなく、「確認が完了するまでClaudeが先へ進めない仕組み」だ。その区別が、連続する「もぐら叩き」を終わらせる鍵になる。

関連: Claude Codeとは？できること・使い方 / Claude Codeの使い方

検証の強さは4段階：プロンプト・/goal・Stop hook・サブエージェント

公式Best Practicesは、検証をどこに組み込むかによって強さが変わると説明する。強さの順に4段階あり、それぞれ適切な用途がある（2026年9月時点）。

段階	仕組み	特性	向いている場面
① プロンプト内	タスク指示の中にチェック実行と反復を依頼する	即時・軽量。どのタスクでも今日から使える	1回限りの作業・試験的な確認
② /goal 条件	セッション全体のゴール条件に設定。別の評価器が毎ターン後に再確認し、ゴールが解決するまでClaudeが作業を続ける	セッション横断で持続する。停滞すると最終的に停止する	複数ステップにまたがる修正・リファクタリング
③ Stop hook	スクリプトでチェックを実行し、通るまでターン終了をブロックする決定論的ゲート（連続ブロックの上限あり）	確実性が高い。CLAUDE.md指示がアドバイザリなのに対し、フックは決定論的に動作する	CI的な品質ゲート・無人実行
④ 検証サブエージェント	作業した本人でない新しいモデルが結果の反証を試みる（敵対的レビュー）	作業者バイアスがない。バンドルの /code-review スキルで差分を新しいサブエージェントがレビュー	PRレビュー・品質の二重確認

公式はプロンプト版と無人実行版の違いをこう位置づける。

The prompt version works on any task today. The /goal and Stop hook versions are what let an unattended run finish correctly without you.

段階を上げるほど確実性は高まるが、費用と複雑さも上がる。特に、サブエージェントを大量に使うバッチ処理で高額モデルを継承させると、費用が想定を超えやすい。大規模な連鎖を組む前に、件数とコストを見積もるステップを入れることを強く勧める。

また公式は敵対的レビューについてこう注意している。

A reviewer prompted to find gaps will usually report some, even when the work is sound.

正しさと要件に関わる指摘だけに絞らせ、過剰設計を避けることが重要だ。

関連: Claude Codeのサブエージェントとは

Skillsで検証を標準化する：4つの配置パターン

公式ブログ「Building verification loops in Claude Code with skills」は、スキルを使って検証ループを標準化する方法を説明している。スキルは .claude/skills/ にフロントマター（name, description, allowed-tools）付きのMarkdownファイルとして置く。

配置パターンは4種類あり、それぞれ用途が異なる（2026年9月時点）。

パターン	動作タイミング	典型的な使い方	注意点
Standalone	成果物ができた後に意図的に呼ぶ	全件には当てはまらない横断チェック（ログ衛生の確認など）	呼び忘れると動かない
Embedded	成果物を作るスキルの一部として自動で動く	既存スキルの指示の末尾に検証ステップを追記するだけ。最も簡単な導入	スキル自体が重くなる
Chained	スキルの最後で別スキルを呼び、検証済みの受け渡しを連続実行	「実装スキル → テストスキル → レポートスキル」のパイプライン	トークン費用が増えやすい。事前にテストを推奨
On every PR	すべてのPRで同じ手順をチーム横断で実行	コードレビューの基準統一・チームへの展開	チーム全員のスキル設定が必要

公式ブログが例として挙げているのがログ衛生の検証スキルだ。「エラー経路にリクエストIDがあるか」「機密データをログに出力していないか」をチェックする。こうした横断的な確認をStandaloneスキルとして切り出すか、実装スキルにEmbedded形式で組み込むかは、チェックを毎回自動で走らせたいか、任意で呼びたいかによって選ぶ。

公式はChained パターンについてこう警告している。

Chained verification loops can increase token spend, so it’s best to test these loops before deploying them broadly.

関連: Claude Codeの自動化（hooks・非対話実行）

最初の1本を作る手順

公式ブログは作り方を6つのステップで示している（下では最後の2つ「新しいタスクで試して直す」「連鎖を試す」を1つにまとめた）。一足飛びに複雑なChainedを作ろうとすると途中で詰まる。まず「繰り返し手で直している指摘」を1つ選ぶところから始めるのが現実的だ。

1. 繰り返し手で直している指摘を見つける：「毎回Claudeに同じことを言っている」という場面を特定する。例：「テストを実行して確認して」「ビルドが通ることを確かめて」
2. /verify を試す：まず組み込みの /verify スキル（ビルド・実行して変更を観察する）を実行し、それが自分のユースケースに合うか確かめる
3. 手順を平文で書く：「どのコマンドを実行し、何がパスならOKか」を箇条書きで書く。あいまいな指示は検証の質を下げる
4. SKILL.md にする：.claude/skills/ 以下にフロントマター付きのMarkdownとして保存する。skill-creatorを使うか直接書く
5. 改善し、連鎖も試す：使いながら指示を洗練する。安定したらChainedへの昇格も検討する

手順2の /verify は、入力欄に /verify と確かめたい内容を続けて入力して呼び出す。下は、README に書いた実行例（python3 calc.py 2 3 で 2 + 3 = 5）どおりに動くかを確かめさせた例だ。

/verify は実際にコマンドを実行し、結果（PASS）と、どのコマンドで何が返ったか（終了コード）を証拠として示す。「できました」という自己申告ではなく、実行した結果で判断できる。

最初に手をつけやすいのはCLAUDE.mdへのルール明文化だ。スキルファイルよりも先に「何を確認すべきか」の基準を文章で固めておく。証拠を示させるという公式の勧告――

Have Claude show evidence rather than asserting success: the test output, the command it ran and what it returned, or a screenshot of the result.

――をそのままCLAUDE.mdに転記するだけでも、自己申告の質は変わる。

よくある質問（FAQ）

Q. Stop hookとCLAUDE.mdの指示の違いは何か？

公式Best Practicesによれば「CLAUDE.mdの指示はアドバイザリ（推奨）であるのに対し、フックは決定論的であり、アクションが必ず実行されることを保証する」。指示は無視されうるが、フックはシステムレベルで強制される。

Q. 検証サブエージェントを呼ぶと毎回費用が増えるか？

はい。新しいモデルインスタンスを起動するたびにトークンが消費される。Chainedで連鎖する場合も同様で、大規模展開前に件数と費用を見積もることを推奨する。

Q. /verify とStop hookはどちらを先に試すべきか？

公式の勧めどおり /verify から始める方が低リスクだ。Stop hookは通るまでターンの終了をブロックする仕組み（連続ブロックには上限あり）なので、チェック自体が正しく動くことを確かめてから組み込む方が安全。

Q. 検証スキルがフェイルを報告しないのに実際には壊れている場合はどうするか？

チェック自体が「実際のユーザー経路」をカバーしていない可能性が高い。上で挙げたアバター映像の例がそうだ。チェックが何をカバーし何をカバーしていないかを明示的に定義し直す必要がある。

Q. 敵対的レビューが指摘を出しすぎて収拾がつかなくなったら？

公式の注意通り「正しさと要件に関わる指摘だけに絞らせる」プロンプトにする。「問題点を列挙して」という指示は常に何らかの指摘を生む。「このコードがビジネス要件X・Yを満たしているかだけをレビューして」のように範囲を絞ることで過剰設計を防げる。

出典・参考

• Claude公式Best Practices「Give Claude a way to verify its work」
  https://code.claude.com/docs/en/best-practices（2026年9月時点）
• Claude公式ブログ「Building verification loops in Claude Code with skills」Delba de Oliveira、2026年7月22日
  https://claude.com/blog/building-verification-loops-in-claude-code-with-skills
• YouTube「Building verification loops in Claude Code」Claude公式チャンネル
  https://www.youtube.com/watch?v=mQZB0l-rhxE