Claude review

Claude Review スキル

このスキルは Claude Code / Codex / Cursor のどのホスト（エージェント）からも呼ばれる前提で書かれている。ホスト固有の手順は「実行時間と中断の防止」のホスト分岐に従う。

用途境界: 本スキルは第三者レビュー専用で、read-only + 既定 high（xhigh 以上は使わない）。実装ワーカーとしてCLI agentを委譲する場合は別のオーケストレーター手順を使い、write権限 + 通常 medium とする。レビューと実装委譲を同じ設定で混用しない。

ガードレール（必須・逸脱禁止）

1. read-only 厳守: 起動コマンドには必ず --permission-mode plan と --disallowedTools "Edit,Write,NotebookEdit" の両方を入れる。片方でも欠けたコマンドは実行してはならない。レビュー後に git status で作業ツリー汚染がないか確認し、汚染があれば即報告する
2. ネスト起動禁止: レビュー用 Claude に別の claude -p / codex exec / review 系 skill を起動させない（依頼文に再帰防止文を必ず含める）
3. 書き込み系操作の禁止: commit / push / PR 作成 / GitHub コメント / Issue 作成・更新を行わせない。結果はテキストで返させる
4. 明示指定の尊重: ユーザーが effort / model を明示した場合、自動判定で上書きしない（上げるのも下げるのも禁止）
5. 長時間無出力時のフォールバック: 開始時に想定所要時間（数分〜数十分）を伝える。バックグラウンド実行にして進捗を定期確認し、40分以上無出力なら状況を報告して「継続 or 中断して codex-review へ切替」をユーザーに提示する（勝手に放置も勝手に中断もしない。中断時は結果の部分回収を試みる）。高 effort のレビューでは数十分の無出力も正常範囲であり、それ自体を失敗の根拠にしない

別プロセスの Claude CLI を起動し、コードベースを read-only で分析する。 現セッションのコンテキストやバイアスに縛られない、独立したセカンドオピニオンを得られる。

モデルと effort（2026-07 時点）

このセクションが本スキル内のモデル ID・effort・既定値の唯一の定義元。 以降のコマンド例に埋まっているモデル名・effort はここの既定値の写しであり、モデル状況が変わったら本セクション・コマンド例・evals/evals.json の expected_output をあわせて更新する。

使用可能なモデル

モデル	ID	備考
Opus 5	claude-opus-5	既定。品質・深さ優先
Sonnet 5	claude-sonnet-5	高速・低コスト。near-Opus 能力。軽めのレビューで指定可
Fable 5	claude-fable-5	ユーザー明示時のみ。トークン消費が著しく多いため自動選択しない

重要: claude-fable-5 はトークン消費が著しく多いため、ユーザーが「Fable で」「fable-5 を使って」と明示的に指定した場合のみ使用する。それ以外では常に claude-opus-5 をデフォルトとする。別モデルの明示指定があればそれを優先。

旧世代 Opus（claude-opus-4-8 以前）を既定にしない。 ユーザーが版を明示した場合のみ使用し、自動判定では常に現行の claude-opus-5 を選ぶ。

Effort レベル

effort が明示されない場合は、依頼内容の複雑度から自動判定する。既定は high。 通常のコードレビューもアーキテクチャ分析もこの既定 high で行う。クイックチェックなど明らかに軽微な依頼に限り medium / low に下げてよい。effort が明示された場合は必ずそれに従う。

xhigh 以上（xhigh / max）は使わない。 effort を上げるほど精度が上がるわけではなく、過剰な探索と推論でレビュー結論の質が落ちる場合がある。自動判定でも既定でも選ばない。深さが足りないと感じたときは effort を上げるのではなく、対象スコープを絞る・観点を具体化する・複数回に分ける方向で対処する。

下表は各レベルの「深さの目安」であって、タスク種別から機械的にレベルを引くための対応表ではない。未指定時は上のルール（既定 high）が優先し、下表は「既定からどこまで下げてよいか」の判断材料として使う。

