code-review

コードレビュー

ミッション

依頼された範囲において、実用上可能な限り詳細なレビューを行います。主な出力は、指摘事項と確認範囲の根拠です。称賛、スタイル上の好み、広範なリファクタリングの提案は二次的なものです。

調整エージェントは、スコープ、最終判断、重複の排除、重大度、永続化されるレポートに責任を持ちます。サブエージェントは範囲を限定した分析を提供します。その結論を独立した統合なしにレポートへコピーしてはいけません。

必須リソース

• レビュー作業を委任する前に、references/subagent-orchestration.md を読んでください。
• references/report-template.md を使ってレポートを作成してください。
• 世代 0 は python3 scripts/validate_review_report.py <report-path> で検証してください。世代 1 は、追加で --parent-report <generation-0-report> --parent-resolution <resolution-report> 引数を指定して検証してください。

厳守事項

• 実質的なレビューに入る前に、ベースライン、変更ファイル一覧、差分の規模、既知の制約に基づいて、調整エージェントがスコープとリスクを評価してください。
• 分解方法が不確かな場合、または独立したリスク分析によって計画が大きく改善される場合に限り、その評価を委任してください。ツールが利用可能というだけでは、委任の理由になりません。カバレッジへの効果とコンテキスト共有のコストを考慮して、専門家を選んでください。
• 環境にサブエージェントのプリミティブがない場合は、Subagent unavailable と記録し、同じ評価手順を調整エージェントが実行してください。実際に実行されていないのに、サブエージェントが実行されたと主張してはいけません。
• すべてのレビュー用サブエージェントを読み取り専用にしてください。ファイルの編集、ステージング、コミット、プッシュ、リセット、チェックアウト、リベース、Git の状態変更を行ってはいけません。
• レビューの段階は読み取り専用にしてください。ユーザーが修正も依頼している場合は、レポートを完成させて確定した後、既存の実装許可の範囲内で作業を続けてください。別途依頼を求める必要はありません。レビューのみの依頼の場合は、レポートを作成して終了してください。
• すべてのレポートをレビューのチェーンに含めてください。確定した初期スコープには世代 0 を使用してください。receiving-code-review の resolution の後、実装差分と影響を受ける実行チェーンを対象とする場合に限り、世代 1 を使用してください。
• 世代 1 は最終世代として扱ってください。レポートを作成し、残りの指摘事項をユーザーまたはプロダクトオーナーに返し、receiving-code-review を自動で実行しないでください。それ以降の作業には、ユーザーからの明示的な依頼と、新しい世代 0 のチェーンが必要です。
• 期待される動作の根拠が権威ある情報源で確認できない場合、見解が分かれているプロダクト上の選択を Blocker、Major、Minor に分類してはいけません。プロダクトの意図が未確認であれば、Question を使用してください。

スコープと識別情報

1. 依頼されたスコープ（ワーキングツリー、ステージ済み差分、コミット範囲、ブランチ差分、プルリクエスト、ファイルセット、貼り付けられたコード）を特定してください。
2. 明示的な指定がない場合は、妥当な範囲で最も狭いスコープを選んでください。ステージ済み変更がある場合はそれを優先し、それ以外の場合はワーキングツリーを HEAD と比較してください。
3. ベースラインと対象を正確に記録してください。利用可能な場合はコミット SHA を使用してください。
4. レビューチェーン ID を作成し、世代、トリガー、親の resolution の ID／パス、スコープモードを記録してください。世代 1 では、レビューの前に親の resolution 全体を読んでください。
5. 実用上可能な場合は、ベースライン、対象、変更パス、正規化した差分ハッシュからスコープフィンガープリントを計算してください。フィンガープリントを利用できない場合は、その理由を記録してください。
6. 意図を判断する前に、要件、課題の記述、PR の説明、設計メモ、マイグレーション、関連する契約、確定済みの親 resolution の決定事項を読んでください。
7. 世代 0 のスコープは確定してください。世代 1 では、実装差分と、それが影響を与える可能性のある呼び出し元、呼び出し先、契約、実行チェーンのみをレビューしてください。元の探索範囲全体を再び開いてはいけません。
8. スコープを暗黙に拡大してはいけません。無関係なコンテキストは、現在のチェーンにおける指摘事項ではなく、補足的な根拠またはフォローアップとして示してください。

