| name | self-review |
| description | コミット済みの変更を、sub agent によるレビューと修正のループで検証する。変更をコミットした後、GitHub への push や PR 作成の前に使う。レビュアーが approve するまでループを回す。 |
セルフレビュー
目的
人間がこのコードをレビューするとき、何も言うことがない状態を作る。
レビューの所要時間やトークンコストの節約よりも、レビュー結果の完成度を優先する。
全体の流れ
- レビュー対象の確定
- プロジェクト固有のレビュー観点の収集
- ラウンド1: 観点別レビュアーを並行起動
- 指摘のトリアージと対応 (修正 or 見送り理由の言語化)
- ラウンド2以降: 検証レビュー
- 終了判定とユーザーへの報告
1. レビュー対象の確定
- スキル起動時に基準コミットを 1 つ確定する。基準は今回の作業を始める前の HEAD。セッションの記録から特定できない場合は upstream (なければデフォルトブランチ) との merge-base を使う
- 基準の確定時と各ラウンドの開始時に
git merge-base --is-ancestor <基準> HEAD で基準が HEAD の祖先であることを検証する。rebase などで履歴が書き換わり祖先でなくなっていたら、upstream (なければデフォルトブランチ) との merge-base に基準を付け替える
- 以降すべてのラウンドで
git diff <基準>..HEAD とその範囲のコミットメッセージをレビュー対象とする。範囲を固定することで、ループ中に作った修正コミットも自動的に対象へ含まれる
2. プロジェクト固有のレビュー観点の収集
レビュアーを起動する前に、プロジェクト内のレビュー指針を探す。見つかったものはレビュアーのプロンプトに含める:
- プロジェクトの CLAUDE.md、
.claude/ 配下のドキュメント
- CONTRIBUTING.md、PULL_REQUEST_TEMPLATE、
docs/ 配下のコーディング・レビューガイド
- linter / formatter の設定 (.rubocop.yml など) から読み取れる規約
3. ラウンド1: 観点別レビュアーの並行起動
変更の規模・性質に応じて、後述の「レビュー観点」を 2〜4 グループに分け、グループごとにレビュアー sub agent を並行起動する。分け方の例:
- 正しさ・影響範囲 / 設計・規約・コメント / セキュリティ・性能 / テスト・コミットメッセージ
ごく小さな変更なら 1 つのレビュアーに全観点をまとめてもよい。
各レビュアーには「レビュアーへの指示」の内容、担当する観点、対象 diff の取得方法、収集したプロジェクト固有の観点を渡す。
4. 指摘のトリアージと対応
レビュアーから受け取った各指摘について、必ずいずれかを行う:
- 修正する: コードを直してコミットする。push 済みなら新規コミット。push 前で HEAD のコミットへの指摘なら amend、それより前のコミットへの指摘なら
git commit --fixup の後に非対話の git rebase --autosquash <基準> で取り込む (Git 2.44 未満などで非対話 rebase が使えなければ fixup を squash せず独立した修正コミットのまま残してよい)
- 修正しない: 見送る理由を明文化する。「軽微だから」「時間がないから」は理由にならない。指摘自体が誤りである根拠、または修正がかえって悪化を招く根拠を書く
- question に回答する: 指摘が質問なら、調査した根拠を添えて回答する。回答の結果修正が必要と分かったら「修正する」に切り替える
対応結果 (修正の diff / 見送り理由 / 回答) は次ラウンドのレビュアーに渡すため記録しておく。
ループ内で作った修正コミットは以降のラウンドで検証されるため、ループ終了後に改めてセルフレビューを起動する必要はない。
5. ラウンド2以降: 検証レビュー
新しいレビュアー sub agent を 1 つ起動し、前ラウンドの指摘一覧と対応内容を渡す。このレビュアーの仕事:
- 修正が指摘を本当に解消しているか検証する
- 修正が新たな問題を持ち込んでいないか確認する
- 見送り理由が妥当か判定する。妥当でなければ指摘を維持する
- 変更全体をあらためて 1 パス見て、新規の指摘がないか確認する
指摘が残れば 4 に戻る。
6. 終了判定とユーザーへの報告
- レビュアーが approve を返したら終了
- ラウンド1を含め 5 ラウンド回っても収束しない場合は打ち切り、未解決の論点を整理してユーザーの判断を仰ぐ
- 終了時、ラウンド数・修正した指摘・見送った指摘とその理由をユーザーに要約して報告する
レビュアーへの指示
レビュアー sub agent のプロンプトには以下を含める。
役割と姿勢
- 人間のレビュアーが何も言うことがなくなる水準を目指す、懐疑的なレビュアーとして振る舞う
- 作者の説明を鵜呑みにせず、diff とコードベースから自分で理解を組み立てる
- 確信が持てない指摘は黙って流さず question として出す
- コードは変更せず、指摘の報告のみを行う。修正は依頼元のエージェントが行う
ツールの積極活用
- コード検索: 変更した関数・メソッドの呼び出し元をすべて洗い出し影響範囲を確認する。類似実装や既存ヘルパーを探し、再実装 (車輪の再発明) を検出する。命名やイディオムの規約をコードベースから確認する
- GitHub の Issue / PR 検索 (GitHub MCP を優先): 関連する過去の議論や設計判断、同種の変更が受けたレビュー指摘、変更箇所に関わる既知のバグを探す
- Web 検索: 使用しているライブラリ・API の仕様確認、deprecation や既知の問題、セキュリティアドバイザリの確認
出力形式
指摘ごとに以下を記す:
- 重大度: must-fix / should-fix / nit / question
- 該当箇所:
file:line
- 根拠と、可能なら修正案
最後に approve / request-changes の判定を明示する。approve の条件は、must-fix / should-fix がゼロで、すべての question に納得できる回答が得られていること。nit だけが残っている場合は approve してよい。
レビュー観点
共通
- 正しさ: ロジックの誤り、境界値 (空、nil、0、負数、巨大入力、マルチバイト文字)、並行性・競合状態、エラー処理、リソースリーク
- 要求との一致: ユーザーの依頼を過不足なく満たしているか。依頼にないスコープ外の変更が紛れ込んでいないか
- 影響範囲: 変更した関数・メソッドのすべての呼び出し元で、挙動の変化が安全か
- コードベースとの整合: 既存の規約・命名・イディオムに沿っているか。既存のヘルパーで書けるものを再実装していないか
- コメント: CLAUDE.md のコメント規約に適合しているか。消すべきコメントが残っていないか
- テスト: 変更に見合うテストがあるか。境界・失敗系を覆っているか。実装をなぞるだけのテストになっていないか
- セキュリティ: 入力検証、インジェクション、秘密情報のハードコードやログ出力
- 性能: 計算量、不要なループ・メモリ確保、I/O 回数
- 依存関係: 追加・更新したライブラリの妥当性、既知の脆弱性
- 互換性: 公開 API・シリアライズ形式・設定ファイルの後方互換性
- 可観測性: 障害時に調査の手がかりになるログ・エラー情報が残るか
- コミットメッセージ: CLAUDE.md の規約 (概要、背景、不採用案、参考 URL、末尾の一句・一首) を満たすか。メッセージだけで変更内容と背景を理解できるか
- ドキュメント: README などの更新漏れ
Webアプリの開発の場合
Ruby/Rails を主に想定するが、他言語の Web アプリにも読み替えて適用する。
- DB クエリ: N+1 (includes / preload の漏れ)、新しいクエリに対するインデックスの有無、不要な全件ロード
- マイグレーション: 可逆性、大きいテーブルでのロック、NOT NULL + default 追加の手順、コードとスキーマのデプロイ順序の安全性
- 整合性: ユニーク制約が validation だけでなく DB 制約にもあるか、トランザクション境界、after_commit と after_save の使い分け
- セキュリティ: Strong Parameters / mass assignment、SQL インジェクション (文字列補間入りの where など)、XSS (html_safe / raw)、CSRF、オープンリダイレクト、認可漏れ (各エンドポイントで対象リソースの所有・権限チェックがあるか)、ファイルアップロードの検証
- バックグラウンドジョブ: 冪等性、リトライ安全性、引数にはオブジェクトでなく ID を渡しているか
- 時刻: Time.current と Time.now の使い分け、タイムゾーン、日付境界の扱い
- HTTP: ステータスコードの妥当性、エラーレスポンス形式の一貫性
- キャッシュ: 無効化漏れ、キー設計
