claude-code-review

name	claude-code-review
description	/claude-code-review で明示的に呼ばれたとき、または他スキルがこのスキル名を指定して委譲したときにのみ使う。通常のコードレビュー依頼では発火しない。
argument-hint	[branch] [--fix] [--crit]

claude-code-review

@aki77/claude-code-review CLI を pnpx 経由で実行し、レビュー結果を人間可読な サマリとして受け取るスキル。このスキルは local（作業ツリーの未コミット変更）専用。

• 引数なし: 未コミット変更があればそれを、全てコミット済みなら base ブランチとの 差分を CLI が自動でレビューする。レビューを 1 回実行し、結果を報告して終了する。 修正は行わない。
• ブランチ名を指定: 引数のうち --fix を除いた最初の非フラグ語をブランチ/範囲指定と みなし、そのブランチとの差分をレビューする。
• --fix 付き: 確認された（confirmed）指摘が 0 件になるまで、レビューと修正を 自動で往復する（後述の修正ループ）。--range 相当の指定と併用でき、その場合は 同じ範囲を 0 件になるまで直す。
• --crit 付き: レビューを 1 回実行し、結果を crit のインラインコメントとして 流し込んでから crit のレビュー画面を開く（後述の crit 連携）。修正は行わない。 crit 上で人間がレビューし、その指摘に応じて対応する。--fix とは独立したモードで、 併用は想定しない（--crit 指定時は crit 連携フローを優先する）。

このツールは「LLM は意味判断のみ、位置解決・検証・フィルタはコードで行う」設計で、 最終サマリに残るのは検証ステップを通過した confirmed 指摘だけ。だから残った指摘は 「たぶんバグ」ではなく「検証済みの実在する問題」として扱ってよい。

--fix なし: レビューのみ

pnpx @aki77/claude-code-review -- local を 1 回実行し、サマリをそのまま報告する。 confirmed 指摘があっても修正はせず、内容をユーザーに提示して終わる（次にどうするかは ユーザーの判断に委ねる）。

--crit あり: crit 連携（--crit 指定時のみ）

--crit が指定されたときだけ、次のフローに入る。レビュー結果を crit のインライン コメントとして流し込み、crit のレビュー画面を開いて人間のレビューに委ねる。修正ループ （--fix）とは独立したモードで、レビューは 1 回だけ実行する。

CLI に --crit を渡すと、サマリではなく [{file, line, body}] の JSON 配列を標準出力に 出す（crit comment --json がそのまま受け取れる形式）。body は pr --comment の PR インラインコメントと同一（カテゴリ/重要度バッジ ＋ 説明文 ＋ GitHub 形式の suggestion フェンス）で、crit のレビュー画面で suggestion をそのまま取り込める。

手順

1. CLI を --crit 付きで実行し、出力を crit comment --json にパイプで渡す。 スキルに渡されたブランチ/範囲指定があれば --range <その語> も付ける。

   pnpx @aki77/claude-code-review -- local --crit | crit comment --json --author code-review
   

   • crit comment が Added N comments と返せば投入成功。指摘が 0 件なら空配列 （[]）が渡り、コメントは追加されない（その旨を報告して終了）。
   • --crit 指定時は投稿用と同じ本文生成（LLM 呼び出し）が走るため、通常の レビューより時間とコストがかかる。実行前にその旨をユーザーに一言伝える。

2. crit のレビュー画面を開く。crit コマンドを直接叩くのではなく、crit スキル （/crit）を引数なしで呼ぶ。crit スキルが git の変更を自動検出してレビュー画面 （ローカルサーバ＋ブラウザ）を開き、手順1で投入したコメントもそこに表示される。 以降のレビュー往復（コメントへの返信・対応・ラウンド継続）は crit スキルの手順に 従う。

3. このスキルの役割は「レビュー結果を crit に流し込んで画面を開くまで」。crit 上での 人間レビューへの対応は crit スキル側に委ねる。

