1
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

Claude Code のスキルで PR レビューを段階に分けて、cmux で並列に回す

1
Posted at

複数のリポジトリをまたいで PR をレビューしていると、困りごとが2つ出てきます。

1つ目は、PR の進み具合を覚えておく手間です。レビューそのものより、次のような PR を覚えておくほうが大変になってきます。

  • 指摘を出して、作成者の返信を待っている PR
  • 返信が来ているのに、まだ確認できていない PR
  • 自分の PR に付いたコメントのうち、まだ返していないもの

2つ目は、レビューを待つ時間です。Claude Code に深くレビューさせると1件に20分以上かかることもあり、1件ずつ流すと待ち時間がそのまま積み上がります。

それぞれに、次の手を打ちました。

  1. 進み具合を覚えておく手間には、レビューの流れを段階に分けてスキルを用意し、次に起動するスキルを PR の状態から決めるようにしました
  2. 待つ時間には、cmux で PR 1件につきセッションを1つ立ち上げ、レビューを並列に回すようにしました

深いレビュー3件を同時に流したところ、約26分で3件そろいました。1件ずつ流すと、約74分かかる見込みでした。

この記事のねらいは、レビューは AI に同時に進めさせ、PR に投稿する指摘は人が選ぶことです。

ここでは、スキルの分け方と、cmux での並列実行を中心に書きます。hook や権限の設定など、体制を支えるほかの仕組みは付録にまとめました。

記事に出てくるリポジトリ名・PR 番号・指摘の内容は、すべて説明用の架空の例です。


🧰 使っているもの

# 使っているもの 役割
1 Claude Code レビューと投稿をするエージェント。手順はスキルとして持たせる
2 cmux PR ごとにワークスペースを作り、エージェントの入力待ちを知らせる
3 GitHub CLI(gh) PR の取得と、コメント・Approve の投稿
4 PR 一覧ツール 自作の TUI。担当リポジトリの PR を一覧にし、起動するスキルを決める

Claude Code の「スキル」は、手順を書いた Markdown を置いておくと /スキル名 で呼び出せる仕組みです。この記事の /review-pr などは、すべて自作のスキルです。

cmux は、AI のコーディングエージェントを複数動かす使い方に向けて作られた、macOS 用のターミナルです。

PR 一覧ツールは公開していません。中でやっていることは、4章でシェルのコードにして示します。

確かめた環境は macOS 26.7.3、Claude Code 2.1.323、cmux 0.65.2、gh 2.103.2 です。cmux のコマンドは 0.65.2 での書き方で、cmux workspace create は以前の書き方の cmux new-workspace と同じ指定を受け付けます。


🏗 全体像

1件の PR について、次の4つを繰り返します。

誰が何を受け持つか

Claude Code を中心にした PR レビュー体制のアーキテクチャ図

真ん中の Claude Code のセッションが PR 1件につき1つ動き、左の決めごとを読み、右の hook と権限の設定に守られながら進めます。画像をクリックすると、元の大きさで開きます。


🗺 1. レビューの流れを段階に分ける

PR が他人のものか自分のものかで、やることと順番が変わります。図の点線は、相手が動くのを待つところです。

1-1. 他人の PR

1-2. 自分の PR

1-3. 次にやることは PR の状態で決まる

待ちの間、セッションは閉じてしまって構いません。次の段階は新しいセッションで始め、続きに必要なものは GitHub と、保存しておいたファイルから取り直します。

どの段階に進むかは、PR の状態だけで決まります。PR 一覧ツールは、次の表の条件で起動するスキルを決めます。

# PR の状態 起動するスキル
1 他人の PR で、自分がまだコメントも Approve もしていない /review-pr
2 他人の PR で、自分のコメントに作成者が返信した /review-reply-status
3 他人の PR で、コメント済みだが返信がまだ無い 起動しない。確かめるものが無い
4 他人の PR で、自分が Approve 済み 起動しない
5 自分の PR で、返信も 👍 もしていないコメントが残っている /review-feedback
6 自分の PR で、まだ返していないコメントが無い 起動しない
7 閉じた PR、依存ライブラリを更新するボットの PR 起動しない

