Claude Codeの検証ループとは？AIの「テスト通りました」の35%が事実と違った実測と4段階の対策

Claude Codeの検証ループとは？——「終わったように見える」を証拠に変える仕組み

Claude Codeの検証ループとは、作業のあとにテストや画面確認など合否が出るチェックをClaude自身に実行させ、通るまで修正を繰り返させる仕組みです。Anthropicはベストプラクティスで、実行できるチェックがなければ人間が検証ループになると述べています。

Anthropicの公式動画「Building verification loops in Claude Code」（2026年9月25日公開・3分8秒）は、Claude Codeが依頼ごとに「文脈を集める→行動する→検証する→応答する」というループを回していると説明しています。問題は3つ目の「検証」です。Claude Codeはテスト・型チェック・リンターを自分で実行して直しますが、動画はそれだけでは足りないと指摘します。

「それらをすべて通過しても、変更が意図したとおりに動くことは証明されません。それを証明するのは、あとから手で行う確認です。」

"But passing all of those doesn't prove the change does what you meant. What proves it is the check you do by hand afterwards."

Anthropic公式動画 — Building verification loops in Claude Code 0:29

動画が勧める出発点は、Claude Codeに同梱されている/verifyスキルです。初回はアプリを実際に起動して変更を確かめ、うまくいった手順を.claude/skills/verify/SKILL.mdとしてプロジェクトに保存します（公式ドキュメントによればv2.1.200以降）。デモでは「いいね」ボタンの追加を頼まれたClaudeが、開発サーバーの起動、ボタンのクリック、スクリーンショットの撮影、Chrome DevTools MCPによるレイアウトシフトの計測までを自分で行い、見つけたずれを直して再計測しています。なお同梱の/verifyは、v2.1.215（2026年7月19日）から利用者が呼び出したときだけ動く仕様です。ただしv2.1.286（2026年9月30日）からは、/verifyが記録したプロジェクトのスキルのように「verify」という名前のスキルがあると、Claudeはコミットの直前にそれを実行するよう指示されます（ドキュメントやテストだけの変更を除く）。一度手順を記録しておけば、コミットのたびに動作確認が走るということです。

「チェックが計測できるものであるほど、Claudeは合格したかどうかを判断しやすくなります。」

"The more measurable a check is, the easier it is for Claude to tell whether it's passed or not."

Anthropic公式動画 — Building verification loops in Claude Code 1:44

事務所の仕事に置き換えると、検証ループは「検算」や「読み合わせ」をAIに組み込むことです。「月次報告書を作った」ではなく「20社分のファイルがそろい、各社の売上合計が会計データと一致した」のように、計測できる完了条件を渡すほどAIは自分で合否を判断できます。動画の締めくくりの助言も同じで、手で確認してClaudeに直させている作業に気づいたら、それを計測できる基準として書き出すよう勧めています。Claude Codeそのものの基本はClaude Codeとは？入門ガイドで解説しています。

なぜAIの「テストが通りました」は事実と違うのか？——101件の実測で分かった「古い結果」

原因の大半は嘘ではなく「古い結果」です。海外の開発者の調査では、成功の申告101件のうち35件が申告の時点で事実と違い、そのうち34件は、一度テストが通ったあとに編集を続け、再実行しないまま「すべて通過」と報告したものでした。

調べたのは開発者のVinzenz Eiberger氏です（dev.to、2026年9月24日）。2026年9月の2週間に使ったClaude Code 95セッションとOpenAI Codex 28セッションから、テスト・ビルド・リンター・型チェックが通ったという申告を抜き出し、ログから「どのコマンドがいつ実行され、どのファイルがいつ編集されたか」を再構成しました。判定は4体のClaudeサブエージェントが、固定の基準で互いに独立して行っています。

「古い結果」は、具体的には次の3つのパターンでした。