オーケストレーション

1. コーディネーター、または妥当な理由を示した読み取り専用の評価担当者が、スコープの識別情報、差分の一覧、変更統計、変更対象のサブシステム、既知の要件、環境上の制約を評価します。
2. 構造化された判断を記録します。判断は Single reviewer または Parallel specialists とし、その理由、リスクの観点、提案する分担、重複への対応計画、検証の必要性を含めます。評価サブエージェントが不要だった場合は、Coordinator assessment - <reason> を使用します。コーディネーターが単独レビュアーを兼ねてもかまいません。
3. 具体的な新たな根拠により判断が無効にならない限り、その判断に従います。判断を覆す場合は、その変更と理由を記録します。
4. 並行レビューでは、範囲を限定し、互いに重複しない担当を割り当てます。一般的な観点は次のとおりです。
   • 正確性、状態、データフロー、API 契約
   • セキュリティ、プライバシー、認証、権限、信頼境界
   • テスト、リグレッション、エラーパス、並行処理、信頼性
   • マイグレーション、永続化、互換性、統合、パフォーマンス、運用
   • フレームワークまたはドメイン固有のセマンティクス
5. 各スペシャリストには、候補となる指摘、確認した範囲、却下した候補、不確実性、根拠への参照先を報告するよう求めます。
6. 最終レポートに含まれる可能性のある候補ごとに、関連するコードと根拠を読み直します。意見の相違は明示的に解決し、最終的な F#、T#、A# ID はコーディネーターだけが割り当てます。

詳細レビューの要件

リスクが波及する可能性がある場合は、変更行以外もレビューします。次の項目を評価できる範囲まで追跡します。

• 呼び出し元、呼び出し先、共有ユーティリティ、アダプター、別のエントリーポイント
• 入力検証、認可、信頼境界、シークレット、プライバシー、安全でない外部作用
• 状態遷移、永続化、マイグレーション、シリアライズ、互換性、ロールバック、データ損失
• リトライ、冪等性、順序、キャッシュ、並行処理、競合、タイムアウト、部分的な失敗、クリーンアップ
• パブリック API、CLI、UI、生成出力、設定、依存関係、デプロイに関する契約
• 正常系、異常系、境界値、リグレッション、統合、マイグレーションのテストカバレッジ
• 確信度が大きく変わる場合の、焦点を絞った非破壊的なコマンドによる実行時の挙動
• 意図された変更を不具合として誤って報告しないための、要件と意図的な挙動の変更

指摘を採用する前に、期待される挙動の根拠を確立します。

1. まず、ユーザーまたはプロダクトオーナーによる現在の明示的な決定と受け入れ基準を優先します。
2. 次に、公開されている契約、承認済みの設計またはマイグレーションの決定、セキュリティ、プライバシー、コンプライアンス、データ整合性に関する不変条件を使用します。
3. テスト、現在のコード、履歴は挙動を示す根拠として扱い、それ自体をプロダクトの判断基準とはしません。
4. 意見の相違がプロダクト上の選択に関するもので、権威ある根拠がない場合は、不具合ではなく、解決基準を添えた承認に影響する Question を提示します。
5. 1 世代目では、親の解決結果にある Intentional、Disproved、Stale、Duplicate の判断を引き継ぎます。関連するコード、適用される契約、または重要な根拠が変わった場合に限り、同じ意味上の問題を再検討します。kind:<code|contract|evidence>; ref:<具体的な情報源>; change:<具体的な差分> を記録します。None、unknown、テンプレート文などのプレースホルダー参照や変更内容では、再検討の根拠になりません。

検索、履歴、blame、実行時チェック、対象を絞ったテストは、根拠を強化する場合に限って使用します。lint、型チェック、無関係なテストの成功は、衛生状態を示す根拠であり、挙動の安全性を証明するものではありません。