「次に何をやるか」は PR の状態から決まる。人が覚えておかなくていい。


🧩 2. 1つのスキルには1つの仕事だけ持たせる

スキルの中身は、手順を書いた Markdown です。たとえば、指定された番号の指摘だけを投稿するスキルは、冒頭がこうなっています。実物から社内の情報を抜き、短くしたものです。

---
name: review-comment-by-no
description: レビュー結果から、指定された番号の指摘だけを PR の該当箇所にコメントする。「No1 と No3 をコメントして」と言われたら使う。
allowed-tools: "Bash,Read,Write"
---

# 指定された番号の指摘を PR に投稿する

やることは1つ。レビュー結果から指定された番号の指摘を読み、該当箇所へ投稿する。Approve はしない。

番号の指定が無ければ中断し、どの番号を投稿するか確認する。全件は投稿しない。

用意したスキルは8つです。1つのスキルには、1つの仕事だけを持たせています。

# スキル 使う場面 やること PR への書き込み
1 /review-pr 他人の PR・1st レビュー 変更の規模でレビューの深さを決め、指摘を3つの重さに分けて報告する なし
2 /approve-lgtm 1st レビューで指摘なし 決まった形の Approve コメントを付けて Approve する Approve
3 /review-comment-by-no 指摘あり・直してから 指定された番号の指摘だけを、該当する行にコメントする コメント
4 /approve-review-comment 指摘あり・LGTM する 指摘をコメントしたうえで Approve する コメントと Approve
5 /review-reply-status 他人の PR・2nd 対応確認 自分の指摘への回答状況を分類し、修正済みの返信はコミットの差分と照合する なし
6 /approve-after-review 他人の PR・3rd Approve 指摘への返信、自分が立てたスレッドの Resolve、Approve を順に行う 返信・Resolve・Approve
7 /review-feedback 自分の PR・コメント確認 付いたコメントを集め、指摘ごとに番号を振った台帳を作る なし
8 /review-feedback-reply 自分の PR・返信・記録 台帳の番号ごとに対応方針と修正コミットを記録し、返信を投稿する 返信

指摘の重さは3つです。Critical は必ず直すもの、Important は直すことを勧めるもの、Suggestion は改善の提案です。

2-1. 読むスキルと、書くスキルを分ける

表の右端の列を見ると、スキルは2種類に分かれています。

  • 読むだけ: /review-pr、/review-reply-status、/review-feedback
  • PR に書く: 残りの5つ

読むだけのスキルは、何度実行しても、いくつ並列に走らせても、PR には何も起きません。4章の並列実行は、この分け方が前提になっています。

2-2. 指摘に番号を振り、人は番号で選ぶ

/review-pr は、見つけた指摘に No1、No2… と通し番号を振って報告します。人はそれを読んで、こう指示します。

No1 と No3 を該当箇所にコメントして

選んだ指摘は、修正の案のコード例も付けて、該当する行にコメントします。コード例が無い指摘には、直し方の方針を書きます。

的外れな指摘や、今回は言わなくてよい指摘も混ざるので、人が読まずに投稿はしません。/review-comment-by-no は、番号の指定が無ければ何も投稿せずに止まります。

/approve-review-comment だけは、番号を省くと全件を投稿します。このスキルを番号なしで呼ぶこと自体が、全件を出すという人の判断になります。

2-3. 結果はファイルに残し、次のスキルがそれを読む

# 書くスキル 残すもの 読むスキル
1 /review-pr レビュー結果の Markdown と HTML /review-comment-by-no、/approve-review-comment
2 /review-reply-status 回答状況の JSON と HTML /approve-after-review
3 /review-feedback 指摘の台帳の Markdown と HTML /review-feedback-reply

1-3 で、待ちの間はセッションを閉じてよいと書きました。それができるのは、続きに要るものを会話ではなく、このファイルに残しているからです。


🔍 3. 読むスキル3つの工夫と出力

読むだけの3つのスキルは、結果を HTML にしてブラウザで開きます。スキルごとに、工夫したところと、架空の PR での出力の例を示します。

3-1. /review-pr: 小さな PR は軽く、それ以外は深く

