1
1

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

【要約】How the Claude Code team thinks about verification ― エージェントに「証拠で検証」させるためのテスト戦略と運用ルール 🔍

1
Posted at

はじめに 📝

2026年11月16日に claude.dev ブログで公開された記事 「How the Claude Code team thinks about verification」(著者: Addy Osmani、カテゴリ: Engineering)の内容を、日本語で要約して紹介します。

Claude Code チームでは、コードの大部分(約90%)を Claude が書き、Claude がレビューしています。この規模になると、エージェントが「証拠をもって」自分の仕事を検証できるようにすることが極めて重要になります。記事では、投資する価値のある3種類のテストと、Claude Code チーム自身が検証レイヤーを「正直」に保つための運用ルールが紹介されています。

なお元記事にはコード例がないため、イメージを掴むために記事中で推奨されている verify スキルの置き場所 を図にしておきます 👇(記事の説明をもとにした構成イメージです)

your-repo/
└── .claude/
    └── skills/
        └── verify/   # シミュレーターの起動やアプリの実行方法をまとめたスキル
                      # Claude はコミット前にこのスキルを使って変更を検証する

3行まとめ ✨

  • 🧪 投資すべきテストは E2E テスト・プロパティテスト・差分(differential)テスト の3種類。フレーキーなテストと遅いテストは避ける
  • 🏃 検証とは「変更を実際に動かすこと」。起動・操作手順を verify スキルにまとめ、コミット前に Claude に使わせる
  • 🛡️ 検証レイヤーは変更から手の届かない場所に置き、重要だったバグで採点し、見逃しをルール化し、定期的に剪定する

検証ループがなぜ重要か 💡

  • 検証ループは、Claude により多くの仕事を任せるための基本構成要素
    • 検証ループがなければ、人間がすべてをチェックする必要があるため、同時に動かせる Claude は1〜2個が限界
    • 検証ループがあれば、数十〜数百の Claude を並列に動かせる
  • エージェントに出力を検証する手段を与えることは、品質向上に効果的
    • 構造化ファイル生成に関する社内テストでは、別のグレーダーがルーブリックに沿って Claude の成果物をチェックすることで、標準的なプロンプトループに比べてタスク成功率が最大10ポイント向上(参考)。最も難しい問題で効果が最大だった
  • かつては高コストだったテスト・ベンチマーク・仕様・実際の E2E 実行も、今はエージェントに安く依頼できる。生成されたテストはソフトウェアとして動くので、追加トークンをほとんど使わずに何度でも実行できる
  • 検証結果をエージェントの改善にフィードバックすることもできる
    • 例: ログにユーザーデータが含まれていないかを確認するテストにエージェントが繰り返し失敗するなら、hook や CLAUDE.md のより明示的なルールを作る → 同じ問題の再発を(ほぼ)防げる

🧪 すべてのテストが同じではない:投資すべき3種類のテスト

どのテストを選ぶにしても、避けるべき失敗パターンがあります。

失敗パターン 何が起きるか
⚠️ フレーキーなテスト エージェントが失敗したコードを直すのではなく「再実行する」ことを学習してしまう
🐢 遅いテスト バッチあたりのテスト数が減り、問題の特定が難しくなる

重いテストは、変更をコミットする前に実行するのがベストです。

🌐 E2E テスト

1種類だけに絞るなら E2E テスト。カートに商品を追加 → チェックアウト → 確認ページへ、といった実際のユーザーフローを記述します。

  • ごまかしが効かない:機能全体が動くか、動かないかのどちらか
  • 完了条件が明確で、何が壊れているかを具体的に示せる
    • 単体テストだと「Error: Timeout after 30 seconds」としか出ないこともあるが、E2E テストなら何が壊れているかをスクリーンショットと説明で示せる
  • 単体テストは速くてフレーキーになりにくいが、単体テストは通っても機能が壊れていることがある(エージェントもテストもタスク全体を理解していないため)
  • エージェントに、実際に動いているシステムへの「手と目」を与えるのが効果的。スキルを使い、CDP・シミュレーター・API ハーネスなどでアプリを起動・操作・検査させる
  • フィーチャーマップ(ユーザー視点の機能一覧。パス、キーボードショートカット、セレクター、期待結果の説明つき)は、エージェントのガイド兼採点ルーブリックになる

🎲 プロパティテスト:壊れてはいけない制約

