コードレビュー

コードレビュースキル

PRをレビューするには、レビュー原則から導き出されたすべての質問を生成し、回答します。最終的には、具体的なPRコメントと推論の成果物への参照を含むドキュメントを作成します。

仕組み

コードレビューは尋問です。質問を生成し、すべてに回答し、不明瞭または懸念事項を明らかにします。

このスキルが生成するもの:

• レビュー原則から導き出された質問
• すべての質問への回答（または明示的な「作成者確認が必要」）
• 回答から導き出された含意
• カテゴリ別に整理された顕在化した懸念事項

このスキルが生成しないもの:

• 重大度のランク付け（致命的/重大/軽微）
• ブロッキング/非ブロッキングの分類
• 承認の推奨

プロセス: 0. セットアップ - PRブランチをローカルにチェックアウト

1. スカウト - PRの領域をマッピングし、初期質問を生成（浅い場合あり）
2. 質問の洗練 - 知識のギャップを埋め、本当の質問バックログを生成し、タイプ別に分類
3. 質問への回答 - 各質問を適切なハンドラーにルーティングし、Q&Aドキュメントを作成
4. 全体事前評価 - Q&Aを使用してアプローチを評価（ステップ5と並行）
5. コミットごとのレビュー - Q&Aを使用して各コミットをレビュー（並行） 5.5. 含意のフィルタリング - 二値の顕在化判断 + カテゴリ分類
6. 全体事後評価 - 再評価、要件充足の確認
7. 統合 - カテゴリ別に整理された懸念事項に結合

質問タイプとハンドラー:

• FACT → fact-findスキル（引用付き回答）
• RESEARCH → deep-researchスキル（教育用ドキュメント）
• DESIGN → 設計評価（代替案の提案、原則に照らした評価）
• CORRECTNESS → 正当性分析（コードのトレース、動作の検証）
• INTENT → 作成者確認が必要としてマーク（自己回答不可）

重要な洞察: すべての質問には明示的で文書化された回答（または明示的な「作成者確認が必要」）が与えられます。これにより検証可能な成果物が作成されます。

入力

• PR参照（URL、番号、またはブランチ）
• オプション: ユーザーが特定した重要な問題やドキュメント

セットアップ

開始前に、オーケストレーターがPRをチェックアウトします:

# ターゲットリポジトリディレクトリ内で
glh pr checkout <PR-number>

前提条件:

• 作業ディレクトリはPRを含むリポジトリであること
• 未コミットの変更がないこと（ダーティな場合は早期に失敗）
• GitHub CLIが認証済みであること

チェックアウト後、すべてのサブエージェントは gh CLIの差分ではなく、ローカルファイルシステムからコードを読み取ります。

ワークスペース

すべての成果物のために planning/<pr-slug>/ を作成します。これらの成果物はコミットしないでください — これらは作業ドキュメントであり、成果物ではありません。

planning/<pr-slug>/
├── 00-scout.md           # 初期領域マップ
├── 01-questions.md       # 洗練され、分類された質問バックログ
├── 02-answers.md         # 統合Q&Aドキュメント
├── answers/              # 個別の回答成果物
│   ├── fact-Q1.md
│   ├── design-Q2.md
│   └── ...
├── 03-commit-NN.md       # コミットごとのレビュー
├── 04-holistic-pre.md
├── filtered-implications.md  # 顕在化するカテゴリ別含意
├── 05-holistic-post.md
└── REVIEW.md             # 最終出力

サブエージェントプロトコル

渡すファイル: PRINCIPLES.md、エージェント指示ファイル、以前のフェーズの成果物

渡すデータ: workspace パス、フェーズ固有データ

応答:

OUTPUT: <ファイル名>
STATUS: ok | problems
NOTES: <問題がある場合>

STATUS: ok を信頼してください。problems の場合はメモを読み、判断してください。

リポジトリへのアクセス

レビュー開始前にPRはローカルにチェックアウトされます。サブエージェントは以下を受け取ります:

• repo_path: PRがチェックアウトされたリポジトリへのパス
• base_ref: ベースブランチ（例: main）
• head_ref: PRブランチ（チェックアウト済み）

サブエージェントは repo_path からファイルを直接読み取ります。差分には git diff {base_ref}...HEAD を使用します。

フェーズ

0. セットアップ

分析前にローカルでPRをチェックアウトします:

glh pr checkout <PR-number>

差分コマンドのためにPRメタデータから base_ref を取得します。

1. スカウト

エージェント: agents/01-scout.md ファイル: PRINCIPLES.md、エージェントファイル データ: workspace、repo_path、base_ref、pr_number、ユーザーコンテキスト 出力: 00-scout.md