PR の大きさと中身で、レビューの深さとサブエージェントの数を変えます。上の行から順に当てはめます。

# PR レビュー 読むサブエージェント
1 コードを含まない Draft や RFC などの設計文書 軽い 設計・DB層の1つ
2 変更が2ファイル以下で、追加と削除の合計が30行以下 軽い 設計・DB層と実装・品質層の2つ
3 それ以外 深い 壊れる経路・仕様との食い違い・データ層の3つ

1行目の PR には実装のコードが無いので、コード品質・テスト品質・API 設計・パフォーマンスとセキュリティの4つの観点は外します。

深いレビューの観点は9つあり、それを3つの担当に分けています。

# 担当 掘るところ 受け持つ観点
1 壊れる経路 回帰・データの破損・例外・並行実行・境界値 コード品質、テスト品質、パフォーマンスとセキュリティ
2 仕様との食い違い PR の意図・宣言した契約・呼び出し元・隣のモジュール アーキテクチャ準拠、DDD と設計パターン、API 設計、リポジトリの責務
3 データ層 SQL・DDL・インデックス SQL とインフラ層、DB 設計の規約

1つのサブエージェントに9つの観点をすべて任せると、どの観点も浅いまま終わります。担当を絞ると、深さの要る確かめまで届きます。たとえば壊れる経路の担当には、壊れる入力を1つ挙げさせ、結果まで追って書かせます。メインのエージェントが3つの結果をまとめ、内容を確かめてから報告します。

出力の例です。注文一覧 API にカーソル方式のページ送りを足す、架空の PR #128 をレビューした結果です。

No レベル 指摘 該当箇所
1 Important 同じ時刻の注文を取りこぼす OrderQueryService.java:88
2 Suggestion README への追記漏れ README.md:42
3 Suggestion 上限件数が2か所にある OrderController.java:31

実際の画面では、上にリポジトリ・タイトル・マージ先と、PR が必要な理由・PR で解決することが並びます。指摘ごとに、修正にかかる手間と放置したときのリスクも出します。詳細と修正の案は、折りたたみの中に入れています。

修正の案は、どの指摘にもコード例か明確な方針まで書かせます。「改善してください」で終わる案は、報告の前にメインのエージェントが見つけ、具体的な案に直します。

3-2. /review-reply-status: 「修正しました」をコミットの差分と照合する

対応確認のスキルは、作成者の返信を読んで分類するだけでは終わりません。「修正しました」と書かれた指摘は、返信と対になるコミットの差分を開き、指摘した箇所が実際に変わっているかを確かめます。

返信の内容と、差分で確かめた結果は、別々の列に出します。「対応済みと書いてあるのに、差分が見つからない」という状態を、そのまま見えるようにするためです。

出力の例です。3-1 の PR #128 に付けた3件の指摘に、作成者が返信したあとの画面です。

No 指摘 状況 差分との照合 次にやること
1 同じ時刻の注文を取りこぼす ✅ 対応済み 一致 a1b2c3d 返信して閉じる
2 README への追記漏れ ⏭️ 見送り — 了承する
3 上限件数が2か所にある 💬 議論中 — 返信が要る

/approve-after-review はこの結果を読み、次のような指摘が1件でもあれば、Approve に進まずに止まります。この例では No3 が議論中なので止まります。

  • 返信がまだ無い指摘
  • 議論が続いている指摘
  • 対応済みと書かれているが、差分と合わない、または対になるコミットが見つからない指摘

3-3. 指摘は3か所から集める

GitHub では、指摘が書かれる場所が3つあります。/review-reply-status と /review-feedback は、3か所とも読みます。

# 場所 見落としやすさ
1 行に付くインラインのスレッド 低い
2 レビューの本文。Approve の本文も含む 高い
3 会話タブのコメント 高い

以前の /review-reply-status は、インラインのスレッドしか取得していませんでした。そのため、Approve の本文にまとめて書かれた改善提案4件を丸ごと見落とし、「作成者側のアクションは残っていません」と報告したことがあります。「LGTM です。改善提案が4件あります」という形のレビューは、インラインだけを見ると指摘が0件に見えるからです。