エージェント別ではCodexの43%、Claude Codeの18%が事実と違いましたが、著者は「モデルのランキングとして読まないで」と明記しています。Codex側は長いマルチエージェント作業が中心で、作業内容も標本数も違うためです。さらに著者が普段どおりの作業を1週間観察し直すと、新しい申告13件のうち「古い結果」は0件でした。問題は、長時間・複数エージェントの作業で積み上がるというのが著者の結論です。1人・2週間の標本で、判定もAIによるもの（104件中29件は確信度「中」）という限界も本人が挙げています。

「| tail」で失敗が消える

著者が挙げたもう1つの注意点は、テストの出力を| tailで短くする書き方です。パイプの終了コードは最後のコマンド（tail）のものになるため、テストが失敗しても「成功（0）」が返ります。手元で、わざと失敗させたテストを実行して確かめました。

$ python3 -m unittest -q 2>&1 | tail -1
FAILED (failures=2)
$ echo $?
0          ← テストは失敗しているのに終了コードは「成功」
$ set -o pipefail
$ python3 -m unittest -q 2>&1 | tail -1
FAILED (failures=2)
$ echo $?
1

bashとzshのどちらでも、set -o pipefailを付けない限り終了コードは0でした。人間やAIが出力の文字を読めば気づけますが、終了コードだけで合否を決めるスクリプトやフックは、このまま失敗を見逃します。

Claude Codeに検証させる4つの段階——プロンプト・/goal・Stop hook・第二の意見

公式ベストプラクティスは、検証の組み込み方を「1つのプロンプトで」「/goalでセッション全体に」「Stop hookで決定的なゲートとして」「第二の意見で」の4段階に整理しています。下の段ほど準備の手間が増え、そのぶん人が見ていない作業でも正しく終わりやすくなります。

段階1：完了報告に「証拠」を書かせる

最も手軽で、すぐ効くのがこの段階です。公式ベストプラクティスは「成功を主張させるのではなく、テストの出力、実行したコマンドとその戻り値、結果のスクリーンショットなど証拠を示させる」よう勧めています。前述のEiberger氏も、道具を作るより先に指示ファイルへ次の1文を書く運用に落ち着きました。日本語にするとこうなります。

- テストが通ったと報告する前に、最後の編集の後でテストを再実行し、
  実行したコマンドと終了コードを引用すること。

テストの代わりに照合スクリプトや件数チェックを使う業務でも、同じ書き方が使えます。CLAUDE.mdの置き場所と書き方はCLAUDE.mdとskillsの使い分けを参照してください。この1行の効果は、後述の手元検証で測りました。

段階2：/goalで条件を満たすまで続けさせる

/goalは、完了条件を1つ設定すると、条件を満たすまでClaudeが自分で次のターンを続けるコマンドです（v2.1.139で追加）。公式ドキュメントによれば、中身はセッション限定のprompt型Stop hookで、ターンが終わるたびに小さなモデル（Claude APIでは既定でHaiku）が条件と会話を読んで判定します。条件は4,000字まで書けます。

注意点は、評価役が自分ではコマンドを実行せず、ファイルも読まないことです。会話に表示された内容だけで判定するため、条件は「テストが終了コード0で終わる」のように会話に証拠が残る形で書き、変えてはいけないものと打ち切り条件も添えます。当研究所の見解では、会話に「古い結果」の報告が残れば評価役もそれを材料にしてしまうため、段階1の証拠ルールと組み合わせて使うのが安全です。

/goal 最後の編集の後に python3 -m unittest を実行し、終了コード0で終わること。
テストファイルの期待値は変更しない。20ターンで止める。

段階3：Stop hookで「合格するまで終われない」ようにする

/goalが「会話を読んで判定する」のに対し、Stop hookはスクリプトが実際にテストを実行して判定します。設定ファイルに書くので全セッションに効き、判定は毎回同じです。設定例と落とし穴は次の章で詳しく解説します。

段階4：第二の意見（敵対的レビュー）を入れる

