Claude Codeチームによるコードレビューの進め方

以前にも述べたように、ClaudeはClaude Codeのコードの約90％を自ら記述しています。では、これほど大量のコードを生成している中で、どうやってコードレビューを行っているのでしょうか？そもそも、今どきコードを読む人なんているのでしょうか？そして、もし何か不具合が発生した場合、誰がそれを発見するのでしょうか？

この記事では、Claude Codeチームのコードレビューの流れと、その変遷について解説します。6月から9月にかけて、Claude Codeのコードベースにマージされたプルリクエストの数は2倍以上に増加した一方で、元に戻す必要があったプルリクエストの割合は40％以上減少しました。

レビュー機能を削除したわけではありません。しかし、読解作業の大部分を機械に移行し、人間の時間と注意力を最大限に活用できるよう最適化するとともに、間違いを素早く簡単に取り消せるようにするために多額の投資を行いました。

コードレビューの目的を再考する

エージェントがコードを書くようになると、変更の数は急速に増加します。Anthropicのモノレポでは、1日あたりの変更件数が、今年の5月の約2,500件から9月には30,000件以上に増加しました。

Claude Codeは、モノレポとは別の専用リポジトリに存在していますが、こちらも大きなプレッシャーにさらされています。これほど迅速にリリースを行う場合、手作業による一行ごとのコードレビューは、不可能ではないにせよ、極めて困難です。

コードレビューには2つの役割があります：

リリース前に問題を発見し、修正する
チーム全体で共通の認識とコードベースへの理解を深める

この記事では主に問題の発見と修正に焦点を当てますが、記事の終盤で2つ目の仕事について改めて触れます。

「人間がコードを読んだか？」という問いは、「この変更で何が問題になり得るか、そしてそれを検出するには、自動化されたチェックと人間によるチェックのどちらが適切か？」という問いに対する、不正確な代用指標に過ぎないと私たちは考えています。

その質問をしたことで、レビューが行われるタイミングも変わりました。以前は、レビューは道の終わりにあるゲートのようなものでした。コードを書き、プルリクエストを開き、同僚の反応を待つ、という流れでした。

現在、レビューは継続的に行われており、執筆中のスペルチェックのようなものです。変更点のほとんどは、人間による確認を依頼される前に、Claudeによって少なくとも一度はレビューされ、修正されています。これにより、日常的なミスのほとんどが検出され、チームはより高度な問題や精査に注力できるようになります。

希少な資源：人間の「時間」と「注意力」

私たちは、人間だけが解決できる課題に、人間の時間と注意力を割けるようにし、それ以外の部分は自動チェックで確実に処理できるようにしたいと考えています。現在の変化のスピードを考えると、人間が担うべき仕事は依然として膨大であり、私たちのチームはほぼ毎日、これまでになかったような新たな課題に直面しています。

人的工数は、レビューにかかるコストの両面、すなわちレビューに費やす時間と、質の悪いコードによって生じた不具合を修正するのに費やす時間の両方を網羅しています。前者を削減しても、その時間が後者に転嫁されてしまっては意味がありません。

したがって、目標は、Claude Codeのリポジトリ（CLI、デスクトップおよびWebアプリ、モバイルアプリ）におけるプルリクエストの大部分が、最大1人の人間（作成者自身を含む）の関与のみでマージされ、かつリバートやインシデントの増加を招かないようにすることです。人的工数を測定するために、PR 1件あたりの人的承認数（中央値および95パーセンタイル）、人的コメント、および PR が人による処理を待つ時間を追跡しています。リバート率とインシデント率は「ガードレール」の役割を果たします。これらが上昇した場合、人的工数を削減できたわけではなく、単にその負担を移しただけということになります。

「変化の軌跡」

通常、エンジニアのノートパソコン（あるいはSlack上のClaudeセッション）から行われる変更は、複数の段階にわたるコードレビューを経ます。

変化の軌跡

図A 経路の大部分は自動化されており、人の注意はリスクがある場所に集中する

レイヤー・バイ・レイヤー