3-4. /review-feedback: 番号は一度振ったら変えない

自分の PR に付いた指摘の台帳は、同じ PR で何度でも作り直します。そのたびに番号がずれると、前に「No3」で指していた指摘が、別のものに入れ替わってしまいます。そこで、番号は一度振ったら変えません。

同じ指摘かどうかは、コメントの URL で見分けます。新しい指摘には、今ある番号の最大値の次を振ります。欠番は詰めず、消されたコメントも行を残して、状況を「原文削除」にします。状況の列だけは前回の値を引き継がず、毎回 PR の現状から判定し直します。

出力の例です。「判断」の列には、スキルが PR の作成者の立場でコードを確かめ、この PR で直すか、別の PR に回すか、直さないかの案を入れます。

No 状況 指摘 判断
1 🔵 返信済み リトライが上限に達したあとの扱いが未定 対応不要
2 🟠 未対応 在庫が0件のときのテストが無い この PR で対応
3 🟢 解決済み 設計書の処理フローに新しいジョブが無い 別の PR で対応

⚡ 4. cmux で並列に回す

ここからが後半です。スキルの仕事を分けたので、あとは PR ごとに別のセッションで同時に走らせるだけです。

4-1. cmux で使う機能

# cmux の機能 並列のレビューで効くところ
1 CLI からワークスペースを作れる PR 一覧ツールが、PR の数だけセッションを起動できる
2 サイドバーにワークスペースの名前が縦に並ぶ どの PR のセッションかが名前で分かる
3 エージェントが入力待ちになると知らせる レビューが終わったセッションに気付ける

4-2. PR 1件 = ワークスペース1つ = セッション1つ

ワークスペースの名前は <何をするか> <リポジトリ名>#<PR番号> の形にして、サイドバーで見分けられるようにします。

PR 一覧ツールでキーを1つ押すと、画面に出ている PR すべてについて、1-3 の表で起動するスキルを決め、まとめて起動します。中でやっていることをシェルで書くと、次のようになります。ここでは簡単のため、3件とも /review-pr で起動しています。

prev=""
for url in \
  https://github.com/fictional-org/order-api/pull/128 \
  https://github.com/fictional-org/order-api/pull/131 \
  https://github.com/fictional-org/stock-batch/pull/57
