エージェントを通じてコードレビューを行う方法

買い物リストのページを想像してください。ページは開き、項目は追加でき、ボタンの見た目も問題ありません。それでも、画面が完成しているからといって、コードまでしっかり考え抜かれているとは限りません。開発者は見落としたバグを見つけ、設計上の判断を話し合うために、コードを別途見直す時間を設けます。この作業はエージェントに任せることができ、エージェントは十分にこなしてくれます。ただし、何をしてほしいのかを説明する必要があります。

1. チームでコードをレビューする方法

小さなチームのある開発者が、項目を追加したり1つずつ削除したりできる買い物リストを作るタスクを担当しました。コードを書き、パンと牛乳を追加してみて、パンを削除しました。すべてうまくいきました。作業を次に渡す前に、開発者は自分の変更をもう一度読み返し、消し忘れたコード片を取り除き、分かりにくい名前を直しました。これがセルフチェックです。

次に、彼は同僚にコードを見てもらいました。同僚はプログラミング言語が分かるので、追加がどう実装されているか、削除する項目をプログラムがどう選んでいるか、リストの残りの項目がどうなるかを読んでいきます。こうした確認をコードレビュー(code review)と呼び、確認する人をレビュアーと呼びます。

同僚は気づきます。プログラムは削除する項目を名前で選んでいます。リストに"牛乳"が2つあると、片方を押しただけで両方消えてしまうかもしれません。作成者が試したのはパンと牛乳だけで、このケースにはたまたま当たらなかったのです。

レビュアーは該当するコードの横にコメントを残します。"今の実装だと、この名前の項目がすべて削除されます。同じ名前の項目は許可する仕様ですか？ 許可するなら、選んだ項目だけを削除する必要があります"。作成者は要件を確認します。同じ名前の項目は許可されています。別々の人のために追加されたのかもしれないからです。話し合いのあと、作成者は項目の選び方を変更します。同僚は修正をもう一度見て、指摘が反映されたことを確かめます。

図は、指摘が出たときのレビューの流れを示しています。コードは作成者から同僚へ渡り、修正のために戻ってきます。再確認のあとも疑問が残れば、話し合いと修正を繰り返します。重要な指摘がなくなったら、同僚は変更を承認します。

これがいつもの作業サイクルです。書いて、見せて、指摘を受けて、話し合って、直す。指摘が複数あることもあれば、1つもないこともあります。作成者が判断の理由を説明し、同僚が疑問を取り下げることもあります。レビューでは、すべてのコメントに同意する必要はありません。

こうした見直しでは、コードの分かりやすさも話題になります。次の開発者が理解できるか、1つのルールを変えるのに何か所も直す必要がないか。ついでに同僚は、プログラムの新しい部分がどう作られているかを知ることができます。プロジェクトの知識が少しずつメンバーの間に広がり、作成者だけのものではなくなります。

ここで、レビューをテストと混同しがちです。項目を2つ追加してボタンを押すとき、人は動いているプログラムの振る舞いを確認しています。削除のコードを読み、どの項目が選ばれるかを突き止めるとき、それはレビューです。レビューの途中で、推測を確かめるためにプログラムを実行してもかまいません。この2つは互いに補い合う方法です。

2. エージェントにレビューを委任する方法

今度は、買い物リストをあなたの説明をもとにClaude Codeが書いたと想像してください。あなたはページで何が起きるべきかは説明できますが、その裏にあるプログラムのロジックは読めません。レビューの技術的な部分もエージェントに任せられます。エージェントがファイルを読み、指摘を普通の言葉で説明してくれます。

チームの話に出てきた役割はそのまま残ります。コードの作成者がいて、別のタスクを与えられた確認役がいます。Claude Codeでは、ここでサブエージェントを使えます。メインエージェントが特定の作業を任せる助手です。今回の場合、サブエージェントはコードを読んで指摘を返します。

作成者自身に作業をもう一度見直してもらうのも役に立ちます。独立したレビュアーは、結果を評価するというタスクを受け取るので、別の視点を加えてくれます。どの解決策が許されるのか分かるように、レビュアーには要件を伝えてください。たとえば、同じ名前の項目を禁止すれば削除の問題は形式上なくなりますが、ページの本来の振る舞いが変わってしまいます。

