Claude Codeチームの検証の考え方 — 3種のテストと検証層の守り方
Claude Codeチームが、エージェントに作業の証拠を出させる検証をどう組むか。E2E・プロパティ・差分の3種のテストと、検証層を改ざんさせない運用を読み解きます。
Claude Codeチームは、コードの約9割をClaudeが書き、レビューもClaudeが担っています。この規模では、人が全差分を読む前提は成り立ちません。2026年11月16日、claude.dev開発者ブログのEngineeringに「How the Claude Code team thinks about verification」(著者はAddy Osmani)が載りました。エージェントに作業の証拠を出させる検証を、どのテストで、どの運用で支えるかの解説です。
要点 — 検証ループがあるから、並列で走らせられる
記事の骨子
- 検証の手段を持たせないと、同時に動かせるClaudeは1〜2本。持たせると数十〜数百本まで増やせる、というのが出発点です
- 投資先のテストは3種です。まずE2E、次にプロパティテスト、移行時には差分テストを足します
- 検証層(チェックやレビュー規則)は、検証される変更の手が届かない場所に置きます
- 検証者そのものも、過去に問題になったバグで採点し、見逃しは規則に変えます
10月15日の前回ポストは、PRが通る層を並べたコードレビューの記事でした。今回はその手前、変更を「動かして確かめる」側に焦点が移っています。前回の整理はClaude Codeチームのコードレビューにあります。
背景 — 検証が安くなったので、委任できる量が変わった
ブログの論旨は、検証を手で行うと委任の上限が人の確認速度で決まる、というものです。検証ループがあれば、人は全部を確認しなくて済みます。
効果を示す数字も1つあります。構造化ファイルの生成に関する社内テストで、別の採点役がルーブリック(採点基準)に照らしてClaudeの出力を確認すると、通常のプロンプト反復より成功率が最大10ポイント上がりました。伸び幅は、難しい問題ほど大きくなりました。条件は特定のタスクに限られるので、他のタスクにそのまま当てはまる数字ではありません。
もう1つの変化は、コストの側です。テスト、ベンチマーク、仕様、実環境での通し実行は、かつては作るのも回すのも高くつきました。いまはエージェントに頼めば安く作れ、作ったあとはソフトウェアとして回るので、追加のトークンもほとんど要りません。
結果をエージェントの改善に戻す道もあります。たとえばログにユーザーデータが出ていないかを調べるテストが何度も落ちるなら、フックかCLAUDE.mdの明示的な規則を足します。同じ失敗が(ほぼ)起きなくなる、という立て付けです。
投資する3種のテスト
テストの種類を選ぶ前に、避けたい失敗は2つです。不安定(flaky)なテストは、エージェントに「直す」より「もう一度走らせる」を教えます。遅いテストは、エージェントが回す回数を減らし、バッチをまたぐと原因の切り分けが難しくなります。重いテストを置く場所は、コミット前です。
| 種類 | 何を確かめるか | 向く場面 |
|---|---|---|
| E2E | 何を確かめるか実ユーザーの流れが通しで動くか | 向く場面機能追加・UI変更。1種類だけなら、これ |
| プロパティ | 何を確かめるか常に成り立つはずの性質が、大量の入力で崩れないか | 向く場面往復変換・不変条件・冪等性・最適化との等価性 |
| 差分 | 何を確かめるか旧システムと新システムが同じ入力で同じ結果を返すか | 向く場面大規模な移行・書き換え |
E2E — 騙しにくいテスト
1種類だけ選ぶなら、E2Eです。カート追加から決済、確認画面までのように、実ユーザーの流れを描くテストで、機能全体が動くか動かないかのどちらかしかありません。完了の基準が明確で、何が壊れているかも具体的に返ります。単体テストなら「30秒でタイムアウト」としか出ないところを、E2Eならスクリーンショットと壊れた箇所の説明で返せます。ブログはこの違いを図で示しています。
単体テストは速く、不安定さも小さい一方で、全部通っても機能が壊れていることがあります。エージェントもテストも、タスク全体を理解していないからです。E2Eで有効なのは、エージェントに実行中の本物のシステムへの手と目を渡すことです。スキルでアプリの起動・操作・確認を組み、CDP(Chrome DevTools Protocol)、シミュレーター、API用ハーネスなどを使います。ユーザー視点で機能を並べた「機能マップ」(経路、キーボードショートカット、セレクタ、期待結果)は、案内図と採点基準の両方に使えます。
プロパティテスト — エージェントと別の偏りで入力を作る
多くのテストは「こう壊れるだろう」という人の予想から作られます。エージェントが失敗しやすいのは、予想から漏れた境界の入力です。プロパティテストは、壊れないはずの命題を書き、ライブラリが大量の入力で反証を試みます。ブログが挙げるライブラリは、JS/TSのfast-check、PythonのHypothesis、Rustのproptestです。
性質の例は4つです。
- 往復変換: 符号化して復号したら元に戻る(パースとシリアライズも同じ)
- 不変条件: 口座残高は負にならない
- 冪等性: マイグレーション・正規化・リトライは、2回行っても1回と同じ
- 等価性: 最適化したコードは、遅くても正しい素朴な実装と同じ結果を返す
入力はエージェントが元のコードを書いたときの偏りと無関係に作られるので、「エージェントを正直にする」手段になります。仕様が本番の挙動から離れ、仕様を検証の基準にできない書き換えでも有効です。プロパティテストによるバグ発見の研究は、ClaudeとProperty-Based Testingで扱っています。
差分テスト — 旧システムを答え合わせの基準にする
機能を変えない大規模移行では、旧システムと新システムに同じ入力を流し、結果が違えばバグか破壊的変更です。入力は乱数生成か、本番トラフィックの標本を使います。空白など無関係な差は正規化し、新環境で違ってよい箇所は「承認済みの差」の一覧に残します。
Claude Codeチームが回している運用
チーム自身の運用は、4つの原則に分かれます。
検証とは、変更を実際に動かすこと
テストよりも、アプリを端から端まで動かすことが重視されます。iOSの変更をシミュレーターで試さずに出荷しないのと同じで、Claudeにも、人やQA担当者のように動かさせます。Web変更ならClaudeのChrome拡張、モバイルならiOS/Android用のMCP、デスクトップならcomputer use、バックエンドならローカル起動です。
起動手順の固定には、verifyというスキルを作ります。リポジトリの.claude/skills/に、関係するコードのなるべく近くへ置き、必要なだけ足します。Claudeは、コミット前にこのスキルを使います。そのうえで、スキル自体を速く確実に磨く(Claudeに反復と負荷試験をさせる)のが推奨です。スモークテストの土台だからです。
公式ドキュメント側にも対応する記述があります。verifyかsimplifyという名前のスキルが揃った状態でセッションが始まると、コミット直前に実行する指示がClaudeに渡ります。docs・テストだけの変更は除かれます。要件はClaude Code v2.1.286以降です。場所は、組織・個人・プロジェクト・追加ディレクトリのスキルか、.claude/commands/の同名ファイル。同梱の/verify・/simplify、プラグイン・claude.aiアカウントのスキルは、この対象に入りません。disable-model-invocation: trueでClaudeからの呼び出しを止めている場合も、渡りません。設定でincludeGitInstructionsをオフにしている場合も、この指示は渡りません。この条件は、/verify単体の挙動を扱うClaude Code verifyコマンドとは何かと組み合わせて読むと、「自動で走る状態」と「明示的に呼ぶ状態」の違いが分かります。
失敗した検査だけが、人を呼ぶ
全変更を読める人はいないので、失敗を「人が要るか」の判断材料に使います。Claudeは検査を走らせ、落ちたものを直します。3回直しても落ちているなら、止まって人を呼びます。この「3回」は、エージェントが際限なく回り続けない歯止めです。
検査を書くのは、そのコードの持ち主です。持ち主が「自分なら指摘する」と思う点を拾うまで磨き、検査が人を呼ぶときは理由も添えます。レビュアーが差分から理由を逆算しなくて済みます。
差分から呼び出される信頼性チェックリスト
信頼性チェックリストは39項目で、各項目に、差分から読み取れるトリガー、検査内容、背景のインシデントかPRが付いています。例は「--resumeが古い会話記録を読み込む」。セッション保存やメッセージ型を変える差分が来たら、新しいフィールドが古い記録でも安全に読み込めるかを確かめます。Claudeが差分を読み、トリガーが合う項目だけを見るので、実際に当たるのは通常3〜10項目です。過去の障害を、誰かが暗記しなくても済みます。
レビュアーは増やさず、1人を磨く
レビュアーを積み増して品質を上げる方針は採っていません。1人目に2人目の高価なレビュアーを重ねるより、1人目の調整のほうが効くことが多い、という判断です。調整の道具がREVIEW.mdです。もう1つの原則は、検証の周回を積み上げること。前の周回と過去の失敗の文脈を次の周回に渡し、毎回ゼロから確かめ直さないほうが、安く済み、見つかる問題も増えます。
検証層を改ざんさせない設計
検証層の守り方は、どのチームにもそのまま移せる決まりです。
検証層を守る4つの決まり
変更が自分の検査を書き換えられない
変更が自分を判定する検査を書き換えられるなら、その検査は壊れています。Code Reviewは
REVIEW.mdを、PRの変更ではなくベースか既定のブランチから読みます。この読み方は公式ドキュメントにも明記があります。レビューは特定のコミットに対して
レビュー中に誰かがpushすると、その結果は役に立たなくなります。古いコミットに対する合格は無意味です。
安い検査を先に
ローカルで試さずにpushすると、共有のレビューとCIの時間を消費します。テスト・ビルド・リンターは、PRを開く前にClaudeが走らせます。強制するなら、Claudeの終了時にテストを回すフックか、
/goalで「テストスイートが通ること」を条件に置きます。新しい関門は観察モードから
コミットごとに「どう検証したか」の印を付け、未検証なら
noneも記録します。/code-reviewか/verifyがセッションに含まれないコミットを止める関門は、off・observe・enforceの3モードです。observeは「止めたはずの件」を記録するだけなので、誤検知を見てからenforceにできます。
関門にも逃げ道があります。コミットメッセージに、検証しなかった理由を書けます。セッション内で2回止められた後は、次を通します。Claudeが身動きできなくならないための割り切りで、チーム自身が「Claude Codeは完璧ではない」と書いています。
検証者を検証する — 実際に効いたバグで採点する
検証層は、作った時点で完成しません。チームはレビュアーのレビューも定期的に行っています。
追う指標は3つです。マージ後に取り消された変更の数。メンテナーがマージ前に却下した変更の数。それに、規模を揃えた「問題なく残った変更」の標本です。
評価の組み方は、前回ポストのCode Reviewの評価設定に沿っています。過去のインシデントや取り消しごとに、レビュー時点のリポジトリを復元し、バグが何だったかを1文の正解として添えます。正解に合う指摘だけが得点です。マージされて安定した変更を対照に置いて過剰な指摘を抑え、調整用のデータは固定の評価用データと分けます。
さらに、生の指摘・検証後・最終レビューの3段階で、見つけたバグの再現率を別々に測ります。検証の過程でバグを落としていないかを見るためで、全体を1つの得点にまとめると、この区別が消えます。
重要度の軸も持ちます。技術的に正しい指摘でも、直さなければならないもの、直したほうがよいもの、些末なものがあるからです。Code ReviewはImportant、Nit、Pre-existingのタグで区別します。Pre-existingは、元からあったバグの責任を著者に負わせないための印です。チームは、再現率を上げる調整を、評価データへの過適合になる手前で止めています。
見逃しを規則に変える2つの経路
Claude Codeのリポジトリでは、見逃しを規則に変える方法が2つあります。
- 人のレビューコメントとPRの取り消しから、共通の問題を抜き出します。少なくとも2つのPRで起き、差分から判別できるものだけが候補です。3つのエージェントが反証を試み、人がPRで承認します
- 既知のインシデントに紐づくPRに、3つのバグ検出役を再生します。2つ以上が見つければ、検出可能なバグです。小さな差分で見逃したなら、
REVIEW.mdに規則として足す価値のある穴です
不安定なテストも、同じ扱いです。Claudeはスキップも、sleepの追加も、通るまでのリトライもできません。根本原因が分からなければ、そのテストを削除して理由を書き残します。規則も育てるだけでは膨れるので、テストスイート・検証手順・.mdファイルは定期的に間引きます。
手元で試すなら — 最小構成の例
以下は、ブログの内容を手元に写す一例です。ブログに載っている原文ではありません。
まず、リポジトリ直下にverifyスキルを置きます。起動手順はプロジェクトごとに書き換えてください。
---
name: verify
description: 変更を実際に動かして確かめる。コミット前に使う
---
1. `npm run dev` でアプリを起動し、ポート3000で応答するまで待つ
2. 変更した画面の主要な操作を実行し、スクリーンショットを残す
3. 結果(コマンド出力か画面の状態)を貼り、成功か失敗かを言い切る
4. 失敗が3回続いたら、そこで止めて状況を報告する次に、Claudeの終了時にテストを回します。公式ドキュメントのagent型Stop hookの例に沿った形です。agent型のフックは実験的な機能で、仕様が変わる可能性があります。
{
"hooks": {
"Stop": [
{
"hooks": [
{
"type": "agent",
"prompt": "Verify that all unit tests pass. Run the test suite and check the results. $ARGUMENTS",
"timeout": 120
}
]
}
]
}
}完了条件を明示したいセッションでは、/goalも使えます。公式ドキュメントの例は次のとおりです。
/goal all tests in test/auth pass and the lint step is clean/goalは毎ターンの後に別のモデルが条件の成否を判定し、未達ならもう1ターン続けさせる仕組みです。完了を作業中のモデル自身に決めさせない点が、「変更が自分の検査を書き換えない」原則と同じ方向を向いています。/goalはそのセッションだけに効く近道で、Stop hookは設定ファイルの適用範囲にある全セッションに効きます。仕組みの詳細はClaude Codeの/goalコマンドに、フックでテストを回す設定はClaude Code hooksでテストを自動実行するにあります。REVIEW.mdの書き方はREVIEW.mdとはが詳しいです。
まとめ — 検証層を、運用する対象として扱う
読みどころは、テストの種類より後半です。検証の入口は、テストの充実ではなく、verifyスキルという起動手順の固定にあります。検証層を、変更の手が届かない場所に置き、実際に問題になったバグで採点し、見逃しを規則にして、規則も間引く。この4つは、テストフレームワークを問わず移せます。
数字の読み方には注意が要ります。「最大10ポイント」は構造化ファイル生成の社内テストの値です。コードの約9割という割合も、Claude Codeチームの自己申告です。自分のリポジトリで再現する保証は、ブログには書かれていません。
小さく始めるなら、まずverifyスキル1本と、observeモードの関門でしょう。観察して誤検知を見てから厳しくする順序は、ブログ自身が示す入り方でもあります。
参照した一次ソース
この記事の記述は、次の一次ソースと照合しています。更新時に参照先が変わった場合は一覧も更新します。