Claude Code 検証の要は、エージェントが自分の成果を確かめる仕組みを先に用意することだ。 Addy Osmani 氏は、2026年11月17日の記事で、Claude Code チームではコードの約90%を Claude が書いてレビューしていると紹介した。人がすべての差分を読むと、同時に動かせる Claude は1〜2体にとどまる。検証の仕組みがあれば、数十体を並行して動かせる、というのが同氏の主張だ。本記事は、その記事で紹介された仕組みを Claude Code の公式ドキュメントと突き合わせて整理する。あわせて、「失敗したら差し戻し、3回で人を呼ぶ」規則を Stop フックで再現し、実際の Claude Code で動かした結果を示す。
VERIFICATION LOOPAddy Osmani 氏が紹介した Claude Code チームの検証の流れ
検証が人を呼ぶのは、3回直しても失敗したときだけ
-
変更する
コードの約9割を Claude が書く
-
安いチェック
PR の前にテスト・ビルド・リンター
-
verify skill で動かす
アプリを起動し、人と同じように操作して確かめる
-
失敗は自分で直す
3ラウンドたっても失敗なら止まって人を呼ぶ
30秒でわかる Claude Code チームの検証
- ・前提:コードの約90%を Claude が書く。人が全部を読む代わりに、検証の仕組みで品質を保つ
- ・テスト:投資するなら E2E・プロパティ・差分の3種類。フレーキーなテストは避ける
- ・規則:失敗は Claude が自分で直し、3ラウンドで直らなければ人を呼ぶ。判定の規則は、判定される変更からは書き換えられない場所に置く
- ・すぐ試せる形:verify skill と Stop フックで、同じ流れを自分のリポジトリに作れる(本記事で実際に動かした)
Claude Code の機能全体は Claude Code|2026年版・インストールからCLAUDE.md・Hooks・本番運用までの実装手引き にまとめている。
Claude Code 検証が並列化の土台になる理由
検証の仕組みが無いと、エージェントの成果を人がすべて確かめることになり、そこが上限になる。Osmani 氏はこれを、同時に動かせる Claude の数の差として説明している。
同氏によると、検証の効果は数字にも出ている。構造化ファイルの生成を題材にした Anthropic 社内のテストでは、別の採点役(グレーダー)がルーブリックに照らして Claude の成果を確かめるようにすると、通常のプロンプトの繰り返しと比べてタスクの成功率が最大10ポイント上がった。いちばん難しい問題ほど改善が大きかったという。
もう1つの理由はコストだ。テスト、ベンチマーク、仕様、実際の E2E の実行は、以前は書くのに手間がかかった。いまはエージェントに頼めば安く作れる。一度作れば、テストやベンチマークはソフトウェアとして動くので、追加のトークンをほとんど使わずに何度でも回せる。
投資すべき3種類のテスト:E2E・プロパティ・差分
THREE TESTS投資する価値が最も高いとされた3種類のテスト
1つ選ぶなら E2E。ごまかしにくい
-
1.E2E テスト
カートに入れて購入まで、実際の利用者の流れ。機能全体が動くか動かないか
-
2.プロパティテスト
「必ず成り立つ」命題を、fast-check・Hypothesis・proptest が何千もの入力で崩しにいく
-
3.差分テスト
旧システムを正解として同じ入力を流し、結果の違いを見る。移行に向く
Osmani 氏は、エージェントの検証に投資する価値が最も高いテストとして3種類を挙げる。どれを選ぶかは、何を確かめたいかで決まる。
| テスト | 何を確かめるか | 向く場面 | 道具の例 |
|---|---|---|---|
| E2E テスト | 実際の利用者の流れ(カートに入れる→購入→確認ページ)が最後まで動くか | 1つだけ選ぶならこれ。機能全体の合否がはっきりする | Chrome DevTools Protocol、シミュレータ、API のハーネス |
| プロパティテスト | 「必ず成り立つ」命題(往復で元に戻る、残高は負にならない、2回やっても同じ、最適化前後で同じ結果) | 人もエージェントも見落としがちな端のケース | fast-check(JS/TS)、Hypothesis(Python)、proptest(Rust) |
| 差分テスト | 旧システムと新システムに同じ入力を流して、結果が違わないか | 機能を変えずに作り直す大きな移行 | ランダムな入力か本番のトラフィックの標本 |
単体テストは速くて安定しているが、合格しても機能が壊れていることがある。エージェントもテストも、タスク全体を理解していないためだ。プロパティテストは、元のコードを書いたエージェントと同じ思い込みで作られていない入力を使うので、エージェントを正直に保つと同氏は書く。差分テストでは、空白のような無関係な違いをそろえてから比べ、新しい環境で違ってよい点は「承認済みの変更」の一覧に持つ。
避けるべき失敗も2つ挙げている。フレーキーなテストは、エージェントに「失敗したコードを直さずにテストを再実行すればよい」と覚えさせる。遅いテストは、エージェントが一度に回すテストの数を減らし、原因の切り分けを難しくする。重いテストはコミットの前に回す。
Claude Code 検証の仕組み8つと、公式の機能
Osmani 氏が紹介した仕組みのうち、自分のリポジトリで再現できるものを、Claude Code の公式の機能と並べた。
| 仕組み | Claude Code チームのやり方 | 公式の機能での作り方 |
|---|---|---|
| 変更を実際に動かす | Web は Chrome 拡張、モバイルは iOS・Android の MCP、デスクトップは computer use、バックエンドはローカルでサービスを起動 | .claude/skills/verify/ に起動と確認の手順を書く(下のコマンド) |
| 安いチェックを先に | プルリクエストの前に、テスト・ビルド・リンターを回す | 終了時にテストを回す Stop フック、または /goal にテストの合格を条件として書く |
| 3回で人を呼ぶ | 3ラウンドたってもチェックが失敗なら、止まって人を呼ぶ | Stop フックで失敗の回数を数える(下で実際に動かした) |
| 判定を変更から守る | 変更をゲートする規則は、その変更では書き換えられないブランチに置く | Code Review は REVIEW.md をベースかデフォルトのブランチから読む。デフォルトのブランチを保護する |
| 差分で発火するチェックリスト | 39項目の信頼性チェックリスト。差分に合う項目だけ(通常3〜10項目)を確かめる | 項目ごとに「差分のどこに当たれば発火するか」を書いたスキルか REVIEW.md |
| コミットに検証の印 | どう検証したかを各コミットに記録する。「none」も記録し、検証していないコミットを探せるようにする | コミットメッセージのトレーラー(例:Verified: e2e / Verified: none) |
| 新しいゲートは observe から | off・observe・enforce の3段階。observe はブロックしたはずのものを記録するだけ。enforce で同じセッションで2回止めたら次の1回は通す | フックの中で「記録だけ」と「ブロック」を設定で切り替える |
| 見逃しをルールに | 少なくとも2つの PR で起き、差分から識別できるものだけをルールの候補にする。3体のエージェントが反証を試み、人が承認する | 指摘の記録を集計し、くり返したものだけを CLAUDE.md・フック・REVIEW.md にする |
レビュアーを重ねることもしないという。安いレビュアーの上に高いレビュアーを足すより、何に注意すべきかを REVIEW.md に書いて1人のレビュアーを調整するほうがよい、というのが同氏の説明だ。レビューの対象もコミット単位に限る。レビューの途中で誰かがプッシュすれば、古いコミットへの合格は意味を持たない。
Code Review の公式ドキュメントは、REVIEW.md をプルリクエストのベースブランチかデフォルトのブランチから読み、プルリクエスト自身の変更からは決して読まないと明記している。REVIEW.md の変更を効かせるには、先にそれをマージする必要がある。
verify skill と「3回で人へ」を Stop フックで試す
Claude Code チームの規則のうち「失敗は自分で直し、3回で人を呼ぶ」は、公式の Stop フックで作れる。Stop フックは Claude が応答を終えようとするたびに動き、終了コード2を返すと、Claude は止まらずに作業を続ける(公式ドキュメント)。
まず、確認の手順を verify skill として書く。中身はリポジトリに合わせて書き換える。
---
name: verify
description: 変更をコミットする前に、アプリを起動して変更が動くかを確かめる。コードを変えたあと、コミットの前に使う
---
1. `npm test` を実行し、失敗したテストを直す
2. `npm run dev` でアプリを起動し、変更した画面か API を実際に操作する
3. 確かめた手順と結果を報告に書く。確かめられなかったことは「未確認」と書く
次に、Claude が終えようとするたびにテストを回すフックを置く。失敗したら差し戻し、3回続けて失敗したら止めて人に回す。
#!/usr/bin/env bash
# .claude/hooks/verify-on-stop.sh
cat > /dev/null # フックの入力(JSON)は使わない
dir="${CLAUDE_PROJECT_DIR:-.}"; rounds="$dir/.claude/.verify-rounds"
if out=$(cd "$dir" && ${TEST_CMD:-npm test} 2>&1); then
rm -f "$rounds"; exit 0 # 合格:終えてよい
fi
n=$(( $(cat "$rounds" 2>/dev/null || echo 0) + 1 )); echo "$n" > "$rounds"
if [ "$n" -ge 3 ]; then
rm -f "$rounds"
echo '{"systemMessage":"テストが3回続けて失敗した。人の確認が要る"}'; exit 0
fi
printf 'テストが失敗している(%s回目)。直してから終える:\n%s\n' "$n" "$(echo "$out" | tail -20)" >&2
exit 2 # 差し戻し:Claude は作業を続ける
{
"hooks": {
"Stop": [
{ "hooks": [ { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/verify-on-stop.sh" } ] }
]
}
}
フックの台本は chmod +x で実行できるようにし、設定は .claude/settings.json に書く。verify skill の中身(アプリの起動と操作)はリポジトリごとに違うので、編集部は上の例そのものは試していない。編集部は Claude Code 2.1.326 で、add(2, 3) が5を返すかを調べるテストと、わざと引き算にした add.js だけの試験用リポジトリを作って試した。
| 試したこと | 結果 |
|---|---|
| 編集を許可して「了解しましたとだけ答えて終えて」と頼む | 終えようとした時点でフックがテストの失敗を返して差し戻し、Claude が add.js を a + b に直した。テストが通り、そのまま終わった(9ターン、約23秒) |
| 編集を許可せずに同じことを頼む | 直せないまま2回差し戻され、3回目にフックが通して終わった。Claude は「2回連続で失敗、書き込みの許可が要る」と人に返した(11ターン、約27秒) |
| 台本だけを合格・失敗で直接実行 | 合格は終了コード0、失敗は1回目と2回目が2、3回目は人向けの通知を出して0。合格すると回数は消えた |
この規則だけでは安全とは言えない。テストが本当に確かめたいことを確かめていなければ、合格しても機能は壊れている。Osmani 氏が E2E とプロパティテストを勧めるのは、その穴を埋めるためだ。Claude Code には、Stop フックが8回続けて差し戻すと次の差し戻しを打ち切る上限も組み込まれている(公式ドキュメント)。3回は、それより先に人を呼ぶための数字だ。毎回の手間を減らしたいなら、/goal にテストの合格を条件として書く方法もある。/goal は、セッションの間だけ有効な、プロンプトで判定する Stop フックの近道だ。
見逃しをルールにする:当サイトで回している例
検証のループは、見逃しを次の規則に変えて初めて閉じる。Osmani 氏は、エージェントがログの利用者データの検査にくり返し失敗するなら、フックを作るか CLAUDE.md に規則を書けば、だいたい再発を止められると書く。ただし規則は増える一方なので、定期的に刈り込むことも勧めている。
MISSES TO RULES見逃しをルールにする流れ(当サイトの実装)
2回以上出た指摘だけを、規則とチェックにする
-
01
記録する
外部レビューをフックが原文のまま受け箱に保存
-
02
数える
論点ごとの回数を集計。2回以上で、まだ規則に無いものが候補
-
03
規則とチェックにする
教訓の文書に節を足す。機械で見分けられるものは validate の警告に
-
04
刈り込む
古くなった規則は外す(字数の上限は 2026-11-17 に廃止)
整理
AI Heartland でも、記事への外部レビューを同じ形で規則に変えている。2026年11月17日時点で、レビュー7件を受け箱に記録した。
| 段階 | 当サイトのやり方 | Osmani 氏の記事との対応 |
|---|---|---|
| 記録 | UserPromptSubmit フックが、点数つきのレビューを原文のまま保存する |
人のレビューコメントとリバートからパターンを抽出する |
| 候補 | 論点ごとの回数を数え、2回以上出て規則に無いものを候補にする | 少なくとも2つの PR で起きたもの |
| 規則とチェック | 教訓の文書に節を足す。機械で見分けられるものは記事の検証スクリプトの警告にする(例:表の値と「約◯倍」が合わない倍率のずれを検出する REVIEW_RATIO) |
差分から識別できるものを REVIEW.md のルールにする |
| 刈り込み | 古くなった規則は外す(2026-11-17 に本文の字数の上限を廃止) | テストスイート・検証の手順・.md を定期的に片付ける |
違いもある。Claude Code チームは、ルールの候補を3体のエージェントに反証させてから人が承認する。当サイトは、候補を人が読んで判断する段階にとどまる。既知のインシデントで検出器を再実行して見逃しを測る評価も、まだ持っていない。
規模に合わせて、どこから入れるかを選ぶとよい。
| 規模・状況 | 最初に入れるもの | 向く人・場面 |
|---|---|---|
| Claude を1〜2体で使う個人の開発 | CLAUDE.md にテスト・ビルドのコマンドを書き、Stop フックでテストを回す |
毎回「テストを回して」と頼んでいる人 |
| 画面のある機能を頻繁に変える | verify skill に起動と操作の手順を書く。E2E テストを1本作る | テストは通るのに画面が壊れることがあるチーム |
| 大きな作り直し・移行 | 旧システムを正解にした差分テスト | 機能を変えずに中身を入れ替える移行 |
| 複数の Claude を並行して動かす | REVIEW.md を保護したブランチに置く。コミットに検証の印を残す |
レビューが追いつかないチーム |
エージェントに任せる範囲の決め方は コーディングエージェントの使い方はマネジメント|Claude Codeで効く習慣とhookの実測 で、Osmani 氏が公開しているスキル集は Addy Osmani agent-skills徹底解剖|AIエージェントの言い訳を封じる20スキル7コマンド で扱っている。
参照ソース
・How the Claude Code team thinks about verification(Addy Osmani、X、2026-11-17)
・Building verification loops in Claude Code with skills(Anthropic)
・Hooks reference(Claude Code ドキュメント)
・Keep Claude working toward a goal(/goal、Claude Code ドキュメント)
・Customize Code Review(REVIEW.md、Claude Code ドキュメント)





