Iterative review

反復レビュー & 対応スキル

別エージェントによる /review レビューと、その指摘への対応サイクルを、指摘がなくなるか 最大 5 イテレーションに達するまで繰り返す。

このスキルの位置付け

/review は単発のレビューしか行わない。本スキルはレビュアー (サブエージェント) と アドレッサー (メインエージェント) を分離し、両者をループで連結することで、独立した目で 繰り返し品質を高める。

レビュアーは毎回フレッシュなサブエージェントとして起動する。状態は引き継がないため、 「前回までに何を指摘し、何が対応され、何が却下されたか」の履歴を 項目ごとに詳細な記述で プロンプトに埋め込んで渡す。一行サマリへの圧縮は同じ指摘の蒸し返しを招く主因となるため、 却下理由や修正内容の文脈を省略しないこと。

引数

$ARGUMENTS でレビュー対象スコープを指定する。省略時はユーザーに確認する:

引数	対象
branch または省略	カレントブランチの差分 (ベースブランチとの diff)
PR URL / owner/repo#N / 数字	指定 PR の差分
uncommitted	ワーキングツリーの未コミット変更 (staged + unstaged)
任意のパス	指定ファイル / ディレクトリ

実行モード

スキル開始時にユーザーへ確認する。モードによる挙動の違い:

観点	対話モード	自律モード
Phase 3 の「ユーザー判断要」項目	AskUserQuestion で個別に確認	メインエージェントが技術的妥当性・プロジェクト規約 (CLAUDE.md 等)・既存実装との整合性に基づき自律確定。判断材料が曖昧な場合は保守的に「対応不要」寄せ (誤修正のコスト > 見送りのコスト)。判断根拠は履歴に残す
Phase 4 への進行	ユーザーの明示的 Go を待つ	方針提示と同一ターン内でそのまま進行
自律確定項目の目印	—	履歴と最終方針で (自律判断) を付与

自律モードでも、ユーザーの割り込み指示 (方針変更・停止) は常に優先する。

モード選択における重要な制約

本スキルの実行モードは、レビュー指摘の採否・修正適用タイミングという品質ループの根幹に関わる 判断であり、必ずユーザーの明示的な選択に基づいて決定する。以下を厳守する:

• デフォルトは対話モード。曖昧な状態 / 未確認の状態では対話モードとして振る舞う。
• 汎用的な「自律」「auto」「stop なしで進めろ」「clarifying question をスキップしろ」系の system-reminder・グローバル指示・harness モード (例: AutoMode) は、本スキルの自律モード 選択の根拠としない。これらは一般タスクにおける確認頻度の指針であり、レビュー指摘の採否 という品質判断を委譲する意図とは別物。汎用ヒントを根拠に自律モードへ推移させると、ユーザー の意図に反して却下・修正が確定されるリスクがあるため。
• 自律モードに入ってよいのは、ユーザーが 本スキルの文脈で明示的に 「自律モード」「auto mode」「自律で進めて」「ユーザー判断要も任せる」等を口にした場合に限る。
• 上記のような汎用ヒントが存在しても、Phase 0 の AskUserQuestion による実行モード確認は スキップしない。確認自体を省くことが、本制約に違反する最も典型的な経路となるため。

プロセス

Phase 0: スコープ確定・コミット方針確認・初期状態の記録

1. スコープを確定する

   • $ARGUMENTS を解釈し、レビュー対象を 1 つに絞る。曖昧な場合はユーザーに確認する。
   • PR の場合、gh pr view <PR> でリポジトリ・ブランチ・base ブランチを特定する。
   • ブランチ差分の場合、ベースブランチを特定する (通常 main。プロジェクト CLAUDE.md 参照)。