2. 質問の洗練

エージェント: agents/02-refine-questions.md ファイル: PRINCIPLES.md、エージェントファイル、00-scout.md データ: workspace、repo_path、base_ref、関連Issue/ドキュメント 出力: 01-questions.md

このフェーズでは、fact-findを使用して知識のギャップを埋め、分類された質問バックログを生成します。

3. 質問への回答

01-questions.md の各質問に対して、適切な回答エージェントを起動します:

タイプ	エージェント	出力
FACT	agents/03-answer-fact.md	answers/fact-{id}.md
RESEARCH	agents/04-answer-research.md	answers/research-{id}.md
DESIGN	agents/05-answer-design.md	answers/design-{id}.md
CORRECTNESS	agents/06-answer-correctness.md	answers/correctness-{id}.md
INTENT	（スキップ—作成者確認が必要としてマーク）

可能な限り、回答エージェントを並行して実行します。

すべて完了後、02-answers.md に統合します:

# 回答済みの質問

| ID | タイプ | 質問 | 回答サマリー | 詳細 |
|----|------|----------|----------------|--------|
| Q1 | FACT | ... | ... | [answers/fact-Q1.md] |

## 作成者確認が必要
| ID | 質問 | 回答できない理由 |

4. 全体事前評価

エージェント: agents/07-holistic-pre.md ファイル: PRINCIPLES.md、エージェントファイル、01-questions.md、02-answers.md データ: workspace、PR説明、コミットメッセージ 出力: 04-holistic-pre.md

フェーズ5と並行して実行できます。

5. コミットごとのレビュー

エージェント: agents/08-commit-review.md（コミットごとに1つ、並行） ファイル: PRINCIPLES.md、エージェントファイル、01-questions.md、02-answers.md データ: workspace、repo_path、base_ref、commit_sha、commit_message、commit_number、total_commits、all_commit_messages 出力: 03-commit-NN.md

for each commit in PR:
    spawn commit_reviewer(
        commit_diff=commit.diff,
        commit_number=N,
        ...
    ) → 03-commit-{N}.md
# コミットごとに1エージェント - バッチ処理しない

5.5. 含意のフィルタリング

エージェント: agents/085-filter-implications.md ファイル: PRINCIPLES.md、エージェントファイル、すべての 03-commit-*.md データ: workspace 出力: filtered-implications.md

エージェントはコミットレビューファイルから含意と作成者への質問を直接解析します。

二値の顕在化判断（顕在化する/しない）とカテゴリ分類:

• correctness - 論理エラー、バグ、不正な動作
• assumption - 成り立たない可能性のある暗黙の前提
• type-system - 型安全性の問題、制約の欠落
• intent - 作成者の意図について明確化が必要な質問

spawn implication_filter(workspace=workspace) → filtered-implications.md
# エージェントは 03-commit-*.md ファイルから含意を抽出

6. 全体事後評価

エージェント: agents/09-holistic-post.md ファイル: PRINCIPLES.md、エージェントファイル、01-questions.md、02-answers.md、04-holistic-pre.md、すべての 03-commit-*.md、filtered-implications.md データ: workspace 出力: 05-holistic-post.md

7. 統合

エージェント: agents/10-synthesize.md ファイル: PRINCIPLES.md、エージェントファイル、すべての成果物 データ: workspace 出力: REVIEW.md

顕在化した懸念事項をカテゴリ（correctness、assumption、type-system、intent）ごとに整理します。重要度ではありません。

8. 納品

REVIEW.md をユーザーに提示します。

⚠️ ローカル限定: このスキルはローカルの成果物のみを生成します。最初の gh pr checkout 以外で、GitHubにコメントを投稿したり、何らかの形でGitHubとやり取りしたりすることはしないでください。レビュー出力はユーザーが手動でアクションを起こすためのものです。

トークン節約

あなたはオーケストレーションを行い、サブエージェントが分析します。ステータス応答を信頼してください。

中間成果物は読まないでください。ただし、以下は例外:

• STATUS: problems → メモを読む
• ユーザーが質問する
• 障害のデバッグ

常に読むもの: ステータス応答、REVIEW.mdの最終出力。

スキルファイル

skills/review-code/
├── SKILL.md
├── PRINCIPLES.md
└── agents/
    ├── 01-scout.md
    ├── 02-refine-questions.md
    ├── 03-answer-fact.md
    ├── 04-answer-research.md
    ├── 05-answer-design.md
    ├── 06-answer-correctness.md
    ├── 07-holistic-pre.md
    ├── 08-commit-review.md
    ├── 085-filter-implications.md
    ├── 09-holistic-post.md
    └── 10-synthesize.md