レベル	オプション	目安（既定 high 基準）
low	--effort low	ごく軽微・クイックな確認のみ（最速）
medium	--effort medium	小さな差分・限定スコープの軽いレビュー
high	--effort high	通常のコードレビュー〜複雑な設計判断・アーキテクチャ分析・難解なバグ（既定・自動判定の上限）
xhigh / max	（使わない）	選択しない。 精度向上に結び付かず、時間とコストだけが増える

自動判定の上限は high。 ユーザーが xhigh / max を明示的に要求した場合のみ、ガードレール4に従って尊重する（その際は精度が上がらない可能性を一度添える）。

実行前の確認

会話の文脈からわかる場合は確認を省略して構わない。不明な場合のみ確認する。

項目	デフォルト
依頼内容	必須。何をレビュー・調査してほしいか。
対象ディレクトリ	カレントディレクトリ (pwd)
モデル	claude-opus-5（Opus 5）。別モデル指定があればそれを優先
Effort レベル	自動判定（既定 high、軽微な依頼のみ medium/low。xhigh 以上は使わない）

<依頼内容> には、ユーザーの依頼をその意図を保ったまま、レビュー対象スコープ（全体／特定ファイル・ディレクトリ／差分の範囲）と観点を含む簡潔な指示へ整形して埋める。差分レビューでは対象（未コミット／ブランチ差分／コミット）を依頼文に明示し、未指定なら作業ツリーの差分を既定とする（起動先 Claude が git diff 等の読み取り系ツールで取得する）。

重要: 起動先 Claude がさらに codex-review / claude-review skill や codex exec / claude -p を起動して再帰することがある。<依頼内容> の先頭または末尾に必ず次の趣旨を明示する。

You are the reviewer. Inspect the repository directly.
Do not invoke codex-review, claude-review, codex exec, claude -p, or any nested reviewer.
Use only read-only repository inspection commands and return findings directly.

実行コマンド

プロンプト本文は必ず single-quoted heredoc で渡す。Markdown のバッククォート、$VAR、$(...)、型注釈、引用符を含むレビュー依頼を claude -p "..." に直接入れると、shell がコマンド置換や変数展開として解釈してプロンプトを壊す。

claude -p "$(cat <<'CLAUDE_REVIEW_PROMPT'
You are the reviewer. Inspect the repository directly.
Do not invoke codex-review, claude-review, codex exec, claude -p, or any nested reviewer.
Use only read-only repository inspection commands and return findings directly.

<依頼内容>
CLAUDE_REVIEW_PROMPT
)" \
  --model claude-opus-5 \
  --effort <level> \
  --add-dir /path/to/project \
  --permission-mode plan \
  --disallowedTools "Edit,Write,NotebookEdit" \
  < /dev/null

重要: heredoc delimiter は必ず引用する（例: <<'CLAUDE_REVIEW_PROMPT'）。引用しない <<EOF は shell 展開を許すため使わない。プロンプト内に delimiter と同じ行が含まれる場合だけ、別の一意な delimiter 名に変える。 重要: --disallowedTools は可変長フラグのため、プロンプトは必ずフラグ群より前（最初の引数）に置くこと。後ろに置くとプロンプトが認識されずエラーになる。 重要: 実行直前に、生成したコマンドへ--permission-mode planと--disallowedToolsが両方存在することを再確認する。 重要: 末尾の < /dev/null は必須。明示prompt以外のstdin待ちを防ぐ。stdin読取を示すメッセージが出ても、redirect済みで本文生成が進んでいればハングではない。 重要: Claude Code 上ではこのコマンドを run_in_background: true で起動する（理由と手順は後述の「実行時間と中断の防止」を参照）。既定 high でも対象が大きければ処理は数分〜数十分かかりうるが、背景実行なら Bash の10分上限で kill されず、呼び出し元もブロックしない。claude -p は非対話の print モードで標準出力に結果を出すため、背景起動でも出力ファイルから完全に回収できる。

• --model claude-opus-5: 使用モデルを明示固定（既定・選択肢は「モデルと effort」セクション参照）
• --effort <level>: 既定 high（自動判定。xhigh 以上は使わない）
• --add-dir <project_dir>: 対象ディレクトリへのアクセスを明示的に許可する
• --permission-mode plan: Bashを含む実行全体を非変更モードへ制約する
• --disallowedTools: Edit/Write/NotebookEdit を禁止して読み取り専用を保証する
• ファイルの読み取り・Bash・git などの読み取り系ツールは引き続き使用可能

