Claude Codeチームはどのように検証を考えているか
How the Claude Code team thinks about verification (claude.dev)
要約
Claude Codeチームでは、コードの約90%をClaude自身が記述・レビューしており、その検証プロセスが極めて重要です。検証ループは、Claudeに多くの作業を委任するための基盤となり、品質向上に不可欠です。本記事では、E2Eテスト、プロパティテスト、差分テストという3つの主要なテストタイプと、Claude Codeチームが実践する検証プロセスについて解説します。
全文翻訳
Claude Codeチームはどのように検証を考えているか
Claude Codeチームでは、コードの大部分(約90%)はClaude自身によって記述され、Claudeによってレビューされています。この規模では、エージェントが証拠をもって作業を検証できるように支援する方法が極めて重要になります。
検証ループは、Claudeにさらに多くの作業を委任することを可能にするビルディングブロックです。これらがないと、すべてを自分でチェックする必要があるため、一度に1つか2つのClaudeしか実行できません。これらがあれば、数十、数百を並列で実行できます。
なぜなら、エージェントに出力結果を検証する方法を提供することは、品質を向上させる効果的な方法だからです。構造化されたファイル生成に関する社内テストでは、別の評価者がルーブリックに基づいてClaudeの作業をチェックしたところ、標準的なプロンプトループと比較してタスク成功率が最大10ポイント向上し、最も困難な問題で最大の成果が得られました。
かつて検証にコストがかかっていたこと(テスト、ベンチマーク、仕様、実際のE2E実行)が、エージェントに依頼するだけで安価になりました。コードと同様に、エージェントはテスト、ベンチマーク、仕様を迅速に生成できます。生成されたテストやベンチマークはソフトウェアとして実行されるため、追加のトークンをあまり消費せずに頻繁に実行できます。
結果を使用して、そのタスクにおけるエージェントのパフォーマンスを改善することで、検証ループを閉じることもできます。たとえば、エージェントがユーザーデータを含むログをチェックするテストで繰り返し失敗する場合、CLAUDE.mdにフックまたはより明確なルールを作成して、将来の問題を防ぐことができます。これにより、問題は(ほとんど)再発しなくなります。
したがって、高い速度で高品質なコードを生成するために検証が不可欠である場合、どのような種類のテストを使用し、パイプライン全体にどのように適用すべきでしょうか?この記事では、これらの質問に答え、Claude Codeチームが使用するプロセスも共有します。
すべてのテストが平等に作られているわけではない:投資する価値のある3つのテスト
どのテストタイプを選択するにしても、避けるべきいくつかの障害モードがあります。
テストが不安定(flaky)だと、エージェントは失敗したコードを修正するのではなく、テストを再実行するように学習してしまいます。テストが遅いと、エージェントはバッチごとにテストを実行する回数が減り、問題の特定が困難になる可能性があります。より重いテストは、変更をコミットする前にデプロイするのが最適です。
さて、私が最も投資する価値があると思う3つのテストタイプを紹介します。
E2Eテスト
1つのテストタイプに集中する必要があるなら、エンドツーエンド(E2E)を選んでください。これらのテストは、カートに商品を追加する、チェックアウトする、確認ページに移動するといった実際のユーザーフローを記述します。
E2Eテストが非常に効果的な理由は、だまされにくいことです。機能全体が機能するか、あるいは機能しないかのどちらかです。また、明確な完了基準を持ち、何が壊れているかを具体的に教えてくれます。
[画像: Unit test failure vs. end-to-end test failure. Left: checkout.test.ts shows only “FAIL checkout.test.ts / Error: Timeout after 30s”, captioned “Shooting blind. No step, no trace.” Right: checkout.spec.ts shows a step trace (Register, Add item to cart, Checkout failed, See confirmation page not reached), a screenshot of shop.example/checkout with “Payment form failed to load” and a disabled “Place order” button, and “What step failed: Checkout: ‘Place order’ stayed disabled because the payment form never loaded”, captioned “Screenshots, trace, and a description of what step failed.”]
図A単体テストは「エラー:30秒後にタイムアウト」と表示されるかもしれませんが、E2Eテストは壊れているものの説明付きのスクリーンショットを表示できます。
単体テストはより高速で不安定さも少ないですが、それらをパスしても機能が壊れている可能性があります。これは、エージェントもテストも完全なタスクを理解していないためです。
E2Eテストでは、エージェントに実際の実行システムに対する手と目を与えることが効果的です。CDP、シミュレーター、APIハーネスなどのツールを使用して、アプリを起動、操作、検査するためにスキルを使用できます。
機能マップは、エージェントのガイドおよび評価ルーブリックとして機能します。通常、ユーザーの視点から機能、パスの説明、キーボードショートカット、セレクター、期待される結果をリストアップします。
プロパティテスト:壊れない制約
多くのテストは、何が間違っている可能性があるかという想定に基づいています。プロパティテストは、人々が見落としがちなエッジケースに注目します。これはエージェントがしばしば失敗する場所です。
失敗しないはずだと考えるステートメントを記述し、テストライブラリ(JS/TSの場合はfast-check、Pythonの場合はHypothesis、Rustの場合はproptestなど)を使用して、それを証明しようとする数千もの入力を生成します。
ほぼすべてのソフトウェアプロジェクトには多くのプロパティがあります。たとえば:
- ラウンドトリップエンコーディング:「Xをエンコードしてからデコードすると、Xが得られる」これは、解析やシリアル化にも有効です。
- 不変条件(Invariants):「口座残高がマイナスになることは決してない」など、常に真であるべきこと。
- 冪等性(Idempotency):アクション(マイグレーション、正規化、リトライ)を2回実行しても、1回実行した場合と同じ効果が得られる。
- 等価性:最適化されたコードが、単純だが正しいコードと同じ結果を生成する。
プロパティライブラリは、元のコードを作成したエージェントと同じバイアスなしに作成されたエッジケースを使用することで、エージェントを正直に保つための優れた方法です。また、仕様が本番の動作から逸脱し、検証の信頼できるソースでなくなったリライトにも特に役立ちます。
差分テスト:古いシステムがオラクルとなる
差分テストは、機能が同じままであることが期待される大規模な移行ユースケースに特に効果的です。これらのテストでは、古いシステムと新しいシステムの両方を同じ入力で実行し、異なる結果が得られるかどうかを確認します。異なる結果が得られた場合は、修正が必要なバグまたは破壊的な変更があります。
差分テストの鍵は、ランダムに生成された入力または本番トラフィックのサンプルを使用することです。また、空白などの無関係な要因を正規化し、新しい環境が古い環境と異なるべき状況に対して承認された変更のリストを保持したいと思うでしょう。
Claude Codeチームはどのように検証を考えているか
以前にAnthropicでのコードレビューの仕組みについて書きましたが、この記事では作業の検証方法についてさらに深く掘り下げます。
検証とは、変更を実行すること
アプリをエンドツーエンドで実行することは、テストよりも重要です。シミュレーターで試さずにiOSの変更をリリースすることはありません。Claudeも同様です。
Claudeは、人間やQAエンジニアが行うように、アプリ全体をテストできます。Webの変更にはClaude Chrome拡張機能、モバイルにはiOSまたはAndroid MCP、デスクトップにはコンピューターの使用、バックエンド作業にはローカルでのサービス実行を依頼してください。
シミュレーターの起動方法やアプリの実行方法をコード化するには、verifyという名前のスキルを作成します。リポジトリ内の.claude/skills/フォルダに、関連コードのできるだけ近くに配置し、必要なだけ追加してください。Claudeは、コミットする前にverifyスキルを使用することを知っています。
そして、verifyスキルを高速かつ信頼性の高いものにするために投資してください。Claudeにそれを反復させ、ストレスをかけてテストするように依頼してください。これはあなたのスモークテストハーネスなので、非常に堅牢にしたいはずです。
Claudeにエンドツーエンドでスモークテストを実行する方法を与えると、はるかに良い結果が得られます。人間のように、それが反復し、実際のミスをより速く検出するのを見るでしょう。これが、Anthropicでほぼすべての変更をテストする方法です。
テストの失敗は人間の注意を必要とする
誰もすべての変更を読むことはできないため、失敗を人が必要とするものを決定する1つの方法として使用します。Claudeはチェックを実行し、失敗したものを修正しようとします。3ラウンド後もチェックが失敗し続ける場合、Claudeは停止して人間を呼び出します。
コードオーナーが自身のチェックを作成する
コードを所有する人々がそのコードのチェックを作成し、それらがオーナーがフラグを立てるものをフラグを立てるまで洗練させます。チェックがレビュアーを呼び出す場合、その理由を伝えるべきです。そうすれば、レビュアーは差分からそれを理解する必要がなくなります。
信頼性チェックは差分でトリガーされる
私たちは、39項目からなる信頼性チェックリストを維持しており、それぞれに差分から読み取れるトリガー、チェック、およびそれらの背後にあるインシデントまたはPRがあります。1つは「--resume loads old transcripts」です。セッションストレージやメッセージタイプが変更された場合、古いトランスクリプトには含まれていないため、新しいフィールドが安全にロードされるかどうかを尋ねます。
Claudeは差分を読み、トリガーが一致する項目のみをチェックします(通常は3〜10項目)。そのため、誰も過去の障害を記憶する必要はありません。
1人のレビュアー、複数ラウンド
より多くのレビュアーを追加することでレビューを改善しようとはしません。2人目の、より高価なレビュアーを最初のレビュアーの上に重ねることは、最初のレビュアーを調整するよりも悪いアプローチであることがよくあります。代わりに、レビュアーがこのコードについて何に注意を払うべきかを記載したREVIEW.mdがあります。
また、レビューと検証のラウンドはお互いに積み重ねられるべきだと考えています。すべてを最初から再チェックするのではなく、以前のラウンドや過去の失敗からのコンテキストを各パスに指示します。より安価で、より多くのものを見つけます。
変更は自身のチェックを変更できない
変更がそれを判断するチェックを変更できる場合、チェックは壊れています。コードレビューは、プルリクエストの変更からではなく、ベースまたはデフォルトブランチからREVIEW.mdファイルを読み取ります。Claude Codeチームは、変更をゲートするルールが、変更が変更できないブランチ上にあることを保証します。
Claude Codeチームは、レビューをコミットのために予約しています。レビュー中に誰かがプッシュしている場合、レビュー結果はもはや有用ではありません。古いコミットでの合格したレビューは意味がありません。
チームはまた、まず安価なチェックを実行します。エージェントがローカルでテストする前にプッシュした場合、自分でバグを検出できたはずのレビューおよびCI時間を費やしたことになります。私たちのチームでは、Claudeはプルリクエストを開く前にテスト、ビルド、リンターを実行します。これは、Claudeが完了したときにテストを実行するフックや、合格したテストスイートの/goalで強制できます。
オブザーブモードで新しいゲートを開始する
私たち自身のリポジトリでは、各コミットに検証方法のスタンプを押しています。スタンプには「none」も含まれているため、検証されなかったコミットをクエリできます。
また、セッションに/code-reviewまたは/verifyが含まれていない場合にコミットをブロックできるコミットゲートを作成しました。これをオフ、オブザーブ、エンフォースモードで設定しました。
オブザーブモードは、ブロックされるであろうものをログに記録するため、偽陽性をレビューし、誰も影響を受けていないことを確認できます。
エンフォースモードはコミットをブロックします。コミットは、検証されなかった理由の説明をメッセージに含めることができます。セッションでコミットが2回ブロックされた場合、Claudeが立ち往生しないように、次のコミットは許可されます。Claude Codeは完璧ではありません。
実際に重要なものをテストする
Claude Codeチームは、レビュアーを定期的にレビューします。マージされた変更がロールバックされた数、メンテナーがマージ前に却下した変更の数、およびクリーンな状態を維持した変更のサイズマッチングサブセットを追跡します。
これは正式な評価でも行うことができます。私たちのコードレビュー投稿で、Code Reviewチームが過去のインシデントとロールバックに基づいて評価を設定した方法を説明しました。各例について、レビュー時のリポジトリの状態を再現し、バグは何であったかについての1文の解答キーを提供します。問題のバグを正しく説明した発見のみが得点されます。過剰なフラグ付けを防ぐために、マージされた安定した変更をコントロールとして使用します。チューニングセットは、システムを評価するために使用する固定テストセットから分離されています。
また、生の発見、検証後、最終レビューの再現率を個別に評価しました。これにより、システムが既に発見したバグを失っているかどうかを確認できます。これらすべてを1つのエンドツーエンドスコアとして扱う評価では、このニュアンスを捉えることはできません。
有効性に加えて、私たちが気にかけているもう1つの次元は、変更の重要性です。優れたレビュアーは、技術的に正しいほとんどのものを検出しますが、人々は特定のバグが必須修正(must-fix)、推奨修正(should-fix)、または些細な修正(nit)であるかどうかを気にします。
Code Reviewにはこの正確な考え方があり、それをImportant, Nit, or Pre-existingとしてタグ付けします。「pre-existing」タグは、レビュアーが既にバグであったものに対して作者に責任を負わせるべきではないことを意味します。
最後に、Claude Codeチームは、次の改善が評価への過剰適合ではなく、実際にバグを検出することになる点まで再現率を調整します。
ミスをルールに変える
Claude Codeリポジトリでは、ミスしたケースをルールに変えるための2つの方法があります。1つ目は、人間のコードレビューコメントやPRのロールバックからパターンを抽出し、一般的な問題を特定することです。これらは少なくとも2つのPRで発生し、差分から識別できる場合にのみ、潜在的なルールと見なされます。3つのエージェントがそれらを反証しようとし、PRで人間によってレビューおよび承認されます。
2つ目の方法は、既知のインシデントに関連付けられたPRに対して3つのバグファインダーを再生することです。少なくとも2つがバグを見つけた場合、それは検出可能なバグです。小さな差分でバグが見逃された場合、これはREVIEW.mdにルールとして変換する価値のあるギャップです。
不安定なテストも同様の扱いを受けます。Claudeはそれらをスキップしたり、スリープを追加したり、パスするまでリトライしたりすることはできません。根本原因を見つけられない場合、テストを削除し、その理由を書き留めます。
ルールもクリーンアップが必要です。テストスイート、検証ステップ、.mdファイルは、許可するだけで増え続けるため、定期的に整理します。
良いテスト、良い結果
エージェントに強力なフィードバックループで作業を検証する方法を与えることが、すべてを変えることを発見しました。検証レイヤーを、他のシステムと同様に扱ってください。判断する変更から手の届かないところに置き、あなたにとって重要だったバグに対してそれらを採点し、何かを見逃したときにレッスンを書き留めて、それが一度以上起こらないようにし、それらのレッスンを刈り込んで、実行する価値があるようにしてください。
そうすれば、あなたの仕事はすべての差分を読むことから、「完了」が何を意味するかを定義し、証拠をレビューすることにシフトします。これが、一度に多くのClaudeを実行できる理由です。