| name | sanity-review |
| description | PRのレビュー報告書を作成する。bugや脆弱性の調査だけでなく、exportされた対話コンテキスト・PR概要欄・実装されたコードの整合性を確認し、実装者の正気を疑う。 ユーザーが「PRのレビュー報告書を書いて」「対話コンテキストと共にコードレビューして」「このPRの正気を疑って」と言った時に使用する。 |
| argument-hint | [PR-URL-or-number] |
PRレビュー報告書の作成手順書
feature/bugfix/refactoring PRをレビューし、レビュー報告書を作成する。
報告書はレビュアーがGitHubに貼ってレビュー完了を示すためのものであり、修正点がある場合はそれを説明するためのものでもある。
対象外
- ライブラリ更新PR（dependabot/renovatebot等）は
library-update-review skillの対象であり、このスキルの対象外
手順
手順0: PR情報の取得
引数でPR番号またはURLが指定されている場合はそのPRを対象とする。
指定がない場合は、現在のブランチに紐づくPRを自動検出する。
いずれの場合も、以下のコマンドでPR情報を取得する:
gh pr view {PR番号またはURL} --json number,title,body,url,author,comments,headRefName
自動検出の場合は {PR番号またはURL} を省略する。
PRが見つからない場合はユーザーに報告して終了する。
PRタイトル、PR番号、ブランチ名は報告書のヘッダーに使用する。Reviewed atには現在の日時（YYYY-MM-DD HH:mm:ss）を、Reviewerには自分のAgent名を記入する。
以下の情報を取得する:
- PR本文（概要欄）
- PRコメント:
gh pr view の comments
- インラインレビューコメント:
gh api repos/{owner}/{repo}/pulls/{number}/comments --paginate
- PRレビュー:
gh api repos/{owner}/{repo}/pulls/{number}/reviews --paginate
- 差分:
gh pr diff {number}
手順1: 対話コンテキストの読み込み
以下の順序で対話コンテキストを探す:
1-1. PRコメント欄を確認
PRコメントの中に「対話コンテキスト」というタイトルを含むコメントがないか確認する。
見つかった場合はその内容を対話コンテキストとして使用する。
1-2. .dev/contexts/ を確認
ブランチ名をサニタイズ（/ \ : * ? " < > | を - に置換）し、.dev/contexts/{サニタイズ済みブランチ名}.md を探す。
見つかった場合はReadツールで読み込む。
1-3. 両方見つからない場合
AskUserQuestionツールで以下を確認する:
- 対話コンテキストなしで続行: 手順6（考慮漏れの確認）はスキップする
- 中断: ユーザーに対話コンテキストの準備を依頼する
手順2: pull request概要欄の品質評価
この手順はコードを読む前に行う。 コードの整合性確認に引っ張られて概要欄の構造的問題を見落とすことを防ぐため。
実装者は正気ではないかもしれない。よくわからずにPR概要欄を書いたり、AIに生成させてそのまま貼っているかもしれない。
この手順では概要欄だけを読み、レビュアーがこの概要欄を読んで「変更の妥当性を判断できるか」を評価する。
PR概要欄チェックリスト
以下の4項目を 必ず全て 評価し、結果をメモする。全項目を評価してから次の手順に進む:
- 変更前の動作・問題が説明されているか: レビュアーは変更の妥当性を判断するために、変更前の状態を知る必要がある。「何をやったか」だけでは「もしかしたら変更前の動作の方が正しかったのでは？」という疑問が残る
- 「問題→解決」や「現状→修正」のペアで書かれているか: 新機能の場合は目的・動機でも可。ただし「やったこと」だけの一方通行な説明は不十分
- 変更の範囲が明確か: 何を変えて、何を変えていないのかがわかるか
- 実装者自身の理解が見えるか: AIが生成した文章をそのまま貼っただけでなく、実装者が何を考えてこの変更をしたのかが伝わるか
外部Agent相談の共通方針
手順3・手順4・手順5と手順6の6-6では外部Agentにセカンドオピニオンを求める（ただし手順4の「長期視点で命名・設計を考察する」サブセクションは対象外）。手順6のうち6-1〜6-5は疑わしい点がある場合に限り外部Agentへ相談する。以下のフォールバック順序に従い、推測で判断せず実際に呼び出して試すこと:
自分自身がCodex CLIの場合は2から開始する。そうでない場合は1から開始する。
- Skill toolで
codex-consultation を呼び出す。失敗した場合は2へ進む
- Skill toolで
subagent-consultation を呼び出す。失敗した場合は3へ進む
- main agentが単独で作業を実行する
フォールバックが発生した場合や、外部Agentが利用できなかった場合は、報告書の「レビュー作業において発生した問題」セクションに記載する。
3（main agent単独実行）にフォールバックした場合は、このスキルのコアである批判的思考の連鎖（互いの主張を検討・反論しあい、正確性と網羅性を向上するプロトコル）が機能していないことを意味する。往復検証が欠落した状態でのレビューは本来の精度を持たないため、報告書の「レビュー作業において発生した問題」セクション冒頭に、以下の文言をそのままbold段落として記載すること:
⚠ 警告: 批判的思考の連鎖が機能していません、実行環境が正気である事を疑ってください
各手順では、外部Agentに渡すArgsの内容と、結果の扱い方を記載する。
手順3: 実装者の説明と実装の整合性確認
この手順の目的は、概要欄やコメントでの説明と実際のコードが一致しているかを確認する、ドキュメントとコードの読み合わせ である。
重要: 実装者の発言のみを拾う
PR概要欄の author と、各コメントの author を照合し、実装者本人の発言のみを実装の説明として扱う。
他の人が書いた応援コメント、機能に対する期待を込めたコメント、質問等は、実装の説明ではない。
これらを実装の説明と混同すると、整合性の判断を誤る。
確認事項
- PR概要欄の説明と、実際の差分が一致しているか
- インラインレビューコメントでの実装者の説明と、実際のコードが一致しているか
- PRレビューの本文（top-level review comment）での実装者の説明と、実装が一致しているか
- 対話コンテキストの内容と、実装が一致しているか（対話コンテキストがある場合）
齟齬を発見した場合は具体的に記録する。
外部Agentによる整合性確認
Agent自身の確認に加えて、外部Agentにも差分と概要欄の整合性を確認させる。
別の視点でコードを読むため、Agentが見落とした齟齬を発見できる可能性がある。
「外部Agent相談の共通方針」に従い、以下のArgsで呼び出す:
Args: よく相談して。PR #{番号} の概要欄の説明と実際の差分に齟齬がないか確認してほしい。{概要欄の要約と確認ポイント}
外部Agentの指摘を受け取ったら、自分の確認結果と照合し、見落としがなかったか確認する。
手順4: 命名・設計パターンの一貫性
この手順の目的は、実装が既存のコードベースの慣習と一致しているかを確認する、コードベースの読み解き である。
バグ・脆弱性を調べる前にコードベースを理解することで、後続の調査の精度が上がる。
確認事項
-
命名規則の一致
- ファイル名・関数名・変数名・クラス名が、既存コードの命名パターンと揃っているか
- 機能の正式名称を歯抜けに省略した名前が導入されていないか
-
設計パターンの一致
- 構造・module分割・責務の切り方が、既存の類似機能と揃っているか
- 既存の抽象化を活用しているか、重複した実装を作っていないか
齟齬を発見した場合は具体的に記録する。
外部Agentによる確認
Agent自身の確認に加えて、外部Agentにも命名・設計パターンの一貫性を確認させる。
「外部Agent相談の共通方針」に従い、以下のArgsで呼び出す:
Args: よく相談して。PR #{番号} で追加・変更された命名と設計パターンが、既存のコードベースの慣習と一致しているか確認してほしい。{変更概要}
外部Agentの指摘を受け取ったら、自分の確認結果と照合し、見落としがなかったか確認する。
長期視点で命名・設計を考察する
将来、コードベースが拡張されたときに、現在の命名・設計が禍根となりうるかを考察する。
既存コードとの一致（事実判定）とは異なり、これは議論のタネを提供して人間の想像力を掻き立てるための作業である。
気になった点があれば、「懸念・反証・結論または保留」を押さえた自問自答形式で書き出す。
これはAgent自身の見解なので、通常の段落として記載する。1論点につき2〜3段落程度でよい。
無理に結論を出さなくてよい。気になる点がなければ「特になし」と記載する。
この考察セクションは外部Agentには振らず、skill実行元のAgentが自分で考える。
出力例:
「access-token」という名前は、現状はユーザーとサービス間のtokenしか指さないため問題はない。
ただ今後、外部サービスとの接続用のtokenが登場した場合は、概念衝突が起きる可能性がある。
そうなったら `user-access-token` のように主体を名前に含める必要が出るかもしれない。
もっとも、現時点で外部サービス連携を近い将来に追加する計画は見えていないため、今すぐ修正すべき問題ではないと判断する。
「member-metrics」という名前についても、将来 project member 以外の member 概念が増えた場合には曖昧になる余地がある。
一方で既存コードでは `Member` は project member を指す語として定着しており、短期的には大きな問題はなさそうである。
したがって現時点では問題なしと判断する。
ただし、将来 organization member など別種の member 概念を導入するなら、命名の見直しは必要になる。
手順5: バグ・脆弱性の調査
「外部Agent相談の共通方針」に従い、外部Agentにコードレビューを依頼する。
引数には、PRの変更概要、差分の要約、確認してほしいポイントを含める。
深さの指定を引数に含めること。consultation系スキルは深さが未指定だとユーザーに聞き返すため、レビューの流れが中断される:
Args: よく相談して。PR #{番号} のコードレビューをお願いします。{変更概要と確認ポイント}
結果の検証
外部Agentの指摘を鵜呑みにしない。以下を行う:
- 外部Agentが指摘したポイントを、自分でコードを読んで検証する
- 外部Agentが見落としている可能性がある領域を意識的に探す
- 外部Agentの指摘と自分の見解が食い違う場合は、両方の理由を記録する
手順6: 対話コンテキストの再読み・考慮漏れ確認
対話コンテキストがない場合はこの手順をスキップする。
コードレビューは作業結果のダブルチェックではない。結果ではなくプロセスをレビューする。
やった事はコードを読めばわかる。検討した上でやらなかった事こそ、設計のレビューに必要な情報である。
対話コンテキストに書かれた設計判断・却下理由・意図的な非対応の「プロセス」が正しいかを検証する。
対話コンテキストを改めて精読し、以下を検証する:
6-1. 設計判断の根拠
対話コンテキストに書かれた設計判断の理由が、コードの実態と一致しているか。
6-2. 却下した代替案の再評価
対話コンテキストの「却下した代替案」セクションから、各代替案を1つずつ抜き出して再評価する:
- 不採用の理由は妥当か。本当に公平に比較したか
- 見落とした利点や、過大評価したデメリットはないか
- 採用案と却下案の比較に使われた前提条件は正しいか
6-3. 失敗した試行のプロセス検証
「試したがダメだった」と記載されているものについて、結果だけでなく試し方自体を疑う:
- 前提条件は正しかったか
- 実行手順に見落としはなかったか
- 判断基準（「ダメ」と判定した根拠）は妥当だったか
- 別の条件で試せば結果が変わる可能性はないか
6-4. 意図的に対応しない事項の妥当性
「やらない」と決めたものについて:
- 「やらない」理由は、今の実装を踏まえても妥当か
- 実装の結果、前提が変わって「やるべき」に変わっていないか
6-5. 記載されている事実の正確性
対話コンテキストに書かれた「事実」が本当に正しいか、コードを読んで検証する。
疑わしい点がある場合は、「外部Agent相談の共通方針」に従い外部Agentにも相談する。Argsに「よく相談して」を含めること。
6-6. 採用案の前提を1つずつ解除して再評価する
この手順が狙うのは「定石外発想」── 現状の発展型（既存案に機能や記述を足す方向）ではなく、前提という枷を外したときに立ち現れる解 ── である。
6-2・6-3が却下案・失敗試行（過去に捨てた選択肢）の判断の公平さを検証するのに対し、ここでは採用された設計そのものが置いている前提を組み替えられないかを検証する。
- 採用案が依存している前提条件を、対話コンテキストとコードから列挙する
- 各前提について「この前提が無ければ、よりシンプルな解になるか」を1つずつ検討する
- シンプルになる場合は、採用案と次の観点で比較する: 実装量 / 既存仕様との互換性 / ユーザー・開発者への説明コスト / 運用・移行コスト / 将来の保守性
- 結果を「今すぐ検討すべき」「将来の論点」「現状の採用案で妥当」に分類する
対話コンテキストやコードに根拠のない空想上の要件・前提は持ち込まず、レビュー対象の変更が依存している前提だけを扱う。
Agent自身の再評価に加えて、外部Agentにも前提解除を独立に行わせる。別の視点で前提を洗い出すことで、Agentが当然視して見落とした前提を拾える。外部Agentは放っておくと既存案のレビュー（現状の発展型）に流れるため、「レビュー」ではなく上記1〜4の手順そのもの（前提を自分で列挙し、1つずつ外してよりシンプルな解を探す）を実行させること。
「外部Agent相談の共通方針」に従い、以下のArgsで呼び出す:
Args: 軽く相談して。PR #{番号} の採用案が依存している前提を自分で列挙し、各前提を1つずつ外したらよりシンプルな解になるか検討してほしい（既存案のレビューではなく前提の組み替え）。対話コンテキストとコードに根拠のある前提だけを扱い、空想上の要件は持ち込まないこと。{採用案と対話コンテキストの要約}
外部Agentの別解を受け取ったら、自分の再評価と照合し、見落とした前提やより良い解がなかったか確認する。
手順7: レビュー報告書の作成
このSKILL.mdと同じディレクトリにある TEMPLATE.md を読み込み、その形式に従って報告書を作成する。
報告書は会話に出力する（ファイルに保存しない）。
レビュアーが自分でGitHubにコピー＆ペーストする。
報告書作成のガイドライン
- pull request概要欄 > サマリー: 実装者の説明を引用・抜粋してbefore-afterで整理する。想像で補って勝手に書かない。実装者の説明が不十分な場合は素直にその旨を指摘する
- pull request概要欄 > 品質評価: 手順2のチェックリスト結果をOK/NG/該当なしで記入する。NGの場合は具体的に何が不足しているかを記載する
- レビュー作業において発生した問題セクション: レビュー手順をスキップした場合は、外的要因（ツールが利用できなかった等）かAgentの判断かを区別して記載する。問題がない場合は「特になし」と記載する
- 結論セクション: 全体の総合判断と推奨アクションを記載する
- 全体を通じて、レビュアーが「この変更は妥当か」を判断するための材料を提供することを意識する
関連スキル
- codex-consultation: Codex CLIと相談するスキル。手順3・手順4・手順5・手順6で外部Agentの第一候補として使用する
- subagent-consultation: Agentツール（subagent）と相談するスキル。codex-consultationが利用できない場合のフォールバック先
- conversation-context-import: 対話コンテキストを読み込むスキル。手順1の背景知識
- conversation-context-export: 対話コンテキストを書き出すスキル。対話コンテキストの形式の背景知識
- library-update-review: ライブラリ更新PRのレビュースキル。このスキルの対象外であるPRの種類