複数directoryを横断する場合、現行CLIの--add-dir <directories...>へ必要なpathを列挙する。共通親を広く許可するより、必要なdirectoryだけを許可し、promptにも対象pathを明示する。

--add-dir /path/to/repo-a /path/to/repo-b /path/to/shared

実行例

# カレントディレクトリを分析する場合（既定 high）
claude -p "$(cat <<'CLAUDE_REVIEW_PROMPT'
You are the reviewer. Inspect the repository directly.
Do not invoke codex-review, claude-review, codex exec, claude -p, or any nested reviewer.
Use only read-only repository inspection commands and return findings directly.

認証周りのセキュリティ上の問題点を洗い出してください
CLAUDE_REVIEW_PROMPT
)" \
  --model claude-opus-5 \
  --effort high \
  --add-dir $HOME/my-project \
  --permission-mode plan \
  --disallowedTools "Edit,Write,NotebookEdit" \
  < /dev/null

# 軽めのクイック確認（自動判定で Sonnet 5 + medium に下げた例）
claude -p "$(cat <<'CLAUDE_REVIEW_PROMPT'
You are the reviewer. Inspect the repository directly.
Do not invoke codex-review, claude-review, codex exec, claude -p, or any nested reviewer.
Use only read-only repository inspection commands and return findings directly.

この差分に明らかなバグがないか軽く見て
CLAUDE_REVIEW_PROMPT
)" \
  --model claude-sonnet-5 \
  --effort medium \
  --add-dir $HOME/other-project \
  --permission-mode plan \
  --disallowedTools "Edit,Write,NotebookEdit" \
  < /dev/null

実行時間と中断の防止

ハイエンドモデル + 高 effort（既定の Opus 5 + high）では、対象が大規模なほどレビューに数分〜数十分かかることがある。これは正常で、出力が無い間も停止やハングではなく推論を継続している。長時間化を理由に kill・キャンセル・再実行をしてはならない。 呼び出し元（人間・上位エージェントを問わず）に中断不要だと伝え、気長に完了を待つ。

まず実行ホストで分岐する: Claude Code 上なら背景実行（手順1〜4）。run_in_background を持たないホスト（Codex/Cursor 等。自分が Codex として動作している場合を含む）は手順1〜4ではなく手順5の foreground フォールバックを使う。

1. run_in_background: true で起動する（Claude Code での本筋） Claude Code 上では Bash ツールの run_in_background を使う。foreground と違い10分上限で kill されず、呼び出し元をブロックしない。起動結果が返すtask IDとoutput file pathを保存し、推測したpathを読まない。完了時に Claude Code がエージェントを自動再呼び出しし、出力も取得できる。

2. 起動直後に呼び出し元へ予告する（背景起動でターンが即 yield するので、この一言を必ず出す）

   「claude-review をバックグラウンドで開始しました。レビューには数十分かかる場合があります。応答が無くても処理は継続中（ハングではありません）なので、中断せず気長にお待ちください。完了時に結果を報告します。」

3. 完了通知で再呼び出しされたら報告する 背景出力は数百KBになり得るため、ファイル全体をReadせずtailで末尾から確認し、rg -n "VERDICT|must-fix" <output>で論点位置を探す。同じ最終本文が再掲される場合は重複報告しない。

4. 待機中は背景タスクを kill・キャンセル・再起動しない。 highで10分超・10万token級、または数十分無出力でも正常になり得る（40分超の無出力のみガードレール5に従いユーザーへ提示する）。

5. 背景実行を持たないホスト（Codex/Cursor 等）でのフォールバック foreground で実行し、ホストの実行タイムアウトを可能な限り長く確保する（Claude Code の Bash 相当なら上限 600000ms=10分）。foreground はブロックするため発話窓は「実行直前」のみ。起動直前に次の foreground 用の予告を出す（手順2の文言は「バックグラウンドで開始」を含み foreground では不正確になるため、そのまま流用しない）。

   「これからレビューを実行します。完了まで数十分かかる場合があります。応答が無くても処理は継続中（ハングではありません）なので、中断せず気長にお待ちください。」

   結果は Bash の標準出力（戻り値）として直接返るため、背景用の出力ファイル Read / BashOutput は使わず、その stdout を下記「結果の整理と報告」に従って報告する。ホストのタイムアウト上限が数十分の実行に足りず kill された場合も盲目的に再実行せず、effort を一段下げる（high→medium）か対象を絞る（特定ファイル/ディレクトリ）。