ゲート1つではなく、複数の層

図B 各レイヤーは一部の問題を捕捉する一方で、他の問題を見逃してしまいます。すべてのレイヤーを通過できるものはほとんどなく、残りはロールバックによって処理されます。

1. 他の誰かが目を通す前に、その作業は確認される

現在、レビューのほとんどはPRが作成される前に行われています。私たちはClaudeに、テストやビルド、デザインと比較するためのスクリーンショットなど、実行可能なものを与え、「完了」と報告させるのではなく、出力を表示するよう指示します。その後、サブエージェントが新鮮な視点で差分を確認します。これらの習慣は、いずれも当社のベストプラクティスガイドに基づいています。

プルリクエストを開く前に、私たちの多くはいくつかの内部チェックも行っています。ある人はバグを探し、ある人は差分（diff）を整理し、またある人は動作を端から端まで確認します。UIの変更についても、デザインガイドラインに照らしてチェックが行われます。

Claude Codeを開発したボリス・チェルニー氏は、Claudeに自身の作業を検証する手段を与えることが、良い結果を得るために最も重要なことだと述べています。同氏は、これにより最終結果が2～3倍向上すると推定しており、「検証の方法は分野ごとに異なります。 bashコマンドを実行するだけの単純なものもあれば、テストスイートを実行したり、ブラウザやスマホシミュレーターでアプリをテストしたりすることもあるだろう」と記している。

自動レビューツールが同じ問題を繰り返し指摘する場合は、その根本原因となる箇所、つまりスキル内、リントルール、または以下のような指示ファイルの更新などで修正します：

CLAUDE.md Claudeに、そのプロジェクトの概要（スタック、規約、目標、および目標外事項）を説明します。レビューのたびにこのドキュメントが参照されるため、大規模なコードベースでは内容を簡潔にまとめ、そこから他のドキュメントへのリンクを掲載しています。また、レビュー担当者は、このドキュメントに記載された規約に違反するコードや、このドキュメントの記述を古くしてしまう変更についても、フラグを立てます。
REVIEW.md, コードの所有者が作成したこのドキュメントは、レビュー担当者に、そのコードの部分で何が重要かを伝えます。レビュー担当者が実際にそれに従っているかどうかは、別途確認します。優れたガイドラインは簡潔です。そのリポジトリにおいて「失敗」がどのような状態かを明記し（ドキュメントなら「虚偽の記述」、設定ファイルなら「ルーティングミス」など）、些細な指摘は最小限に抑え、スキップすべきパスを列挙し、ファイル名や行番号を根拠として提示するよう求め、単なる推測を避けるようにしています。また、修正箇所がない場合は、その旨を明記し、件数から始まる要約を提出するよう求めています。

2. すべてのプルリクエストに対するAIによるレビュー

すべてのプルリクエストは、人間が確認する前にClaudeによるレビューを受けます。Claudeは、リポジトリ全体との差分とプルリクエストに記載された意図を読み取り、「この変更は問題を解決しているか、システムに適合しているか、あるいは他の部分に不具合を引き起こしていないか」と問いかけます。

バグ修正にあたっては、根本原因を突き止めます。一般公開版である「Claude Code用コードレビュー」は、TeamプランおよびEnterpriseプランで一般提供が開始されており、 /code-review ローカルでは軽量版が実行されます。

リサーチプレビューを開始したところ、実質的なレビューコメントが寄せられる社内PRの割合が16%から54%に上昇しました。 1,000行を超えるPRのほとんどには指摘事項が寄せられ、小規模なPRのほとんどは問題なしと判定されます。管理者は各リポジトリを「クイック」「スタンダード」「ディープ」のいずれかに設定します。「ディープ」は、1つのバグを見逃すことによるコストが、追加のレビューにかかる時間よりも大きい場合に、その価値があります。