Claude Codeのレビューに関する推奨事項では、独立したレビュアーと明確な基準を用意することが勧められています。また、正しく動くかどうかや要件に影響する指摘に集中するよう助言しています。これをプロジェクトの小さな部分に当てはめてみましょう。

レビューを進めるためにあなたがすることは多くありません。期待する振る舞いを説明し、確認された問題のうちどれを直すかを選ぶだけです。プログラムのロジックを読むこと、原因を探すこと、技術的な反論を検討することはエージェントに任せられます。

図には3つの役割があります。あなたは要件を決めて修正を選び、メインエージェントは作業を取りまとめてコードを直し、確認役はコードと指摘を調べます。メインエージェントは確認役に必要な材料を渡し、結果をあなたに返します。確認された問題がなければ、修正のステップは飛ばします。以下では、この流れを3つのリクエストで実行します。

最終的に手元に残るのは、問題の分かりやすい説明、その再確認の結果、そして修正の報告です。指摘が誤りだったと分かった場合も、それは有益な結果です。不要な修正をせずに済んだのですから。

こうした見直し用の常設の助手を設定したい場合は、サブエージェントの作成と起動についての記事が役に立ちます。より詳しい依頼の準備の仕方は、ブリーフと結果の形式についての記事で解説しています。

リクエスト1. 書いたコードをチェックする

プロジェクトのフォルダーでClaude Codeを起動します。次の3つのリクエストはメインセッションに送ってください。メインエージェントが自分で助手に作業を渡します。ここから先は学習用の買い物リストを例にします。自分のプロジェクトで使うときは、振る舞いの説明を差し替えてください。

現在のプロジェクトにある買い物リストのコードのレビューを
独立したサブエージェントに任せて。項目の追加と削除をチェックして。
要件: 同じ名前は許可する。削除されるのは
選んだ項目だけ。空の項目は追加できない。

現在のコードと、それに関係するプロジェクトの部分を読んで。
これらの要件に違反するバグを探して。
コードは変更しないで。新しい機能は追加しないで。
指摘ごとに、分かりやすい言葉で説明して:
何がうまくいかない可能性があるか、どの操作で起きるか、なぜそう判断したか。
別のエージェントが後で確認できるよう、コード内の場所を示して。
問題が見つからなければ、そう書いて。何を確認したか、
何が分からないままかを挙げて。レポートはREVIEW_REPORT.mdに保存して。
私はプログラミング言語が分からないので、コードを読まなくても分かるように結果を説明して。

REVIEW_REPORT.mdは普通のテキストのレポートです。名前は私たちが決めたもので、別の名前でもかまいません。次のリクエストで、どの指摘を再確認するのかがはっきり分かるようにするためのものです。"コードは変更しないで"という要件は、レビューと修正を切り分けます。レポートの書き込みは許可されています。

この例では、役に立つ回答は次のようなものになるでしょう。"同じ名前の項目を2つ追加すると、1つを削除したときに両方が消えます。コードが名前で項目を選んでいるため、名前が一致する2つの項目が両方とも対象になります"。これは説明用の回答例であり、あなたのプロジェクトを確認した結果ではありません。

あなたにも影響は分かります。残しておくつもりだった項目が消えてしまうのです。ファイル名とコード内の場所は、次のエージェントが原因を見つけるためのものです。あなた自身がその部分を読み解く必要はありません。

3. 指摘を再確認する方法

レビュー担当のエージェントも間違えます。たとえば"リストに空の項目を追加できます"と書いてきたとします。もっともらしく聞こえます。しかし実は、空の入力のチェックはプログラムの別の部分にすでにあり、エージェントはそこを読んでいなかったのです。この指摘は存在しない問題を説明しています。

このように自信たっぷりだが事実でない主張は、AIのハルシネーションと呼ばれることがよくあります。レビューでは特に厄介です。エージェントが修正を提案し、あなたはもともと正しく動いていたコードの変更に時間を使ってしまうかもしれません。だからこそ、書いたコードだけでなく、それに対する指摘も再確認しておくと役に立ちます。

最初の一歩はもう済んでいます。作成者の作業を見てもらいました。次は、別の確認役にレポートと現在のプロジェクトを一緒に渡します。その役目は、それぞれの指摘が本当に成り立つかを確かめることです。最初のレビュアーに反対してもかまいません。

リクエスト2. レビュアーのレポートを検証する

別のサブエージェントに、REVIEW_REPORT.mdを
現在のプロジェクトのコードと前のリクエストの要件に照らして再確認させて。
その要件はサブエージェントに明示的に渡して。