多くのテストは「何が壊れそうか」という人の想定に基づいています。プロパティテストは、人が見落としがちなエッジケース(=エージェントもよく失敗する部分)に目を向けます。

  • 「絶対に成り立つはず」という命題を書き、テストライブラリに反証を試みる入力を何千個も生成させる
  • ほぼすべてのソフトウェアにあるプロパティの例
プロパティ 内容
🔁 ラウンドトリップ 「X をエンコードしてデコードすると X に戻る」。パースやシリアライズにも使える
📏 不変条件 「口座残高は決してマイナスにならない」など、常に真であるべきこと
♻️ 冪等性 マイグレーション・正規化・リトライなどを2回やっても1回と同じ効果
🟰 等価性 最適化したコードが、素朴だが正しいコードと同じ結果を返す
  • プロパティライブラリは、元のコードを書いたエージェントと同じバイアスを持たないエッジケースでエージェントを正直に保てる
  • 仕様が本番の挙動から乖離し、検証の拠り所として信頼できなくなったリライト時にも特に有効

🔀 差分テスト:旧システムがオラクル(正解)

  • 機能が変わらないことが期待される大規模マイグレーションで特に有効
  • 旧システムと新システムに同じ入力を与え、結果が異なればバグか破壊的変更がある
  • ポイント
    • ランダム生成した入力か本番トラフィックのサンプルを使う
    • 空白など無関係な差異は正規化する
    • 新環境が旧環境と異なるべきケースのために、承認済みの変更リストを持っておく

🏗️ Claude Code チームの検証の考え方

Anthropic でのコードレビューの仕組みは以前の記事で紹介済みで、本記事ではさらに踏み込んで「どう検証しているか」が説明されています。

🏃 検証とは「変更を実際に動かす」こと

  • アプリを E2E で動かすことは、テストよりも重要。iOS の変更をシミュレーターで試さずにリリースしないのと同じで、Claude にも同じことが言える
  • Claude は人間や QA エンジニアのようにアプリ全体をテストできる
    • Web: Claude Chrome 拡張
    • モバイル: iOS / Android の MCP
    • デスクトップ: computer use
    • バックエンド: サービスをローカルで起動
  • シミュレーターの起動やアプリの実行方法は verify という名前のスキルに落とし込む
    • リポジトリの .claude/skills/ フォルダに、関連コードのなるべく近くに置く(必要なだけ追加してよい)
    • Claude はコミット前に verify スキルを使うことを知っている
  • verify スキルはスモークテストハーネスなので、高速かつ確実に動くよう投資する。Claude に反復改善やストレステストをさせるとよい
  • Anthropic ではほぼすべての変更をこの方法でテストしている

🙋 失敗し続けるテストは人間の出番

  • すべての変更を誰かが読むことはできないので、「失敗」を人が必要かどうかの判断材料にしている
  • Claude がチェックを実行して失敗を修正しようとし、3ラウンド経っても失敗するなら止めて人間を呼ぶ

👤 コードオーナーが自分でチェックを書く

  • コードのオーナーがチェックを書き、オーナー自身が指摘するであろうことを指摘できるまで洗練させる
  • チェックがレビュアーを呼ぶときは理由を明記し、レビュアーが diff から推測しなくて済むようにする

📋 信頼性チェックは diff をトリガーに

  • 39項目の信頼性チェックリストを運用。各項目は「diff から読み取れるトリガー」「チェック内容」「その背景となったインシデントや PR」で構成
    • 例:「--resume が古いトランスクリプトを読み込む」。セッションストレージやメッセージ型が変わったとき、新しいフィールドを安全に読み込めるか(古いトランスクリプトにはそのフィールドがない)を確認する
  • Claude が diff を読み、トリガーに合致する項目(通常3〜10個)だけをチェックする → 過去の障害を誰も暗記しなくてよい

🔁 レビュアーは1人、ラウンドを重ねる

  • レビュアーを積み重ねて改善しようとはしない。高価な2人目のレビュアーを追加するより、1人目をチューニングする方が良いことが多い
  • そのために、このコードでレビュアーが何に注意すべきかを書いた REVIEW.md を用意する
  • レビュー・検証のラウンドは前のラウンドの文脈や過去の失敗を踏まえて行い、毎回ゼロから全部チェックし直さない。その方が安く、多くを見つけられる