発見事項は、人間によるレビューが行われる前に、他のエージェントによって検証されます。複数のエージェントが同時にバグを探します。その後、別のグループが各発見事項について投票を行い、十分な数のエージェントが「本物」であると合意した場合にのみ、それが公開されます。スタイル、診断情報、またはコードの整理のみに関する発見事項は除外されます。これらのフィルタは、採用する前に自社のプルリクエストでA/Bテストを行いました。残った項目は、重大度順に並べられたインラインコメントとして表示されます。それぞれに「重要（Important）」「些細な問題（Nit）」「既存の問題（Pre-existing）」というタグが付けられているため、プルリクエストによって新たに発生したものではないバグが、作成者のミスであるかのように見えることはありません。

すべての指摘には対応する必要があります。修正するか、理由を明記してスレッドをクローズしてください。多くの場合、担当者が夜間に修正を行うため、投稿者は、すでに別のレビューラウンドを経たPRを確認することになります。

3. ブロック可能なセキュリティ審査

セキュリティについても、独自の自動レビューが行われます。バグレビューやセキュリティレビューで指摘された事項が未解決のままである限り、プルリクエストをマージすることはできません。修正するか、簡単な理由を添えてスレッドをクローズする必要があります。これが、誤検知を解消する方法です。

後のコミットでその問題が修正されれば、その検出結果は自動的に解消されます。オープンソースのセキュリティレビュー用GitHub Actionや /security-review コマンドを使用して、同様の設定を行うことができます。設定方法については、Claude Codeの「自動化されたセキュリティレビュー」で解説されています。

4. ブロックする自動チェック

いつもの手順：リンター、型チェック、全プラットフォームでのテスト、そしてビルド。（この規模でのCIのスケーリングについては、こちらで解説しています。）一般的なCLIのプルリクエストでは、誰かが内容を確認する前に、数十ものチェックが実行されることがあります。 PRテンプレートには、変更がどのようにテストされたか、また元に戻すにはどうすればよいかを尋ねる項目があります。Claudeがそれを記入することもできますが、最終的な承認は変更を依頼した本人が行います。

5. リスクに応じた人的承認

ドキュメントの修正と自動更新機能の変更ではリスクが異なるため、それぞれ異なる審査が行われます。

リスク	例	人による承認
低	ドキュメント、コピー、社内限定機能、フラグ設定による追加変更	自動レビューとセキュリティチェックの結果が「合格」となれば、それ以上の対応は不要です
中	通常の製品変更、およびキャッシュ、自動更新機能、システムプロンプトなどの重要な機能に関する変更	1人
高い	リスクが最も高いコードに加え、常に2人が必要な少数のパス	2人

変更内容によってリスクレベルが決定され、作成者によるものではありません。分類器が変更内容を解析し、リスクレベルを判定します。別の分類器が、そのリスクレベルでは他者の確認が不要と判定された場合でも、その特定の変更内容について他者の確認が必要かどうかを判断します。常に他者の確認が必要なケースとしては、所有者が「機密」として指定した項目や、CIワークフローファイルなどが挙げられます。

信頼された作成者のみが、より簡略化された承認プロセスを利用できます。リポジトリの信頼リストに登録されている作成者、主にそのリポジトリを管理するチームのみが、より簡略化された承認プロセスを利用できます。それ以外のユーザーは、別の担当者による承認が必要です。また、エージェントによる承認は、人間の承認としてカウントされることはありません。自動レビューでは低リスクの変更を承認できますが、人間の承認が必要なケースを代替することはできません。

その変更を指示した人物が責任を負うことになる。エージェントが作成したPRの場合、エージェントに指示を出した人物は、あたかもその人物自身がコードを記述したのと同様に、必須のレビューアの一人としてカウントされる。

承認は、特定の1つのコミットに対して行われます。エージェントによるプッシュや、誰かが手動で解決したマージなど、システムが保証できない新しいコミットが追加された場合、再度承認を行う必要があります。

6. キュー、フラグ、および段階的なリリースの統合

