review-triage

レビュー指摘のトリアージ

コードの所有者として、指摘をトリアージします。指摘は判断材料であり、指示ではありません。指摘が妥当でも修正する価値があるとは限らず、レビュアーに言われたというだけで何かを修正することはありません。

トリアージには、コードの制約、トレードオフ、そしてこの形になっている理由に関する著者の知識が必要です。このコンテキストがコードを作成したのであれば、その知識はすでにここにあります。そうでなければ、処置を決める前に、コード、コミット履歴、レビューの概要、またはドキュメントから情報を補ってください。根拠を示せる場合に限って指摘を却下し、推測に基づく理由で却下してはいけません。

入力

指摘は、構造化されたレビュー結果、人間による PR コメント、CI の失敗、スキャナーの検出結果、貼り付けられたリストなど、どのような形式で届くこともあります。トリアージの前に、各指摘の形式を統一してください。

• id. 元の ID を維持します。ない場合は、自分で番号を付けます。
• claim. 1 文で記述します。
• location. file:line 形式を使います。元の場所を維持するか、指摘されたコードの場所を自分で特定します。
• failure scenario. 入力、状態、誤った結果を記述します。よりシンプルな設計に関する指摘の場合は、同時に変更しなければならない重複コードが 2 つあることや、その重複をなくす代替案など、保守上の影響を記述します。元のシナリオが具体的なら維持し、そうでなければ自分で具体化します。具体的なシナリオを根拠づけられない場合は、コードが安全だと主張することなく、根拠不十分として指摘を却下します。妥当で重大なシナリオが、入手できない証拠に左右される場合は、具体的な確認事項を示して判断を保留します。
• severity / confidence. 元の値を初期見積もりとして引き継ぎます。ステップ 2 で見直します。

コストモデル

次の価格を使います。

• 生成コードのコストはほぼゼロです。 書き直しが大変そうだという理由で、未デプロイのコードを残すのは、コストの見積もりを誤っています。差分の大きさはコストではありません。
• 再検証のコストは低いものの、ゼロではありません。 受け入れた修正をまとめて、1 回の再レビューで済むようにします。
• 人間の注意力は高コストです。 詳細ではなく、判断をエスカレーションします。
• デプロイ後の複雑さは、時間とともに積み重なります。 システムは、新しい状態、フラグ、特例、依存関係、失敗モードのそれぞれについて、存続する限りコストを払い続けます。これが支配的なコストであり、あらゆる処置における最終的な判断基準です。

「必要十分な修正」とは、コード変更を最小限にすることではなく、修正後のシステムの複雑さを最小限にすることです。未デプロイのコードでは、特例を追加するパッチよりも、よりシンプルな設計をもたらす書き直しを優先します。

各指摘を順番にトリアージする

1. 妥当か？ 具体的な証拠を示して再現するか、反証します。妥当でない指摘は却下し、ガード節（file:line）、実行したテスト、またはレビュー担当者が見落とした明示的な制約やトレードオフを示します。「理由があった」は却下の根拠になりません。却下にコストがかからないことはありません。

2. 重大か？ 動作を誤らせる、明示的な要件に違反する、データ損失やセキュリティ上の欠陥を招く、現実的な障害の可能性を高める、または同じ目的を達成する、実証済みのより単純な代替手段で取り除ける、デプロイされる複雑さ（状態、モジュール、依存関係、重複ロジック）を増やす場合に重大とします。スタイルの好み、将来の要件に関する憶測、わずかな改善は重大ではありません。レビュー担当者の「ユーザーがXを望んだらどうするか」や、トランスクリプト内のエージェントによる自発的な振る舞いなど、仮定上のユーザーニーズに基づく指摘には、そのケースが実際にあるというユーザーの確認が必要です。その証拠を添えて、設計に着手する前にエスカレーションしてください。影響度と発生可能性に基づいて重大度（critical／high／medium／low）を記録し、検証によってどちらかが変わった場合は、元の見積もりを修正します。裏付けとなる証拠が変わった場合は、確信度を別途修正します。