6. 補足（実行モードに依らない）: 背景実行は10分の foreground 上限に縛られないが「無制限」ではない。巨大リポジトリのレビューが背景でも長すぎる場合は、同様に effort 降格（high→medium）や対象の絞り込みで対処する。

結果の整理と報告

Claudeの指摘は結論ではなく仮説として受け取り、採用前に該当path:lineと実装を自分で確認する。必要であれば以下の観点で整理する:

1. 要約: 主な発見事項（3点以内）
2. 詳細: 具体的な指摘（優先度順）
3. 推奨対応: 改善提案と実装方針
4. 補足: 追加調査が必要な項目

推奨prompt contract

• 論点を番号付きで列挙し、各論点に VERDICT: AGREE / AGREE-WITH-CAVEAT / DISAGREE / RISK、根拠、代替案を要求する
• 遠慮不要と明記し、懸念している弱点を具体的に列挙する
• 各findingにpath:lineを必須化する
• docsレビューでは契約定義・manifest・package設定など対象実装を列挙し、文書の現在形の主張と実装を突合させる。docs整合だけならmediumを選べる

網羅性を明示的に要求する（重要）。 洗練された指摘が返る一方で、重要度による自己フィルタや説明の飛躍で論点が落ちることがある。次の3点を依頼文へ必ず入れる。

• 重要度・確信度で self-filter させない。 「低確度・低severityと判断したものも含めて全件挙げる。絞り込みは呼び出し側で行うので、この段階の目的は網羅性である」と明記し、各findingに confidence と severity を自己申告させる。上限件数は課さない（件数上限は網羅性と直接トレードオフするため、必要なら受け取り側で切る）。
• 見ていない範囲を返させる。 「今回検査しなかったファイル・観点・前提」を scope statement として必ず出させる。無言の未検査を「問題なし」と誤読しないため。
• 同種欠陥の掃き出しを最後に1回要求する。 「指摘した各欠陥について、同じ原因の箇所が他に残っていないか検索して報告する」。1件目だけ挙げて類似箇所を落とす形を防ぐ。

受け取り側の検証規律

1. 指摘を機械的に採用・棄却せず、該当箇所と成立条件を確認する。
2. 引用の実在を確認する。 提示された path:line とコード断片が実際にその内容で存在するかを、採用前に必ず自分で突き合わせる。行番号のずれ、古い内容の引用、存在しないシンボルは珍しくない。実在しない引用に依存した指摘は、結論が正しく見えても採用しない。
3. セキュリティ境界はfail-closed等のラベルで合格にせず、何と何を比較し、どこで強制しているかを実装まで辿る。
4. scope statement を読み、未検査範囲を明示的に扱う。 未検査の観点が重要なら、別途レビューするか自分で確認する。返答に無いことを「問題が無いこと」の根拠にしない。
5. 修正後は元の検査に加え、secret/confusable等の関連scanを再実行する。
6. 最後にgit statusを再確認し、レビュー用processによる汚染がないことを確認する。

注意事項

• --permission-mode plan と --disallowedTools を併用し、Bashを含む変更操作とEdit/Write/NotebookEditを二重に制約する
• Markdown やコード片を含むプロンプトを claude -p "..." に直接書かない。必ず single-quoted heredoc で渡す
• モデル・effort の既定と選択肢は「モデルと effort」セクションの定義に従う
• claude-fable-5 はトークン消費が著しく多いためユーザー明示時のみ使用し、自動選択は絶対にしない
• effort は既定 high（自動判定）。軽微な依頼や時間優先のときのみ medium / low に下げる
• xhigh / max は使わない。精度が上がらないため、深さ不足はスコープの絞り込みや観点の具体化で解決する
• --add-dir を忘れると対象ディレクトリへのアクセスが制限される場合がある