マージキューは、変更が適用された状態でメインブランチに対するすべてのチェックを再実行するため、個別にチェックを通過した2つのプルリクエストが結合されて、メインブランチに不具合が生じることはありません。新しい動作は通常、Anthropicの従業員向けにフラグを設定して先行リリースされ、当社での集中的な利用により、ユーザーよりも先にリグレッションが発見されることがよくあります。一般公開版は、まず latest チャンネルに配信されます。 stable チャンネルはそれに続いて提供されます。

7. 迅速な検出、迅速なロールバック

それでも一部のミスは見逃されてしまうため、最終段階ではそれらを迅速に発見することが重要です。デプロイが行われないとフラグは解除されます。Claude Codeでは毎週オンコール当番制を採用しており、インシデントレビューでは、どの段階でその問題を検知すべきだったかが検討されます。

不適切なマージに気付くかどうかは、依然として作成者や当直担当者、さらにはリバートやインシデントのダッシュボードに依存しています。現時点では、これらの数値が変動した際に承認基準を厳格化するサーキットブレーカーは導入されていません。当社のエンジニアたちは、コードのマージが完全に自動化される前に、こうした機能の導入を望んでいます。

ある同僚は、「ペースを落とせばミスは減るが、それはあくまで、あらゆる作業の量そのものが減るからに過ぎない」と言っていました。私たちとしては、問題に気づき、それを修正するスピードをむしろ上げたいと考えています。

レビュー担当者のスキル向上に向けた取り組み

当社のコードレビュープロセスは、ループを繰り返しながら絶えず改善されています。

現在、あらゆるインシデントは評価の対象となっています。チームは、過去にインシデントを引き起こしたPRを、その修正履歴や元に戻した履歴とともに収集し、そのコードに精通したエンジニアに各バグの内容と発生箇所を確認してもらいました。レビュー担当者は、そのデータセットに対して毎日検証を行っています。

当社のインシデントは評価対象です

図C 評価値はインシデントが発生するたびに増加し、レビュー担当者に加えられる変更はすべて、その評価値に基づいて採点されます。

私たちは、ユーザーがコメントに対してどのような対応をするかを観察することで、ノイズを測定しています。バグではないものをたくさんフラグ付けしても構わないという姿勢であれば、より多くのバグを見つけやすくなりますが、そのためには適切なチェックが必要です。レビュー担当者が残したすべてのコメントを、PRの担当者がどのように対応したか（修正した、誤りだと指摘した、その動作は意図的だと説明した、あるいは問題ないと判断した）という基準で分類しています。また、問題がないと分かっているプルリクエストに対してもレビューツールを実行し、誰かが有害な変更を行う原因となり得た問題を報告した頻度をカウントしています。私たちの優先順位は、文書化されている通り、まず真のバグを検出すること、次にレビューの回数を減らすことです。

著者がエージェントの場合、ノイズによるコストは高くなります。個人なら些細なミスは数秒で片付けることができますが、エージェントが修正することになると、新たなコミットと、それに伴う再レビューが必要になります。

レビューは収束させなければならない。エージェントの作成者とレビュー担当者は、互いに延々と作業を続けさせ合う可能性がある。あるCLIのプルリクエストは、作成者が中止するまで、一晩のうちに50回以上のレビューと修正を繰り返した。

レビュー担当者が繰り返し指摘していた箇所に対して「git blame」を実行したところ、その約59％は、レビュー担当者が最初にチェックした時点からすでに存在していたコードでした。レビュー担当者が新しいバグを発見することはほとんどなく、各ラウンドごとに、以前からあったバグをいくつか追加で発見していたに過ぎませんでした。

事態を悪化させたのは私たち自身でした。各パスで新たな問題が見つかるため、デフォルトで数ラウンドのレビューを行うことに慣れてしまっていたのです。これはリスクの高い変更では有効かもしれませんが、すべてのプルリクエストでそうすべきではありません。チームでは現在、リコール率とともに「パスまでのラウンド数」も追跡しており、再レビューの仕組みを変更しました：

ラウンド・キャップ。3ラウンドを経た後、レビュアーは著者に一歩引いて、アプローチを再考するよう求める。
最初の数回のパス終了後の、差分のみを対象とした再レビュー。
バグの種類を明記して、作成者が1行だけでなくすべての箇所を修正できるようにしましょう。
すでに投稿済みの発見内容の重複は避けてください。