変更されたレビュー対象の領域、または影響が不明な領域をすべて確認し、意味のある候補を判定し、残る見落としの可能性を明示するまで、レビューを終了しません。

完全性に関する契約

• レビュー対象範囲内で合理的に発見できる、互いに異なる指摘をすべて列挙してください。最も重大なリスクだけに限定しないでください。
• 安定した A# 領域 ID を使って Review Coverage Ledger を維持してください。レビューに関係する変更箇所、または影響が不明な箇所はすべて、次のいずれかに対応付けてください。
  • Finding F#
  • Reviewed - no issue found
  • Not review-relevant
  • Not covered
• 独立したテスト不足にはそれぞれ安定した T# ID と重大度を付けてください。
• すべての F# と T# に、正規の意味的な問題キーを付けてください。指摘には behavior; entry=<semantic entry>; contract=<stable expectation>; effect=<terminal failure>、独立したテスト不足には test-gap; entry=<semantic entry>; contract=<stable expectation>; gap=<missing coverage> を使用してください。行番号、レポート内の ID、生成情報、現在の実装上のシンボルは含めないでください。指紋は ifp-sha256:<sha256 of the exact UTF-8 issue key> として計算し、同じ指摘を世代間で識別できるようにしてください。
• 意味のある却下候補や統合候補は、Subagent Candidate Adjudication またはエビデンス付録に記録してください。
• コンテキスト、認証情報、ランタイム、差分の大きさ、その他の制限により完全なレビューができない場合は、レポートを Incomplete とし、未確認の箇所を正確に示してください。
• 部分的なレビューを完全なレビューとして提示してはいけません。

指摘事項とエビデンス

同じ障害モード、影響を受ける契約、セキュリティ境界、データリスク、承認判断に対する指摘は 1 件にまとめてください。同じ不具合の繰り返し発生は統合し、影響が実質的に異なる場合は分けてください。

優先する項目：

• クラッシュ、誤った結果、古いデータや失われたデータ、可用性の障害、壊れたエッジケース
• ユーザー向け機能、API、CLI、永続化、認証、権限、再試行、順序、キャッシュ、統合におけるリグレッション
• インジェクション、安全でないデシリアライゼーション、認証のバイパス、シークレットの漏えい、SSRF、XSS、CSRF、過度に広範なアクセス、安全でないファイルシステムや依存関係の使用
• リスクの高い変更動作、特に修正、権限、マイグレーション、並行処理、障害に関するテストの不足
• 具体的なレビューリスクにつながる場合に限り、保守性の問題

採用する指摘にはすべて、次の内容を含めてください。

• 指摘を箇所、動作経路、出力、テスト不足、またはカバレッジの欠落に結び付ける
• 検証済みの事実と推論を区別する
• 前提条件を明示し、証明が不完全な場合は確信度を下げる
• Look here first には主要なコードリンクを 1 つまたは 2 つだけ含める
• その指摘を提案したレビュアーと、コーディネーターがどのように検証したかを記録する
• 構造化された期待動作の根拠、正規の問題キー、検証済みの意味的な問題の指紋を記録する

不具合を捏造してはいけません。問題がない場合でも、完全なカバレッジ台帳、最大の死角、検証記録が必要です。

重大度と推奨事項

レポートテンプレートで定義されている Blocker、Major、Minor、Question を使用してください。

未解決の指摘と独立したテスト不足は、次の優先順位で推奨事項に反映してください。

1. Blocker が 1 件でもある場合 -> Block。
2. それ以外で Major が 1 件でもある場合 -> Changes requested。
3. それ以外で承認に影響する Question が 1 件でもある場合 -> Discuss。
4. それ以外でレビューに関係する箇所、または影響が不明な箇所に Not covered が 1 件でもある場合 -> Discuss。
5. それ以外で Minor が 1 件でもある場合 -> Pass with caveat。
6. それ以外 -> Pass。

裏付けのないブロッカーの疑いは、曖昧な Blocker のままにせず、重大度を下げてください。承認に影響しない単なる好奇心のために Question を使用してはいけません。

永続化と引き継ぎ