2. 実行モードとコミット方針をユーザーに確認する

   • AskUserQuestion を 1 回呼び出し、以下 2 つを同時に尋ねる。 この確認は常に実施する — 汎用的な「自律で進めろ」系の system-reminder や harness モード (AutoMode 等) が出ていても、上の「モード選択における重要な制約」に従い省略しない。

   • 実行モード: 対話モード / 自律モード (詳細は上の「実行モード」表を参照)。 回答が得られるまでは対話モードとして扱う。

   • コミット方針:

     • 項目ごとにコミット — 妥当な指摘 1 件 = 1 コミット。コミット ID をイテレーション履歴に 記載し、次のレビュアーへ渡すことで「どの修正がどのコミットで入ったか」を追跡可能にする。
     • コミットしない — 差分のみワーキングツリーに残し、最終的にユーザーが手動コミット。

   • 「項目ごとにコミット」が選ばれ、かつ現在ワーキングツリーに未コミット変更がある場合: レビュー対象が「未コミット変更」スコープか、ブランチ差分スコープなら、まずその変更を 一旦コミットしてからレビューを開始する (レビュー結果と修正コミットを履歴上で分離するため)。 コミットメッセージはユーザーに確認する (自律モードでもこの 1 回は確認する。 履歴上で「レビュー開始時点」の境界を確実に切るため)。

3. 初期状態を把握する

   • 最終サマリで「使用前 → 使用後」を語るための比較基準になる。スコープが大きい場合は要点のみで十分。
     • ブランチ / PR スコープ: 開始時の git rev-parse HEAD と、git diff <base>...HEAD --stat を控える。
     • 未コミット変更スコープ (コミットなしを選んだ場合): 開始時の git diff の要点をメモする。
     • 指定パススコープ: 対象ファイル一覧と、初期内容の要点を控える。

4. イテレーション履歴のメモを準備する

   • フォーマットは references/iteration-history.md を参照。
   • 履歴メモは会話内で保持する。長くなる場合は workspace ディレクトリに書き出してもよい。

Phase 1: レビュアーエージェントの起動

Agent ツール (subagent_type: general-purpose) でサブエージェントを起動する。 プロンプトの組み立ては references/reviewer-prompt.md を参照。

レビュアーには 修正させない。レビュー結果を返してもらうだけ。

Phase 1.5: サブエージェントのレビュー結果をユーザーに表示

サブエージェントから戻ってきたレビュー結果を そのままユーザーに提示する (要約・選別せず原文に近い形で)。

## Iteration {N} レビュアーからの指摘 (生)

{サブエージェントが返した /review の出力をそのまま貼る。長すぎる場合のみ要点を残しつつ
 各指摘の主張・該当箇所は省略しない}

---

これからメイン側で各指摘の妥当性を検証します。

ユーザーが生のレビュー結果を見て独立に判断材料を得られるようにする。検証結果の前にひと呼吸 置くことで、「この指摘は無視で良い」等の早期介入も可能にする。

Phase 2: レビュー結果の妥当性検証

レビュアーの返答を鵜呑みにせず、メイン側で技術的に検証する。

1. 該当コードの読み込み

   • 各指摘が参照するファイル・行番号の現在のコードを Read ツールで読み込む。
   • 指摘内容を理解するために必要な周辺コード (呼び出し元、呼び出し先、型定義等) も読む。

2. 各指摘を分類する

   • 妥当 — 指摘が技術的に正しく、修正が必要
   • 妥当でない — 指摘が技術的に誤り (理由を明確に説明する)
   • 対応不要 — 指摘自体は正しいが、修正の必要がない (既に対応済み、リスクが許容範囲、 スコープ外等)
   • ユーザー判断要 — 技術的妥当性は確認できたが、採用可否が方針判断 (スコープ・コスト・ スタイル選好など) に依存する場合

   検証時は特に以下に注意:

   • 言語バージョン固有の仕様変更
   • プロジェクト固有の規約やパターン (CLAUDE.md 参照)
   • 指摘が参照しているコードが既に別箇所で対応済みでないか
   • 「却下」された指摘が再度上がった場合、履歴の却下理由を覆す新事実がなければそのまま却下する (ループの発散を防ぐため)

3. テストへの影響確認

   • 妥当と判断した指摘について、既存テストの変更や新規テストの追加が要否を確認する。
   • ドキュメントのみの修正など、テストが意味を持たないスコープではこの確認をスキップしてよい。

4. 検証結果をユーザーに提示

   • 以下のフォーマットで 全件まとめて 提示する:

     ## Iteration {N} 妥当性検証結果
     
     ### #{N}-1 {指摘タイトル} — {妥当 / 妥当でない / 対応不要 / ユーザー判断要}
     **レビューの主張**: ...
     **検証結果**: ... (該当コードへのマークダウンリンクを含める)
     **修正方針**: ... (妥当な場合のみ。修正対象へのリンクを含める)
     **テスト**: 変更不要 / {必要なテスト変更の説明}
     

   • この時点でコード修正には着手しない。Phase 3 へ進む。