また、レビューエージェントは毎晩既存のコードに対して実行され、古いバグが別の場所で発生する前に発見するのに役立っています。

収束するレビュー

図 D：収束の変更後、内部プルリクエストあたりのレビュー回数が減少した

人間が常にプロセスに関与し続ける場所

熟練エンジニアを「ディープワーク」から引き離して、ありふれたミスを見つけ出すには、自動レビューを行うよりもはるかに大きなコストがかかります。Anthropicでは、私たちの仕事は、すべての差分を確認することから、機械が苦手とする意思決定へと移行しています：

そもそもこれを構築すべきなのか？　方向性、好み、そして範囲について。レビューのボトルネックが解消されたと宣言したあるチームでさえ、チーム外からの変更については依然として人間によるレビューを維持していたため、誰かが「そもそもこれを行うべきなのか？」と問うている。
課金機能、自動更新機能、CIワークフローなどのリスクの高いコード。
他者が模倣するようになるような建築。
証拠を確認する。テスト結果、実行したコマンドとその出力内容、スクリーンショット、レビュー担当者の所見など。チェックでは見落とされる可能性がある点を特定できない場合は、安易に承認するのではなく、本格的なレビューを依頼してください。
結果に対する責任。リリースされるすべての変更については、誰がコードを書いたかに関わらず、その担当者が責任を負う。

ある人が決断するとき

図E　人々は、すべての差分を確認する作業から、機械が苦手とする判断を行う作業へと移行した

チーム全体で状況を共有する

コードレビューのもう一つの役割は、常にコードベースへの理解を広めることでした。チームメイトのdiffを読むことで、何が変更されたのか、そして各部分がどのように組み合わさっているのかを学ぶことができるのです。もし機械が読み込みの大部分を担うようになったら、一体どうやってコードを学べばよいのでしょうか？

これに関する正式なプロセスは設けていません。チームメンバーの誰も、Claude Codeの全体像を頭の中に完全に把握しているわけではなく、また、その必要もないと考えています。誰かがコードベースの一部を理解したいと思ったときは、Claudeに、その部分についてのみ解説文を作成するよう依頼します。これには数分しかかからず、現在のコードの状態を正確に反映した内容になります。

中には、さらに一歩踏み込んで、Claudeにコードのその部分を可視化する小さなツールを作ってもらい、その人が好む学習方法に合わせて教えてもらう人もいる。

人間の注意力を有効に活用することが目的なら、これは些細な変更点を一行ずつ読み込むよりもはるかに有益です。たった1行のコピー変更からは、ほとんど何も学べません。一方、これから変更しようとしているモジュールに関する解説文からは、多くのことを学べます。また、オープンなSlackチャンネルで作業することを基本とする私たちの文化も役立っています。なぜなら、他の人が何を作っているかを、実際に作っている最中に見ることができるからです。

「成功させれば、それが自分のものになる」

小規模または中規模の変更を実施したにもかかわらず、何か問題が発生した場合、通常はチームとしてそれを修正するのが慣例となっています。事態が悪化しないようにするためのポイントは以下の通りです：

変更点は些細なものなので、レビューやデバッグ、元に戻す作業も簡単です。
すべては元に戻せます。フラグ、リバート、ステージングリリースを使えば、ほとんどのミスを数分で取り消すことができます。
影響範囲が基準となる。コストのかかるコードほど、より多くの人が関与し、より多くのチェックが行われる。
テレメトリや社内での利用を通じて、回帰バグがすぐに表面化します。
これは非難ではありません。「修正の責任」を負うということは、その件について最も詳しい状況を把握していることを意味します。インシデントレビューでは、システム全体を検証するものです。

所有権も共有されています。チームの多くはオープンなチャンネルで作業しており、誰でも他のメンバーが何を作っているかを確認したり、議論に加わったり、Claudeを使って改善すべき点を指摘したりできます。また、コードの所有者ではないメンバーからもフィードバックが寄せられます。このオープンな姿勢こそが、すべての行にチェックポイントを設けることなく、品質を高く維持できる大きな要因となっています。