作業したClaude自身に「確認して」と頼むと、自分の判断の経緯に引っ張られます。公式ベストプラクティスは、新しい文脈のサブエージェントに差分と基準だけを渡してレビューさせる「敵対的なレビューステップ」を勧めており、差分のバグを探す/code-reviewスキルも同梱されています。計画書や仕様との突き合わせなら、次のように自分でレビューを依頼します。

サブエージェントを使って、請求書計算の差分を 仕様.md と照らしてレビューしてください。
すべての要件が実装されているか、挙げた境界の金額にテストがあるか、
依頼範囲外の変更がないかを確認し、好みではなく正しさと要件に関わる不足だけを報告してください。

最後の一文には理由があります。公式ドキュメントは、指摘を探すよう頼まれたレビュー役は健全な作業にも何かしら指摘を出しがちで、すべてを追うと余計な抽象化や起こりえないケースのテストが増える「過剰設計」につながると注意しています。

Stop hookでテストが通るまで終わらせる方法——設定例と5つの落とし穴

Stop hookは、Claude Codeが応答を終えようとするたびに実行されるフックです。スクリプトが終了コード2で終わると終了が取り消され、エラー出力がそのまま「続ける理由」としてClaudeに渡るため、テストが通るまで作業を続けさせるゲートになります。

設定例（手元で動作を確認したもの）

必要なのは、プロジェクトの.claude/settings.jsonとスクリプト1本です。パスの指定はHooks リファレンスが推奨する形式にしています。

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/test-gate.sh",
            "args": []
          }
        ]
      }
    ]
  }
}

#!/bin/bash
# Claudeが終わろうとするたびに実行され、テストが通るまで終了させない
set -o pipefail
cd "$CLAUDE_PROJECT_DIR" || exit 0

# 前回テストが通ったときからコードが変わっていなければ、テストを回さず終了を許可
hash=$(find . -name '*.py' -not -path './.git/*' | sort | xargs cat | shasum | cut -d' ' -f1)
[ "$hash" = "$(cat .claude/.last-green 2>/dev/null)" ] && exit 0

out=$(python3 -m unittest -q 2>&1)
code=$?
if [ $code -ne 0 ]; then
  echo "テストが失敗しています（終了コード ${code}）。修正してテストを再実行し、実行したコマンドと終了コードを報告してから終了してください。" >&2
  echo "$out" | tail -n 12 >&2
  exit 2   # 1ではなく2。1だとClaudeはそのまま終了してしまう
fi
echo "$hash" > .claude/.last-green
exit 0

テストのコマンド（ここではpython3 -m unittest）と対象のファイル（*.py）は、プロジェクトに合わせて置き換えます。合格時の記録ファイル.claude/.last-greenは.gitignoreに入れておきます。スクリプトは「このプロジェクトのテストコマンドで、この形のStop hookを作って」とClaude Codeに頼めば作れますが、次の5点は人が確認してください。

5つの落とし穴

補足として、macOS標準のbash 3.2では、日本語のメッセージ中で$code）のように変数の直後に全角文字を続けると文字化けしました。変数は${code}のように波括弧で囲むと安全です。危険な操作を止めるPreToolUseのフックについては権限設定ガードレールの作り方で解説しています。

手元検証：1行のルールとStop hookでClaude Codeの完了報告は変わるか？

士業の報酬請求書を計算する小さなプログラムで試したところ、「古い結果」の報告は6回とも起きませんでした。違いが出たのは報告の中身で、実行コマンドと終了コードが書かれたのはルールなしで3回中0回、CLAUDE.mdに1行書くと3回中3回でした。Stop hookは、終了コード2のときだけ失敗したテストを直すまで終了を止めました。

検証の条件

2026年9月30日、Claude Code v2.1.285をヘッドレスモード（claude -p）で動かし、モデルはSonnet 5.5、編集は自動承認にしました。題材は、報酬額から消費税（10%）と源泉徴収税を計算するinvoice.pyとテスト2件です。源泉徴収税は、国税庁のNo.2798に従い100万円以下が10.21%、超える部分が20.42%（1円未満切り捨て）ですが、最初のコードは100万円超に対応していません。依頼文は次のとおりで、「テストが通った後にもう一度編集させる」ことで古い結果が生まれやすい流れにしています。

