GitHub ディープレビュー
Peter 流にレビューする:高い確信度、エビデンス優先、コード認識、そして手がかりが弱いときは「証明されていない」と述べる。目標は一般的な要約ではない。目標はバグクラスを理解し、可能なら真の原因を見つけ、十分なコードを読んだ後に最適な修正を決定し、より大規模なリファクタリングが設計を改善するかどうかを指摘することである。
開始
GitHub 参照には、Web ブラウジングではなく gh を使用する:
gh issue view <n> --json number,title,state,author,body,comments,labels,updatedAt,url
gh pr view <n> --json number,title,state,author,body,comments,reviews,files,commits,statusCheckRollup,mergeStateStatus,headRefName,headRepositoryOwner,url
gh pr diff <n> --patch
PR の場合、作成者が Peter (steipete または明らかに Peter が所有するアカウント) でない限り、デフォルトで作成者のコンテキストを収集する。~/Projects/agent-scripts/skills/github-author-context/SKILL.md のローカルワークフローを使用し、作成者が Peter でない場合は、レビューの先頭近くに短い Author context: ブロックを含める。マージ/却下/クローズ/レビュー後、同じ作成者コンテキストワークフローを使用して、将来のレビューシグナルとして持続可能なインタラクションがあった場合にのみ、コントリビューターノートを追加する。
リポジトリローカルレビューの場合は、以下も調査する:
git status --short --branch
git fetch origin
git log --oneline --decorate -20
rg "<key symbol/error/config/endpoint>"
リポジトリにローカル手順、issue/PR スキル、ドキュメントリスト、テストガイダンス、またはメンテナーラン ブックがある場合は、決定する前にそれらを読む。
レビュー契約
常に以下に明示的に回答する:
- URL/参照:issue または PR 番号と影響範囲。
- 修正されるバグまたは動作は何か?
- 根本原因を特定できるか? できる場合、コード内のどこで、なぜか。できない場合、欠落しているエビデンスは何か。
- 回帰の場合、誰/何によって、いつ導入されたか? 限定された履歴で追跡可能な場合は、コミット/PR の来歴を含める。推測する代わりに不明と記載する。
- 現在/提案されている修正は、隣接コードを読んだ後の最善の修正か?
- より大規模なリファクタリングは、正確性、明確性、将来の保守性を向上させるか?
- どのような証明が存在するか:テスト、ライブ再現、CI チェック、ドキュメント、依存関係のドキュメント/ソース、出荷/現在の動作。
- 何がリスクまたは未検証のままか。
コード読み取り深度
最初に触れたファイルを超えて読む。実際の呼び出しパスをたどる:
- エントリポイント -> 検証/解析 -> ルーティング/ディスパッチ -> オーナーモジュール -> 共有ヘルパー -> 永続化/ネットワーク/ランタイム境界
- 設定/スキーマ/ドキュメント -> ランタイム使用 -> 診断/マイグレーション/修正パス
- プロバイダー/チャネル/プラグインオーナーコード -> 汎用コア境界(複数のオーナーが必要な場合のみ)
- 影響範囲の周辺のテストと隣接する回帰テスト
動作が依存関係に依存する場合、想定する前に上流のドキュメント/ソース/型または現在のパッケージ契約を読む。
issue のコメントよりも、現在のソースと実行可能な証明を優先する。再確認されるまで、古いコメント、古い CI、および古いリリース動作はヒントとして扱う。
来歴
バグ/回帰レビューの場合、実行可能な場合はコンパクトな Provenance: 回答を含める:
git log -S/-G、git blame、リンクされた PR/issue、およびテストを使用する。- 作成者、コミッター/マージャー、現在の PR 作成者が異なる場合は分離する。
introduced by、made visible by、またはcarried forward byとして表現する。- 確信度を含める:
clear、likely、またはunknown。 - 機能、ドキュメント、リファクタリング、または追跡不可能なバグの場合は、
N/Aと記述するか、欠落しているエビデンスを述べる。
修正品質基準
優れた修正は通常:
- バグが属する所有権境界に存在する
- 問題がその廃止に関するものでない限り、パブリック/後方互換性のある動作を維持する
- 最小の意味のある境界で回帰テストを追加する
- 広範な特殊ケース、隠れたマイグレーション、意味上のセンチネル、汎用コア内のプロバイダー/チャネル ID を回避する
- ユーザーに見える動作が変更された場合、ドキュメント/チェンジログを更新する
- ランタイムパスで明確に失敗し、それが確立された契約である場合、診断/マイグレーションパスを通じて修復する
修正が単なる症状レベルの場合に指摘する。少し大規模なリファクタリングによって不変条件が明らかになり、将来のバグが減少する場合は、それを推奨する。リファクタリングがバグクラスを改善せずにリスクを広げる場合は、そのように述べる。
PR レビューの形式
PR をレビューするときは、調査結果を先頭にする。調査結果には、ファイル/行/シンボル参照と具体的な障害モードが必要である。あいまいな「考慮」コメントは避ける。
ブロックする問題がない場合:
- ブロックする正当性の問題は見つからなかったと述べる
- 確認した最も強力な証明をリストする
- 残りのリスク/テストのギャップを挙げる
- 設計が利用可能な最良の形状であるかどうかに回答する
ユーザーがそのアクションを要求しない限り、承認、コメント、クローズ、マージ、プッシュ、またはランディングを行わない。
Issue レビューの形式
バグ/issue の場合:
- 報告者のシナリオと影響を受けるバージョン/範囲を再構築する。
- 現在の
mainですでに修正されているか確認する。 - 実行可能な場合、最小限のローカル/ライブ証明を再現または作成する。
- 明確な場合、根本原因を特定し、修正を提案する。
mainで解決されている場合、ユーザーが要求した場合のみコメント/クローズする。既知の場合は、証明と正規のコミット/PR を含める。
再現が実行不可能な場合、何がそれを阻害しているか、および決定を信頼できるものにするためにどのようなエビデンスが必要かを正確に述べる。
出力テンプレート
ユーザーが「これは何についてか」「これが最善の修正か」「何を修正したか」と尋ねた場合、次の形式を使用する:
Ref: #123 / PR #456
Surface: <runtime/CLI/provider/channel/docs>
Bug: <1〜2文>
Cause: <コードパス + 確信度>
Provenance: <introduced/made visible/carried forward by commit/PR/date, または N/A/unknown>
Best fix: <何を変更すべきか、なぜか>
Refactor: <yes/no、具体的な形状>
Proof: <tests/live/CI/source/dependency docs>
Risk: <残りの不確実性>
```\n簡潔に保つが、原因/修正/リファクタリング/証明の判断を省略しない。