--fix あり: 全体の流れ（指摘が 0 になるまで繰り返す）

--fix が指定されたときだけ、次のループに入る。confirmed 指摘が 0 件になる（または 進展が止まる／ユーザー判断待ちの指摘だけが残る）まで、レビューと修正を自動で往復する。

loop:
  1. pnpx @aki77/claude-code-review -- local を実行
  2. exit 0（指摘なし）        → 完了。0 件になった旨を報告して終了
  3. exit 1（confirmed あり）  → サマリを読む
       - 安全に直せる指摘は直す
       - ユーザー判断が必要な指摘が残る   → ループを止めて相談（後述）
  4. それ以外の非0（2・130）  → サマリは出ていない。stderr の error: を読んで
       ユーザーに相談し、修正・ループには進まない
  5. 進展があれば 1 に戻って再レビュー、なければ止めて報告

なぜ再レビューするか: 修正が新たな問題を生む／不完全なことがあるため、直したら 必ずもう一度 CLI にかけて「本当に消えたか」を機械検証させる。人間の目視で 「直したはず」と判断して終わらせない。

各ラウンドの実行

サブコマンド引数を渡すには -- 区切りが必須（README 準拠）。

pnpx @aki77/claude-code-review -- local

ブランチ/範囲指定がある場合は --range を付ける:

pnpx @aki77/claude-code-review -- local --range <branch>

実行前に確認すること:

• カレントディレクトリがレビュー対象のリポジトリルートであること。 そうでなければ 移動してから実行する。
• 引数の解釈: スキルに渡された引数のうち --fix / --crit を除いた最初の非フラグ語が あれば、それをブランチ/範囲指定として --range <その語> に渡す。無ければ --range を 付けずに実行する（未コミット変更があればそれを、全てコミット済みなら base 差分を CLI が 自動でレビューする）。--crit が指定されていれば、レビュー実行はこの節ではなく 「--crit あり: crit 連携」の手順に従う（CLI に --crit を付けて crit にパイプする）。

実行にはそれなりに時間がかかる（複数の LLM エージェントを並列起動する）。最初の ラウンドを始める前に、レビューを開始した旨をユーザーに一言伝えてから待つ。 --fix が指定されているときだけ「指摘が 0 になるまで回す」ことも併せて伝える。 --fix なしのときは 1 回のレビューで終わる旨を伝え、ループを示唆する文言 （「0 になるまで」「自動で繰り返す」等）は含めない。--fix ありの場合、2 ラウンド目 以降も再レビューに入るたびに何ラウンド目かを簡潔に伝える。

終了コードと結果の読み方

• exit 0: confirmed 指摘なし（サマリに「問題は見つかりませんでした」と出る）。 --fix ループのゴール。 修正は不要。0 件で終わった旨を報告して終了。
• exit 1: confirmed 指摘が 1 件以上ある（local の既定挙動）。唯一「1」を返す ケース。 --fix 指定時は修正フェーズへ進む。--fix なしならここでサマリを報告して 終了する。
• exit 2: レビュー自体の失敗（例外）または引数エラー。stdout にサマリは出ない （printSummary は成功パスでしか呼ばれない）。サマリを探しに行かず、stderr の error: <message> を読んでユーザーに相談する。指摘の修正・ループ継続には進まない。
• exit 130: Ctrl+C による中断。exit 2 と同様、サマリは出ていない。

exit 1 は「失敗」ではなく「指摘あり」を意味する CI 向けシグナルなので、コマンドが exit 1 で終わっても慌てず、まずサマリ本文を読む。exit 1 以外の非0（2・130）では サマリは読まず、stderr のエラーメッセージを確認する。

サマリの形式（stdout、プレーンテキスト）

指摘は次の 2 行構成のブロックで出力される（JSON ではない。テキストを読んで解釈する）。

🐛 Bug 🔴          ← カテゴリバッジ + 重要度バッジ
📍 src/foo.ts:42  タイトル

  指摘本文（修正提案を含むことがある）