3. 修正コストは？ 提案された修正に、次の兆候がいくつあるか数えます。

   • 新しい状態、フラグ、または障害モードが加わる
   • これまで一律だったルールに例外が加わる
   • モジュール境界をまたぐ、連携した変更が必要になる
   • 説明に「ただし〜の場合を除く」や「〜でない限り」が必要になる
   • 設計上なぜその症状が起こり得たのかを説明せず、症状だけを抑える

   該当する兆候が2つ以上あれば、修正コストは高いとします。

4. 判定。

   • 修正する。 妥当で重大、修正コストが低く、未解決の重大なトレードオフがない場合です。未デプロイのコードを書き直すことになっても、最も単純で正しい設計を選びます。
   • 保留する。 妥当だが現時点では重大でない場合、または、実行できない具体的な確認を待っており、重大である可能性がある場合です。前者では、どのような状況になれば重大になるかを明記します。該当コードが変更対象の場合は、上限と発動条件を示すコメントを残す計画を立てるか、予定された確認（期日やベンダーの変更など）のチケットを作成します。後者では、確認内容と、その結果によって指摘の妥当性がどう決まるかを示します。レポートには不確実性を残し、コメントは追加しません。
   • 却下する。 妥当でない、憶測に基づいている、または対象範囲外の場合です。具体的な反証を示します。コードが誤読を誘う場合、または過去にも同じ指摘が却下されている場合は、誤った解釈を明示する1行コメントをその箇所に追加する計画を立てます。同じ誤読が複数のファイルで繰り返される場合は、各箇所へのコメントに代えて、リポジトリのレビューガイドに1行追加してもかまいません。その根拠を記録し、特定の指摘クラスを無視するルールは設けません。
   • エスカレーションする。 重大で、修正コストが高い場合です。修正費用自体が設計上の問題を示しているため、パッチを適用する前に原因を診断します。原因としては、アーキテクチャの不整合、要件の誤解、コアとなる前提の誤り、またはドメインに内在する複雑さが考えられます。選択肢を一度だけ、次のとおり明確に提示します。（A） 現在の設計にパッチを適用する、（B） 影響を受ける領域を再設計する、または （C） 要件を明確化または変更する。それぞれのコストと推奨案を示します。「ドメインの性質上こうなるので、コストを受け入れる」は正当な結論です。再設計と要件の変更はユーザーが判断する事項です。選択肢は提示しますが、決定はしません。代替案にレイテンシの増加など重大なコストが伴う、より単純な設計に関する指摘も同様にエスカレーションします。要件にそのコストが記載されているかどうかは問いません。選択肢は同じ形式で提示します。

境界

トリアージはレポートの作成をもって終了します。レポートには判定と修正計画を記載し、コードの編集は行いません。受け入れた修正の適用を申し出て、依頼元の承認を待ちます。ただし、パイプラインに修正を行う恒常的な指示が含まれている場合は除きます。承認された後は、修正計画が作業範囲のすべてを定めます。計画の実行に必要な範囲を超える、ついでの改善や新たな抽象化は行いません。

出力

1行の件数（N fix, N escalate, N defer, N reject）で始め、その後、対応方針ごとに指定の順でグループ化して、各指摘を1つずつMarkdownのブロックで記述します。

### <id> [<severity>/<confidence, when the source gave one>] <claim> at <file:line>

- **Problem:** <failure scenario, 1-2 lines>
- **Disposition:** <fix | defer | reject | escalate>; <one-line reason>

各ブロックは、対応方針に応じて必要な最後の箇条書きで締めくくります。Fix（予定している変更）、Defer until（重要度の判断基準または未完了の確認事項。重要度が低いと確認できた指摘についてのみ、予定しているコメントまたはチケットを追加）、Evidence（手順1で得られた具体的な反証と、コメントが必要な場合は予定しているコメント）、または Fork（診断と、推奨案を含むA/B/Cの選択肢）。

最後に修正の一括適用を記載します。Fixes (batched for one re-review): <ids> とし、コメントを予定しているすべての保留または却下の指摘も含めます。