invoice.py の源泉徴収税を100万円超にも対応させてください（100万円を超える部分は20.42%。国税庁 No.2798）。
テストケースを追加して通ることを確認したら、最後に関数名・変数名を読みやすく整理
（例: withholding → calc_withholding_tax）してから、結果を報告してください。

結果1：CLAUDE.mdの1行ルールの有無（各3回）

Sonnet 5.5は、ルールがなくても名前の整理のあとにテストを再実行していました。短く単純な作業では古い結果は起きにくいという点は、Eiberger氏が普段の作業で観察した結果（13件中0件）と一致します。差が出たのは報告の書き方です。ルールなしの報告は「リネーム後も含めて6件のテストがすべて通っています」のように結論だけで、読む側は信じるしかありません。ルールありの報告は3回とも実行コマンドと終了コードを含み、たとえば1回目は「テスト結果（リネーム後、最後の編集のあとに再実行）　コマンド：python3 -m unittest -v　結果：5件すべてOK、終了コード exit=0」と、確かめられる形になっていました。

パイプの使い方にも差が出ました。ルールなしではテストの実行13回すべてが| tail -4などの形で、終了コードは実質的に見ていません。ルールありでは9回中2回で、そのうち1回はClaude自身がset -o pipefailを付けて実行していました。3回ずつの小さな比較ですが、終了コードを報告させることが、終了コードを正しく取る書き方も促したように見えます。

ほかにも1つ、人が確認すべき点が見つかりました。ルールなしの1回では、Claudeが自分で追加したテストの期待値を手計算で間違え（150,000円）、テストが失敗したあとでテスト側を149,998円に直していました。今回はテスト側の修正が正解でしたが、「テストの期待値を書き換えて合格させる」動きは、どの段階の検証でも自動では防げません。期待値の変更があったかどうかは、差分で人が確認します。

結果2：Stop hookの終了コード1と2

次に、先ほどのゲート（Stop hook）を入れ、終了コードだけを1と2で変えて比べました。100万円超のテスト（150万円で源泉徴収税204,200円）が失敗している状態から始め、Claudeにはあえて無関係な「請求書番号を採番する関数の追加」を頼んでいます。

終了コード1のゲートは、テストを実行して失敗を検出しながら、終了を止められませんでした。一方で、この結果には考えるべき点もあります。終了コード2のゲートは「テストが全件通ること」を完了の定義として強制するため、依頼の範囲外だった既存の不具合までClaudeに直させました。終了コード1の回で、Claudeが修正前に「直しますか？」と確認したのは、人と一緒に作業する場面ではむしろ望ましい振る舞いです。既知の失敗テストを抱えたまま運用しているプロジェクトでは、ゲートで実行するテストを対象の範囲に絞る必要があります。

今回の検証は、小さな題材・各3回・短いセッションという条件での結果です。古い結果が起きやすいとされる長時間・複数エージェントの作業は試していません。

テストだけで足りないときはどうする？——Shopify Helixのゲートと、Boris Chernyの形式検証

テストの合格は「書いたテストの範囲では正しい」ことしか示しません。そこで海外の実践では、テストの前後に種類の違うチェックを重ねています。Shopifyは4つのゲートを順番に通し、Claude Code責任者のBoris Cherny氏は形式検証で、テストでは拾いにくいバグを探しています。

Shopify Helix：4つのゲートと「覆せない検査」

Shopifyは2026年9月21日、モバイルアプリをReact NativeからSwift・Kotlinへ作り直すための社内ツール「Helix」を公開しました。Shopアプリはすでに12週間で作り直しており、その経験を300画面を超えるShopifyアプリに生かすために作ったのがHelixです。作業を小さな「チェックポイント」に分け、それぞれが(1)テストによる振る舞いの確認、(2)元のアプリとの見た目の比較、(3)文脈を分けた2体のレビュー役による敵対的コードレビュー、(4)エンジニアの承認、の4つのゲートを順に通るまで次に進みません。