方向転換するとき

エージェントのおかげで、新しい取り組みを安価に始められるため、一部の作業は採用されないこともあります。通常、チャネル内の誰かがその理由を尋ねたり、以前の決定を指摘したり、よりシンプルな方法を提案したりすると、作成者はPRをクローズするか、内容を修正します。

コードを書くのは早かったので、PRをクローズしても損をしたような気はしません。コツは、完了したPRに対する妨げになるようなコメントとしてではなく、スレッドの早い段階で別の方向性を提示することです。

このプロセスを導入する方法

チームでこれを実現するための要素のほとんどは、すでに揃っています。

プルリクエストの前に

エージェントが実行できるチェックを、短いリストにまとめて提供してください CLAUDE.md、さらにフォーマッターやリンターを実行するためのフックを指定してください。
実行 /code-review を実行し、 /security-review ローカルで実行するか、新しいコンテキストのサブエージェントによるレビューを行う。
[ REVIEW.mdを追加し、重複しているレビューコメントをそこに移動してください。

すべてのプルリクエストにおいて

CIを必須とし、プルリクエスト（PR）テンプレートに「テスト」、「リスク」、「元に戻す方法」を追加してください。
あるリポジトリにAIレビューア（Claude Code用のコードレビュー、またはClaude CodeのGitHub Action）を追加し、 REVIEW.md 数週間かけて調整し、その後適用範囲を広げていく。
自動化されたセキュリティレビューを追加し、マージ前にすべてのレビュースレッドを解決することを義務付ける。
レビューの取り組みとリスクのバランス：日常的な変更には「クイック」なレビューを、見逃したバグが大きな損失につながるような変更には「ディープ」なレビューを行う（コードレビューの「クイック」「スタンダード」「ディープ」）。
変更点のレビューを段階的に行う。最初の数回を終えた後は、新たに追加された変更点のみを再レビューする。

承認

リスクレベルを、作成者ではなく変更内容に基づいて設定し、書き留めておくこと。最初は厳格に設定し、根拠が得られ次第、緩和していく。
信頼できる著者に対しては、審査プロセスを簡略化したままにしておきましょう。
CODEOWNERS とブランチ保護機能を活用し、認証、課金、CI、リリースワークフロー、およびインストーラーの操作には常に担当者が関与するようにします。
ボットによる承認を、必要な人間による承認の代わりにしてはなりません。新しいコミットに対する承認は却下してください。

マージ後

マージキュー、フィーチャーフラグ、内部先行利用、段階的なリリース、およびワンステップロールバックを活用してください。
インシデントやリバートを評価セットに変換し、プロンプト、ツール、またはモデルが変更されるたびに、レビュアーのスコアを再算出します。
「リバート率」と「インシデント率」を安全基準として、人間の作業時間を測定する。

この先どうなるのか

Code Reviewの発表によると、プルリクエストの承認は依然として人間の判断に委ねられており、同製品が提示するのは「承認」ではなく「指摘事項」である。当社独自のリポジトリではさらに一歩進んでおり、所有者が低リスクの変更について、自動チェックの結果のみに基づいてマージするかどうかを決定できるようにしている。そして、その基準は常に変化し続けている。

レビューで見落としがあった場合、モデルに何が提示されていなかったのかを突き止め、その修正を CLAUDE.md、スキル、あるいは新しいチェックとして実装します。目標は変わっていません。変更1件あたりの人的工数を削減し、以前と同程度のロールバック数に抑えることです。

チームでエージェントによるプルリクエストの作成を許可している場合、どのようなチェックを自動化しているか、どのチェックには依然として人の手が必要か、また当社の説明に誤りがあると思われる点について、ぜひご意見をお聞かせください。

エマ・ウェッブ、マイケル・セグナー、そしてエイミー・ロザラムに、レビューをしていただいたことに感謝します。