🔒 変更は自分を審査するチェックを書き換えられない

  • 変更が自分を審査するチェックを書き換えられるなら、そのチェックは壊れている
  • レビューはコミット単位で行う。レビュー中に push されたらその結果はもう役に立たない。古いコミットに対するレビューのパスには意味がない
  • 安いチェックから先に実行する
    • ローカルでテストせずに push すると、自分で見つけられたはずのバグに共有のレビュー・CI 時間を使ってしまう
    • Claude Code チームでは、Claude が PR を作る前にテスト・ビルド・リンターを実行する
    • Claude の終了時にテストを走らせる hook や、テストスイートのパスを目標にした /goal で強制できる

👀 新しいゲートは observe モードから始める

  • 各コミットにどう検証されたかのスタンプを付ける。「none」も含めることで、未検証のコミットをクエリできる
  • セッション内で /code-review または /verify が実行されていなければコミットをブロックできるコミットゲートを作成。モードは3つ
モード 挙動
off 無効
observe ブロックされるはずだったものをログに記録。誤検知を確認し、誰にも影響が出ないようにする
enforce コミットをブロックする
  • どのコミットも、検証しなかった理由をコミットメッセージに書ける
  • セッション内で2回ブロックされたら、次のコミットは通す(Claude が行き詰まらないように。Claude Code も完璧ではないため)

📊 チェック自体を「本当に重要なもの」でテストする

  • Claude Code チームは定期的にレビュアーをレビューしている。追跡しているのは
    • マージ後に revert された変更の数
    • マージ前にメンテナーが却下した変更の数
    • クリーンなままの変更から、サイズを揃えて抽出したサブセット
  • 形式的な評価(eval)でも可能。コードレビューの記事で紹介した Code Review チームの評価では
    • 過去のインシデントや revert を元に、レビュー時点のリポジトリ状態を再現
    • バグの内容を 1文の正解キー で用意し、それを正しく説明した指摘だけが得点
    • マージ済みで安定した変更を対照群にして過剰な指摘を防ぐ
    • チューニング用セットと固定のテストセットを分離
  • 生の指摘・検証後・最終レビューそれぞれの再現率を別々に測定し、一度見つけたバグを途中で失っていないかを確認する。E2E の単一スコアではこのニュアンスを捉えられない
  • 妥当性に加えて「その修正がどれだけ重要か」も重視。Code Review は指摘に Important / Nit / Pre-existing のタグを付ける
    • Pre-existing は「元からあったバグなので作者の責任にしない」という意味
  • 再現率は、それ以上の改善が「実際にバグを捕まえる」のではなく eval への過学習になる手前までチューニングする

📝 見逃しをルールに変える

Claude Code リポジトリでは、見逃しをルール化する方法が2つあります。

  1. 人間のレビューコメントと PR の revert からパターンを抽出
    • 少なくとも2つの PR で発生し、かつ diff から識別できるものだけがルール候補
    • 3つのエージェントが反証を試み、PR で人間がレビュー・承認する
  2. 既知のインシデントに紐づく PR に対して、3つのバグファインダーをリプレイ
    • 2つ以上が見つけたら「検出可能なバグ」
    • 小さな diff で見逃されたなら、REVIEW.md のルールにする価値のあるギャップ
  • フレーキーなテストも同様に扱う。Claude はスキップ・sleep の追加・パスするまでリトライ、をしてはいけない。根本原因が見つからなければテストを削除し、理由を書き残す
  • ルールにも掃除が必要。テストスイート・検証手順・.md ファイルは放っておくと増える一方なので、定期的に整理する

まとめ 🎯

元記事の結論は「強いフィードバックループで、エージェントに自分の仕事を検証する手段を与えることがすべてを変える」というものです。検証レイヤーも他のシステムと同じように扱いましょう。

  • 🔒 検証レイヤーは、それが審査する変更から手の届かない場所に置く
  • 🐞 自分にとって重要だったバグで採点する
  • 📝 見逃したら教訓を書き残し、同じことが二度起きないようにする
  • ✂️ 教訓は剪定して、実行する価値があるものだけ残す

そうすれば、人の仕事は「すべての diff を読むこと」から「"完了" の定義と証拠のレビュー」へと移り、多くの Claude を同時に動かせるようになります。

まずは手元のリポジトリに .claude/skills/ の verify スキルを用意し、Claude がコミット前にアプリを実際に動かして確認できるようにするところから始めてみてはいかがでしょうか 🚀

参考リンク 🔗

1
1
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
1
1

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?