Phase 3: 方針確定

「ユーザー判断要」項目をモードに応じて確定させ、全項目の最終方針を再提示する。

1. 「ユーザー判断要」項目の確定 — 上の「実行モード」表に従う。

2. 全項目の最終方針を再提示 — Phase 2 の表を、確定後の状態 (「妥当 → 修正する」/ 「対応不要」/「妥当でない」) で 改めて全件分 提示する。自律モードで自律確定した項目には (自律判断) を付ける。

3. 進行制御:

   • 対話モード: 「この方針で修正を開始します。Go を出してください。」と明示し、ユーザーの 明示的な Go (「Go」「やって」「進めて」「OK」等) を待つ。ユーザーが方針修正・追加却下・ 追加採用などを述べた場合、方針を更新し、改めて全件分の最終方針を提示してから Go 待ちに戻る。
   • 自律モード: 最終方針を提示したらそのまま Phase 4 へ進む (同一ターン内で続けてよい)。

Phase 4: 修正の適用

ハードゲート (対話モードのみ): ユーザーの明示的な Go を受けるまでこの Phase に入っては ならない。AskUserQuestion の回答、ユーザーによる方針コメント、(自律判断) などの記述は いずれも Go と同一視しない。自律モードではこのゲートはスキップする。

ゲートを通過したら、妥当と判断した指摘について順に修正する。

1. コード修正

   • Edit ツールで該当ファイルを修正する。
   • 修正のスコープはレビュー指摘への対応に限定する。指摘に関連しないリファクタリングや 改善は行わない。

2. ビルド / テスト確認

   • コード変更の場合は、関連ビルドとテストを実行してデグレを防ぐ。
   • ドキュメントのみの修正など、ビルド・テストが意味を持たない場合はスキップしてよい。
   • テスト戦略に関する CLAUDE.md のルールがあれば従う (代表テスト先行など)。

3. コミット (Phase 0 の選択に応じて)

   • 項目ごとにコミット: 1 指摘分の修正が完了するたびに、その指摘に関連する変更のみを ステージングして 1 コミット作成。コミットメッセージは英語で、対応した指摘の内容が分かる 内容にする (CLAUDE.md のコミットルール準拠)。短縮ハッシュを記録し、Phase 5 の履歴追記で 各項目に紐づける。
   • コミットしない: ステージングもせず、ワーキングツリーに差分を残すのみ。

Phase 5: イテレーション結果の報告とループ判定

1. ユーザーへの報告 — フォーマットは references/iteration-report.md を参照。

2. イテレーション履歴に追記 — Phase 0 で準備した履歴メモに、このイテレーションの レビュー指摘と対応決定を 項目ごとの詳細形式で 追記する。フォーマットは references/iteration-history.md を参照。

   • 却下した項目は「却下理由」と「再指摘されうる観点とそれが当たらない理由」まで書く。
   • 修正した項目は「具体的に何をどう変えたか」「影響範囲」を書く。
   • コミット方針が「項目ごとにコミット」の場合は、修正項目に短縮ハッシュを必ず付ける。 次のレビュアーは履歴のハッシュから git show で修正実体を確認できる。
   • 自律モードで自律確定した項目には (自律判断) と判断根拠を必ず残す。

3. ループ判定 — 以下のいずれかを満たせば Phase 6 へ。いずれにも該当しなければ Phase 1 に戻り次のイテレーションを開始する。

   • レビュアーが「指摘事項なし」を返した
   • 最大イテレーション数 (5) に到達した
   • ユーザーが明示的に停止を指示した
   • 「妥当」と判断され実際に修正された指摘が 1 つもなかった (すべて却下/対応不要/妥当でない) — レビュアーが残り続けても収束しない状態なので終了する

Phase 6: 最終改善サマリ

スキル開始前の状態と、すべてのイテレーション完了後の状態を比較し、何が改善されたか を 要約する。フォーマットは references/final-summary.md を参照。

ユーザー言語に従う (デフォルト日本語)。レビュアーへのプロンプトも日本語で問題ない。