指摘ごとに、説明された問題が実際にあるかを調べて。
関係するコードの部分も確認して。必要な処理がすでにあるかもしれない。
最初のレポートを証拠として扱わないで。結論を出すのに
実行による確認が必要なら、使える手段で実行して。
プロジェクトのコードは変更しないで。

各項目について、確認された、否定された、
まだ判断できない、のいずれかを示して。根拠を分かりやすく説明して。
コードを読んで得た結論と、実行した確認の結果は分けて書いて。
実行していない確認を、実行したかのように見せないで。
結果はREVIEW_CHECK.mdに保存して、私に短く説明して。

これで、再確認の結果をまとめたREVIEW_CHECK.mdが手元に残ります。この学習用の例では、2つ目のエージェントは同じ名前の問題を確認し、空の入力についての指摘は否定するかもしれません。"空の文字列は項目の追加前に弾かれます。最初のレビュアーはこのチェックを見落としていました"。

これだけで、次に何をするかを選びやすくなります。削除の問題は修正に回せます。空の入力は、この指摘を理由に変える必要はありません。エージェントが"まだ判断できない"と書いてきたら、どんな情報が足りなかったのか説明してもらいましょう。それがあなたへの質問であることもあります。たとえば、同じ名前の2つの項目を1つの買い物と数えるのか、2つと数えるのか、です。

再確認は作り話の指摘をふるい落とすのに役立ちますが、完全になくなる保証はありません。2つのエージェントが同じ間違いを繰り返すこともあります。だから回答には根拠が必要です。確認役がプロジェクトの中で具体的に何を見つけたのか、実行してどんな結果を得たのか。"前のエージェントに同意します"だけでは足りません。

4. 修正と再レビュー

では、何を直すかを選びましょう。そのためには、問題がページの本来の動きにどう影響するかが分かれば十分です。この例では、余計な項目まで消えてしまうのは明らかに困るので、この指摘を採用します。並べ替えを追加するという提案は後回しにしてかまいません。どのみち削除の修正とは関係ないので。

"最初のバグを直して"が何を指すのか推測させずに済むよう、選んだ指摘をまるごとエージェントに渡してください。変更したあとで結果をもう一度確認するよう頼みましょう。これはチームの話の続きです。同僚が修正後のバージョンを見るのと同じです。

リクエスト3. 修正して結果をチェックする

REVIEW_CHECK.mdで確認された問題を直して:
1つの項目を削除すると、同じ名前の項目がすべて消える。
削除するのは選んだ項目だけにすること。同じ名前は許可する。
レビューで出たほかの提案は今は取り入れないで。

修正のあと、使える手段で項目の追加と削除をチェックして。
同じ名前の項目が2つある場合も含めて。
そのあと、独立したサブエージェントに修正後のコードを再レビューさせて:
原因が取り除かれたか、追加と削除の動きが壊れていないか。
元の要件と、修正している問題の説明をそのサブエージェントに渡して。

何が変わったか、どんなチェックを実行したか、
再レビューで何が分かったかを分かりやすく説明して。
チェックできなかったことがあれば、別に挙げて。
新しい改善でタスクを広げないで。

自分のプロジェクトで使うときは、買い物についての段落を、あなたのレポートで確認された指摘に置き換えてください。残りの流れはそのままでかまいません。修正、チェック、結果の独立した見直しです。

良い報告には具体的な内容があります。"各項目が個別に削除されるようになりました。同じ名前を2つ使ったチェックでは、2つ目の項目が残りました。再レビューでは、以前のバグの原因は見つかりませんでした"。こう書けるのは、実際にそのチェックをしたあとだけです。エージェントがコードを読んだだけなら、そのことを明記すべきです。

あなた自身がページを開いて、いつもの操作を試してみることもできます。それにはプログラミング言語の知識はいりません。これは目に見える結果についての追加のチェックです。修正の技術的なレビューは、引き続きエージェントの仕事です。エージェントが実行して確かめる手段が足りなかった場合、レポートには"確実に動きます"という約束ではなく、分かりやすい制約の説明が残ります。

毎回の見直しを終わりのない手直しにする必要はありません。選んだ問題が直り、チェックも済み、再レビューで関連するバグが見つからなければ、そのタスクは完了です。それだけです。新しい要望は、また別に話し合う価値があります。