• 正式な code-review レポート契約に従って、常に新しい Markdown レポートを作成します。
• 一意のレポート ID とファイル名を生成します。既存のリポジトリのレポート規約に従い、規約がない場合は tmp/reviews/YYYY-MM-DD-code-review-report-<random-id>.md を使用します。
• 既存のレポートを上書きしないでください。
• スコープの識別情報、スコープのフィンガープリント、オーケストレーションの判断、専門家への割り当て、候補の裁定、指摘事項、テストの不足、カバレッジ、エビデンス、および Receiving Handoff セクションを永続化します。
• レビューチェーンの識別情報、世代、トリガー、親レビューと解決内容、意味的な問題キーとフィンガープリント、期待動作の根拠、および継承された解決事項との整合性確認を永続化します。
• 完了したレビュー レポートは固定の入力成果物として扱います。受領または実装中に書き換えないでください。後続の処置やコード変更は、Report ID でリンクされた別の receiving-code-review 解決レポートに記録します。
• generation 0 のレポートは、Automatic receiving permitted が No でも receiving-code-review を実行できる状態の場合があります。準備状況は成果物の状態を示すものであり、ユーザーの許可を示すものではありません。準備ができており、ユーザーが続行を許可したレポートに限り Yes を使用します。レビューのみの依頼では No を使用します。generation 1 のレポートでは終端の引き継ぎを使用し、自動的に処理してはなりません。
• Question 以外のすべての指摘事項と、独立したすべてのテスト不足項目を、実行可能または延期の引き継ぎ ID に一度ずつ割り当てます。すべての Question と Not covered の領域を、対応する未解決 ID フィールドに列挙します。
• バリデーターを実行し、レポートの完了を宣言する前にすべてのエラーを修正します。

ワークフロー

1. レビューチェーンの識別情報、世代、トリガー、スコープ、ベースライン、対象、および最小限の差分インベントリを確定します。
2. コーディネーターがオーケストレーションを評価するか、正当な理由がある場合は評価を委任します。
3. 単独レビュアーまたは専門家による計画を記録し、実行します。
4. 意味的な差分インベントリと A# カバレッジ領域を作成します。
5. 変更された制御、データ、セキュリティ、永続化、統合、およびテストの各パスを追跡します。
6. 確信度を実質的に高める場合は、対象を絞った検証を実行します。
7. 指摘候補と専門家によるカバレッジ結果を収集します。
8. 期待動作の根拠と継承された解決事項に照らして、すべての候補を独立して検証し、重複を排除し、異議を唱え、分類します。
9. 最終的な F#、T#、A# の ID と意味的な問題フィンガープリントを割り当てます。
10. 未解決項目とカバレッジに基づいて推奨事項を導き出します。
11. テンプレートから正式なレポートを作成します。
12. scripts/validate_review_report.py を実行し、すべてのエラーを修正します。
13. レポートのパス、推奨事項、完了状況、重要度別の件数、オーケストレーションモード、および主なリスクを含む短い要約を返します。

最終セルフチェック

• レポートに、実際の評価モードとその根拠が記録されています。コーディネーター、評価の委任、または利用不可の場合の代替手段のいずれかです。
• オーケストレーションの判断は、任意のエージェント数ではなく、スコープとリスクに基づいています。
• 専門家が提示したすべての候補は、エビデンスに基づいて検証、却下、統合、または採用されています。
• 変更されたレビュー関連領域、または影響が不明な領域には、すべて A# 行があります。
• すべての F# と T# には、正式な期待動作の根拠があるか、明示的に Question とされており、一意の意味的な問題フィンガープリントがあります。
• generation と引き継ぎに矛盾がありません。generation 0 では受領を許可でき、generation 1 は終端となり、その親の解決内容にリンクされています。
• インデックス化されたすべての指摘事項には対応するカードがあり、すべての Finding F# 領域は実在する指摘事項を参照しています。
• すべての Not covered 行には、理由と具体的な次の手順があります。
• 推奨事項の対応付けが正確です。
• レポートのバリデーターが成功します。
• Git の状態に変更がありません。