「必要なだけ何度でもやり直せますが、結果が十分に良いと自分で思ったからといって、失敗した検査を覆すことはできません。」

"It can retry as many times as it needs to, but it can't override a failed check just because it thinks the result is good enough."

Talha Naqvi（Shopify）— Helix: The internal tool powering our Shopify app's native migration

Helix自体はClaude Code専用ではなく、見た目の比較にはGemini、全体の進行にはGPTが使われています。この仕組みをClaude Codeで再現したYouTubeチャンネルAI LABSは、Stop hookが終了コード2を返して次のタスクに進ませない構成を示し、ルールとゲートの違いを次のように説明しています。

「ルールは助言にすぎません。エージェントは作業中にルールを忘れるので、また言い直す必要があります。ゲートは違います。ゲートを通過しない限り、エージェントを次のタスクに進ませません。」

"A rule is only advice. The agent forgets the rule when it's working and you have to remind it again. A gate is different because unless a gate is passed, it won't let the agent move to the next task."

AI LABS — Shopify Just Released The Greatest AI Coding Workflow Ever 5:36

段階1（ルール）と段階3（ゲート）の違いは、まさにこの点です。同じように「確率ではなく決まりで守る」設計は、StripeのClaude Code導入事例でも紹介しました。

Boris Cherny：形式検証で「人が見落とすバグ」を探す

Boris Cherny氏は2026年9月23日、Opus 5.5と証明支援系のLeanを使ってClaude Agent SDKを形式検証し、数回の短いプロンプトでバグと競合状態を直す16件のPRができたと投稿しました（約190万表示・ブックマーク4.6K、9月30日時点）。仕様記述言語のTLA+も併用しているそうです。

「どちらの言語もよく知りませんが、Claudeは両方とも非常に得意です。」

"I don't know either language well, but Claude is excellent at both."

Boris Cherny（Anthropic・Claude Code責任者）— X（2026年9月23日）

翌日の補足によれば、Claudeが行っているのは (1)状態遷移が込み入った部分や競合が起きやすい部分をモデル化する、(2)モデルの中で反例（バグの候補）を探す、(3)実際のコードで再現する、(4)修正する、という流れです。コード全体を検証しているのではなく、最も込み入った部分だけを対象にしています。当研究所ではLeanを試していませんが、業務に置き換えるなら「受付→補正→許可→更新期限」のような状態の移り変わりを持つ案件管理で、ありえない状態の組み合わせを探す用途が考えられます。多くの事務所にとっては、段階1〜3を先に整えるほうが効果は大きいでしょう。

検証は厚くするほど良いわけではない

最後に、検証を増やす側の限界も押さえておきます。Eiberger氏は「最後のテスト以降に編集した」ことを検出して終了を止めるフックを試作しましたが、警告の正しさは30件中22件（73%）で、自ら決めた基準の90%に届かず断念しました。「狼少年のゲートは外される」ためです。Max Taylor氏が、テストのない編集を止めるClaude Codeプラグイン「tdd-guard」を54回の実行で比べたベンチマーク（2026年9月28日）では、費用が素のClaude Codeの1.9〜3.8倍になり、テストの質はむしろ素のClaude Codeが上でした。テストを先に書く縛りが、テストの無い要件を飛ばす原因になることもあったといいます。一方で、継続開発ではテストがコードと一緒に増え続ける点に価値があると結論づけています。

SIOS Tech Labの記事は「ガードレールは、効かなくなったことを自分では教えてくれません。」と書いています。当研究所の見解では、ゲートは少なく強くし、月に一度はわざと失敗させて止まることを確かめるのが、長く効かせるための現実的な運用です。

まとめ