付録C cross review を手元で回すスキル — codex-cross-review と gh-review-loop

第3章のレビューループ(指摘のトリアージ → 修正 → push → 再レビュー)は、毎回手で指示することもできますが、手順そのものを Claude Code の「スキル」にしておくと、/コマンド 一発で回せるようになります。この付録では、実際に運用されている2本のスキルを紹介します。

そもそもスキルってなに？

スキル(skill)は、Claude Code に渡す「手順書」です。~/.claude/skills/<名前>/SKILL.md(自分専用)または .claude/skills/<名前>/(プロジェクト共有)にマークダウンで手順を書いておくと、/名前 で呼び出せます。

CLAUDE.md との関係はこうです — CLAUDE.md が「常に守るルール」なら、スキルは「特定の作業のときだけ読む手順書」。第1章で見た「段階的開示」(本文を太らせず、詳細は必要なときだけ読む)の、実行版です。

<!-- SKILL.md の骨格 -->
---
description: いつ使うスキルか(Claude がこれを読んで起動判断する)
---

# スキル名

手順を、人間の新人に渡す手順書と同じ調子で書く。
コマンド例・判断基準・やってはいけないこと・終了条件。

2本のスキル — 同じプロトコルの「攻め」と「受け」

紹介する2本は、第3章で導入した判定マーカー(CODEX VERDICT: LGTM / CHANGES REQUESTED)という共通プロトコルの両側を担当します。

  /codex-cross-review(攻め) /gh-review-loop(受け)
レビューを 自分から起こす(手元で codex CLI を起動) 受け取る(CI のボットが投稿したものを読む)
前提 codex CLI が手元に入っていればよい リポジトリに CI レビューボット(付録B)や CodeRabbit(付録A)がいること
向く場面 ボット未整備のリポジトリ、マージ前の念入りチェック ボットが常駐しているリポジトリの日常運用

/codex-cross-review — 二者レビューの収束ループ

PR の URL か番号を渡すと、Codex(別会社のAI)と Claude(自分)の2人のレビュアーが合意するまでループを回します。

① PR を checkout し、CLAUDE.md(プロジェクトのルール)を読む
② codex exec でレビューを依頼(最後に必ず VERDICT を出す契約つき)
③ Claude が指摘を1件ずつ自分の目で評価:
     - 必要性: 本物のバグ? 好み? 誤検知?
     - 波及範囲: 同じ問題が他の場所にもないか横展開で検索
     - 副作用: その修正は呼び出し元を壊さないか
     - 見落とし: Codex が見ていない問題を自分でも探す
   → MUST-FIX / 妥当なnit / 誤検知 / 先送り に分類
④ 修正 → format・lint・typecheck・build・test を全部通す
   → main を取り込んでから push(誤検知には理由を返信)
⑤ ②へ戻って再レビュー。
   終了条件: Codex が LGTM+Claude 自身もOK+CI緑 → 人間に確認してマージ

設計上の安全装置がよくできています:

  • 最大5周の上限 — 収束しないレビューは人間の出番、と割り切る
  • 1周ごとに状態ファイルへ記録 — ループが暴れたとき事後検証できる
  • Claude 自身の「OK」の定義が明文化されている — 「Codex が何も言わなかった」では不十分。MUST-FIX ゼロ・checks 全通過・変更に見合うテストがあること、まで満たして初めて OK
  • 誠実性のルールまである — 「Codex が見落とした問題を自分が見つけたら、Codex の指摘のふりをせず、自分の発見として正直にコミットメッセージに書く」

/gh-review-loop — ボットの合唱をさばく係

こちらは逆向きです。push すると CI 側で複数のレビュアー(付録Bの codex workflow、CodeRabbit、Sourcery…)が勝手にレビューを投稿してくる環境で、その全部をさばいて収束させます。

① push 後、各ボットのレビュー完了を待つ
   (codex は workflow の完了を検知、CodeRabbit は少し待つ、など待ち方もボット別)
② 今回の push に対する新しいコメントだけを収集
   (ボットごとの投稿者名の癖、古いコメントとの区別もスキルが知っている)
③ 定型ノイズ(要約・ポエム・rate limit 通知)を捨て、実質的な指摘だけ残す
④ トリアージ(第3章の分類そのまま)→ 修正 → どのボット対応か分かる名前で commit → push
⑤ ボットが再レビュー。全ボット LGTM + CI 緑 + 人間の確認 → マージ
   最後に「対応した指摘 / 意図的に見送った指摘」のまとめコメントを PR に投稿

このスキルの価値は、ボットごとの実務知識が焼き込まれていることです。「CodeRabbit は rate limit で沈黙することがある(=今回はレビューなしとして扱う)」「ボット同士は矛盾する提案をする(=両方を機械的に満たそうとしない)」「codex が2つの名義で投稿することがある」— こうした細部は口頭で毎回説明できる量ではなく、スキルという形にして初めて運用に乗ります。

2本に共通する設計原則

自分でレビュー系スキルを作るときは、この5つを外さないでください(第3章の原則が、スキルとして固定化されたものです):

  1. 機械可読な合意点を決める — 判定マーカーがないと「終わったかどうか」を機械が判断できず、ループが自動化できない
  2. 回数の上限を切る — 収束しないループは人間にエスカレーション。無限ループと無限課金を防ぐ
  3. 盲信しない — AI レビュアーの指摘は必ず評価してから適用。誤検知には理由を返す(黙って無視すると次の周でまた指摘される)
  4. 修正のたびに全チェック — 赤いビルドを push するとレビュアー(人もAIも)の前提が壊れる
  5. マージの最終判断は人間 — スキルは「マージしてよい状態」までを作り、ボタンは人間が押す

合わせて読む