• カテゴリ: 🐛 Bug / 🔒 Security / ⚡ Performance / 📋 Rule
• 重要度: 🔴 critical / 🟠 high / 🟡 medium / ⚪ low
• 位置が path:line なら行が確定済み。（行番号未確定） の場合は本文から該当箇所を 自分で特定する。
• rejected / unverified として列挙された項目は修正対象ではない（検証で棄却された、 または未検証）。confirmed の指摘（検出 N 件 に含まれるもの）だけを直す。
• 「レビュー対象外」に挙がったファイルは CLI が読んでいないので、指摘の根拠にしない。
• 「未コミット変更なし → base 差分（...）をレビューしました」という行が出た場合は、 引数なし実行で全てコミット済みだったため CLI が自動的に base ブランチとの差分に 切り替えたことを示す（異常ではない、そのまま結果を読めばよい）。

修正フェーズ（--fix のときのみ）

confirmed 指摘を上から重要度順（critical → high → medium → low）に直していく。

1. 各指摘について、まず該当ファイル・該当行を Read で開いて指摘内容が現状のコードに 実際に当てはまるか確認する（サマリの位置情報を鵜呑みにしない）。
2. 明確な修正は適用する。ツールが本文に載せた suggestion は参考にしつつ、周辺コードの 実際の文脈に合わせて自分で正しい修正を書く。丸写ししない。
3. テスト・lint などの検証は、そのリポジトリで普段行う範囲で必要に応じて実行する （やり方はプロジェクトの流儀に従う）。

ユーザーの判断が必要なときはループを止める（重要）

すべての指摘を機械的に直すのではなく、次に当てはまる指摘は修正せずにループを止め、 その指摘の内容と考えられる対応案を提示してユーザーの判断を仰ぐ。バグ・軽微で意図が 明白な修正は止めずにそのまま直してよい。

止めて確認すべきケース:

• 設計・仕様の選択を伴う指摘（インターフェース変更、データ構造の変更、責務の再配置など、 「どう直すか」に複数の妥当な選択肢がある）。
• 破壊的・広範囲な変更（公開 API・スキーマ・設定フォーマットの変更、多数のファイルに 波及する変更、外部から観測される挙動が変わる変更）。
• 指摘の意図や前提が不明で、修正すると別の意図を壊しかねないもの。
• 修正が既存の意図的な挙動と矛盾して見えるもの（コメントや設計原則と食い違う指摘は、 勝手に直す前にユーザーに確認する）。

このループの停止ポリシー: 安全に直せる指摘は先に片付けてから、判断待ちの指摘が 残ったところでループを止める。0 件到達を無理に急がない。止めるときは「どの指摘を、なぜ ユーザー判断待ちにしたか」「取りうる対応案」を簡潔に示し、ユーザーの返答を待ってから 再開する。

進展がないときも止める（無限ループ防止）

再レビューの結果が前ラウンドと実質的に同じ（confirmed 件数が減らない、かつ内容も 変わらない）場合は、同じ指摘を直せていないか、CLI が同じ箇所を繰り返し検出して いる可能性が高い。回数の固定上限は設けないが、進展が止まったらループを続けず停止し、 「どの指摘が残り続けているか」「なぜ自動で消せないと判断したか」を報告してユーザーに 委ねる。同じ修正を延々と試し続けない。

完了時の報告（--fix のときのみ）

ループを抜けたら、抜けた理由に応じて報告する。

• 0 件到達で終了: すべての confirmed 指摘が解消され、再レビューでも 0 件だったことを 伝える。各ラウンドで何を直したかを簡潔にまとめる。
• ユーザー判断待ちで停止: 直した指摘・判断待ちにした指摘を区別し、判断待ちの各件に ついて対応案を添えて相談する。
• 進展なしで停止: 残っている指摘と、自動で消せないと判断した理由を示す。

いずれの場合も、検証を実行したならその結果を、していないならその旨を、事実のまま報告する。