do
  repo=$(echo "$url" | cut -d/ -f5)
  num=${url##*/}

  # 同じリポジトリを続けて起動するときだけ、15秒空ける
  [ "$repo" = "$prev" ] && sleep 15
  prev=$repo

  # --name: サイドバーに出る名前
  # --cwd: Claude Code を起動するディレクトリ。CLAUDE.md を置いた場所にする
  # --env: プロンプトを環境変数で渡す
  # --command: 最初に実行するコマンド。プロンプトは環境変数から読む
  # --focus false: 画面を切り替えずに裏で起動する
  cmux workspace create \
    --name "review ${repo}#${num}" \
    --cwd "$HOME/work/review" \
    --env "REVIEW_PROMPT=/review-pr ${url} を実行して" \
    --command 'claude --permission-mode auto "$REVIEW_PROMPT"' \
    --focus false
done

成功すると、1件ごとに OK workspace:<番号> が返ります。

プロンプトは --command に直接書かず、--env で渡しています。--command を英数字と記号だけにしておくと、文字コードとクォートの入れ子を気にしなくて済みます。

--permission-mode auto を付けると、確認のたびに止まらずに進みます。確認なしで進むので、PR の状態から選んで自動で起動するのは、PR に書き込まない読むだけの3つのスキルに限っています。

4-3. 並列でぶつからないための決めごと

同時に走らせると、1件ずつのときには起きなかった衝突が起きます。

# 決めごと 理由
1 PR ごとに git worktree を作る 1つの clone でブランチを切り替えると、他のセッションが読んでいるファイルが変わる
2 同じリポジトリの起動は15秒空ける 各セッションが共有の clone で git fetch する。同時に走るとロックで失敗することがある
3 結果のファイル名にリポジトリ名と PR 番号を入れる 全セッションが同じ場所に書く。PR 番号だけだと、別のリポジトリの同じ番号とぶつかって黙って上書きされる
4 起動したワークスペースを PR の URL と対で記録する そのワークスペースが開いている間は、同じ PR をもう一度起動しない
5 ワークスペース1つにセッションは1つ 名前はワークスペース単位。2つ入れると、何のセッションかが名前で分からなくなる

4番の記録は、起動の前に cmux --json workspace list の結果と突き合わせます。閉じられたワークスペースの分は記録から消すので、ワークスペースを閉じた PR はもう一度起動できます。

4-4. 起動できたかを確かめる

OK が返っても、中のエージェントが動き出したとは限りません。起動に失敗したワークスペースを残すと、記録の上では「起動済み」のままになり、次の一括起動から外れてしまいます。PR 一覧ツールは中のエージェントの様子までは見ないので、起動のあとは手で次のコマンドを打って確かめます。

# ワークスペースの中身を見る
cmux tree --workspace workspace:12

# 画面に出ている文字を読む
cmux read-screen --workspace workspace:12 --lines 12

# 失敗していたら閉じる
cmux workspace close workspace:12

cmux tree に出るタイトルがディレクトリのパスのままなら、Claude Code は動き出していません。read-screen では、渡したプロンプトの文字が化けていないかを見ます。失敗していたら、ワークスペースを閉じてから起動し直します。


⏱ 5. 測ってみた

深いレビュー3件を同時に起動して、結果のファイルができるまでの時間を測りました。

# PR 変更の規模 結果が出るまで
1 A 4ファイル・385行 約23分
2 B 4ファイル・801行 約25分
3 C 3ファイル・79行 約26分

行は追加と削除の合計です。C は行数が少ないものの、確かめ直しが2回入りました。

3件そろうまで約26分でした。1件ずつ流して測ってはいないので、3件の時間を足した約74分を目安にしています。

並列にしても、使うトークンの量は減りません。短くなるのは人の待ち時間です。


🔚 まとめ

やったことを並べます。

  • レビューの流れを段階に分け、1つのスキルには1つの仕事だけを持たせた
  • 読むだけのスキルと、PR に書くスキルを分けた
  • 指摘に番号を振り、投稿するものは人が番号で選ぶようにした
  • 結果をファイルに残し、セッションを閉じても続きを始められるようにした
  • 次に起動するスキルを PR の状態から決め、cmux で PR ごとに並列に走らせた

いちばん変わったのは、時間よりも人の動き方でした。

  • 一覧でキーを1つ押して、別の作業に戻る
  • 入力待ちの知らせが出たワークスペースから順に開く
  • 画面を読み、投稿する指摘を番号で選ぶ

レビューが終わるのを画面の前で待つ時間が無くなりました。

AI に任せる範囲を広げるほど、「どこで人が決めるか」を先に決めておくことが効いてきます。
読むところは並列に任せ、書くところは人が番号で選ぶ。この線を引いたことで判断のみに集中して作業効率がよくなり、並列化して作業が増えてもタスクを回せるようになりました。

PR レビューが溜まりがちな方の参考になれば嬉しいです。


📎 付録

付録1. 体制を支えるほかの仕組み

構成図に出てくる仕組みを、表にまとめます。

# 使っている仕組み この体制での使い方
1 CLAUDE.md とガイドライン 起動時に必ず読み込む決めごと。操作の安全・進め方・伝え方を書く
2 役割の定義 レビュアーと PR の作成者で、使えるスキルを分ける
3 スキル 段階ごとの手順。必要になったときにだけ読み込む
4 サブエージェント 9つの観点を3つの担当に分け、並列で差分を読む
5 hook 危険な git 操作の拒否、リポジトリの規約の差し込み、応答の検査
6 権限の設定 強制 push などを設定で拒否する
7 ナレッジ 過去の失敗の記録。決めごととスキルに反映していく

AI に守らせたいことは、文章で頼むだけにせず、hook と権限の設定で止めています。

付録2. 1件のレビューを投稿するまでの流れ

他人の PR を1回レビューして、指摘を投稿するまでの流れです。色の付いた範囲は、PR ごとのセッションが並列に進めます。

1
0
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
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?