Sanity Review

PRレビュー報告書の作成手順書

feature/bugfix/refactoring PRをレビューし、レビュー報告書を作成する。 通常のコードレビューを補助するだけでなく、実装者が自らPRをレビューするためのセルフレビューツールでもある。人間のレビュアーに見せられる正気なpull requestに仕上げる事を目的とする。

対象外

• ライブラリ更新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名とmodel名を記入し、外部Agentを使った場合はconsultation skillが取得した実行環境を併記する。

以下の情報を取得する:

1. PR本文（概要欄）
2. PRコメント: gh pr view の comments
3. インラインレビューコメント: gh api repos/{owner}/{repo}/pulls/{number}/comments --paginate
4. PRレビュー: gh api repos/{owner}/{repo}/pulls/{number}/reviews --paginate
5. 差分: gh pr diff {number}

報告書の出力先の確認

レビュー作業を始める前に、AskUserQuestionツールで報告書の出力先を確認する:

• チャットとpull request（推奨）: レビュー報告書を会話に出力し、同じ内容をPRにもコメントとして投稿する
• チャット: レビュー報告書を会話にだけ出力する

ユーザーが明示的に出力先を指定している場合はこの確認を省略し、指定に従う。

手順1: 対話コンテキストの読み込み

以下の順序で対話コンテキストを探す:

1-1. PRコメント欄を確認

PRコメントの中に「対話コンテキスト」というタイトルを含むコメントがないか確認する。 見つかった場合はその内容を対話コンテキストとして使用する。

1-2. .dev/contexts/ を確認

ブランチ名をサニタイズ（/ \ : * ? " < > | を - に置換）し、.dev/contexts/{サニタイズ済みブランチ名}.md を探す。 見つかった場合はReadツールで読み込む。

1-3. 両方見つからない場合

AskUserQuestionツールで以下を確認する:

• 対話コンテキストなしで続行: 手順6（考慮漏れの確認）はスキップする
• 中断: ユーザーに対話コンテキストの準備を依頼する

手順2: pull request概要欄の品質評価

この手順はコードを読む前に行う。 コードの整合性確認に引っ張られて概要欄の構造的問題を見落とすことを防ぐため。

実装者は正気ではないかもしれない。よくわからずにPR概要欄を書いたり、AIに生成させてそのまま貼っているかもしれない。 この手順では概要欄だけを読み、レビュアーがこの概要欄を読んで「変更の妥当性を判断できるか」を評価する。

PR概要欄チェックリスト

以下の4項目を 必ず全て 評価し、結果をメモする。全項目を評価してから次の手順に進む:

1. 変更前の動作・問題が説明されているか: レビュアーは変更の妥当性を判断するために、変更前の状態を知る必要がある。「何をやったか」だけでは「もしかしたら変更前の動作の方が正しかったのでは？」という疑問が残る
2. 「問題→解決」や「現状→修正」のペアで書かれているか: 新機能の場合は目的・動機でも可。ただし「やったこと」だけの一方通行な説明は不十分
3. 変更の範囲が明確か: 何を変えて、何を変えていないのかがわかるか
4. 実装者自身の理解が見えるか: AIが生成した文章をそのまま貼っただけでなく、実装者が何を考えてこの変更をしたのかが伝わるか

外部Agent相談の共通方針

手順3・手順4・手順5では外部Agentにセカンドオピニオンを求める（ただし手順4の「長期視点で命名・設計を考察する」サブセクションは対象外）。手順6では疑わしい点がある場合に限り外部Agentへ相談する。以下のフォールバック順序に従い、推測で判断せず実際に呼び出して試すこと:

自分自身がCodex CLIの場合は2から開始する。そうでない場合は1から開始する。

1. Skill toolで codex-consultation を呼び出す。失敗した場合は2へ進む
2. Skill toolで subagent-consultation を呼び出す。失敗した場合は3へ進む
3. main agentが単独で作業を実行する

フォールバックが発生した場合や、外部Agentが利用できなかった場合は、報告書の「レビュー作業において発生した問題」セクションに記載する。

3（main agent単独実行）にフォールバックした場合は、このスキルのコアである批判的思考の連鎖（互いの主張を検討・反論しあい、正確性と網羅性を向上するプロトコル）が機能していないことを意味する。往復検証が欠落した状態でのレビューは本来の精度を持たないため、報告書の「レビュー作業において発生した問題」セクション冒頭に、以下の文言をそのままbold段落として記載すること:

⚠ 警告: 批判的思考の連鎖が機能していません、実行環境が正気である事を疑ってください

各手順では、外部Agentに渡すArgsの内容と、結果の扱い方を記載する。

手順3: 実装者の説明と実装の整合性確認

この手順の目的は、概要欄やコメントでの説明と実際のコードが一致しているかを確認する、ドキュメントとコードの読み合わせ である。

重要: 実装者の発言のみを拾う

PR概要欄の author と、各コメントの author を照合し、実装者本人の発言のみを実装の説明として扱う。 他の人が書いた応援コメント、機能に対する期待を込めたコメント、質問等は、実装の説明ではない。 これらを実装の説明と混同すると、整合性の判断を誤る。

確認事項

1. PR概要欄の説明と、実際の差分が一致しているか
2. インラインレビューコメントでの実装者の説明と、実際のコードが一致しているか
3. PRレビューの本文（top-level review comment）での実装者の説明と、実装が一致しているか
4. 対話コンテキストの内容と、実装が一致しているか（対話コンテキストがある場合）

齟齬を発見した場合は具体的に記録する。

外部Agentによる整合性確認

Agent自身の確認に加えて、外部Agentにも差分と概要欄の整合性を確認させる。 別の視点でコードを読むため、Agentが見落とした齟齬を発見できる可能性がある。

「外部Agent相談の共通方針」に従い、以下のArgsで呼び出す:

Args: よく相談して。PR #{番号} の概要欄の説明と実際の差分に齟齬がないか確認してほしい。{概要欄の要約と確認ポイント}

外部Agentの指摘を受け取ったら、自分の確認結果と照合し、見落としがなかったか確認する。

手順4: 命名・設計パターンの一貫性

この手順の目的は、実装が既存のコードベースの慣習と一致しているかを確認する、コードベースの読み解き である。 バグ・脆弱性を調べる前にコードベースを理解することで、後続の調査の精度が上がる。

確認事項

1. 命名規則の一致

   • ファイル名・関数名・変数名・クラス名が、既存コードの命名パターンと揃っているか
   • 機能の正式名称を歯抜けに省略した名前が導入されていないか

2. 設計パターンの一致

   • 構造・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に「よく相談して」を含めること。

手順7: レビュー報告書の作成

このSKILL.mdと同じディレクトリにある TEMPLATE.md を読み込み、その形式に従って報告書を作成する。

報告書は会話に出力する。 手順0でPRへのコメント投稿を行うと決めた場合は、同じ内容をPRにもコメントとして投稿する。

報告書作成のガイドライン

• 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の種類