code-review-axes-and-quality

コードレビューの評価軸と品質

このスキルは、コミット範囲、機能、モジュール、または作業ツリーを体系的にレビューするために使用します。実行レイヤーとして委任モードを使用し、チャット上だけの所感ではなく、永続的な計画を作成します。

関連するコンパニオンスキル

このスキルの実行レイヤーとしてdelegation-modeを使用します。レビュー計画を作成または実行する前に、次を読んでください。

../delegation-mode/SKILL.md

そのワーカー契約、安定したタスク ID、.agents/plans/の出力規約、逐次実行／並列実行の選択ルール、検証済み結果ファイルのマーカー、セッションをまたいだDONE_IDSの再開手順に従ってください。このスキルではレビュー品質を定め、delegation-modeではレビューのディスパッチと再開方法を定めます。実行可能なレビュー用テンプレートでは、各評価軸の成果物を検証し、未解決のCRITICALまたはHIGHの指摘を無視した最終承認を拒否します。

レビュー用テンプレートでは、計画の識別情報、安全なパス、DONE_IDS、フロントマター、完了マーカー、永続ファイルのチェックに、共有のdelegation-mode検証コアを使用します。レビュー固有の評価軸要件と判定／ブロッカーチェックは、このテンプレート内で行います。

レビュー基準

すべての変更をマージ前にレビューします。ただし、承認基準は変更に見合ったものにしてください。コード全体の健全性が向上し、未解決のブロッキング問題がなければ、変更を承認します。個人的なスタイルの好みや完璧なコードへの期待を理由にブロックしてはいけません。テストが通ったから、あるいは作成者が自信を持っているからといって、内容を精査せず承認してはいけません。

すべての指摘は、証拠に基づき、実行可能な内容で、影響度の高い順に並べる必要があります。まず正確性とセキュリティ、次に構造上のリグレッションと見落とされた簡素化、その後に影響度の低い懸念を扱います。構造上の問題を指摘する場合は、コードが複雑だと述べるだけでなく、問題を解消するための変更案を示してください。

固定された評価軸

指摘がない評価軸も含め、10個すべての評価軸を実施してください。

#	評価軸	焦点
1	正確性	バグ、エッジケース、誤った前提、リグレッション
2	パフォーマンス	ボトルネック、不要な処理、レイテンシー、メモリ、ホットパス
3	スケーラビリティ	拡大、並行処理、入力の大規模化に伴う障害や劣化
4	インフラストラクチャ	既存プロジェクトの配線、境界、運用
5	ライブラリの健全性	依存関係、サポートされる API、バージョン、使用方法
6	セキュリティ	入力処理、認証、シークレット、インジェクション、SSRF、XSS、悪用
7	データ整合性と並行処理	原子性、冪等性、競合、順序、再試行
8	可観測性	ログ、メトリクス、トレース、アラート、診断、障害の可視性
9	保守性	結合度、凝集度、変更リスク、重複、アーキテクチャ
10	可読性	命名、制御フロー、局所的な理解のしやすさ、認知負荷

保守性と可読性は別の評価軸です。保守性では、将来の変更を安全かつ局所的に行えるかを評価します。可読性では、隠れた意図を推測し直さずに、現在の動作を理解できるかを評価します。

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

• 何が問題なのか
• ファイルと行、またはシンボル
• なぜ重要なのか
• 推奨する修正
• 重大度：CRITICAL、HIGH、MEDIUM、またはLOW

各評価軸の結果には、正確な対象範囲、割り当てられた評価軸、実際の検証証拠も含めてください。指摘がない評価軸には、指摘がなかったことを明記します。マーカーだけのファイルは、完了したレビュー結果ではありません。

指摘がない評価軸が完了とみなされるのは、レビューした対象範囲に指摘がなかったと明記されている場合に限ります。

軸ごとのガイダンス

各担当軸の範囲内で、次の観点から確認してください。

• 正確性： 動作を仕様やテストと照らし合わせてください。正常系だけでなく、null、空の値、境界値、再試行、タイムアウト、エラーの各パスも確認してください。状態の不整合、オフバイワンエラー、リグレッションがないかを探してください。
• パフォーマンス： N+1 クエリ、上限のない処理やフェッチ、回避可能な同期処理、ホットパスでのアロケーション、UI の再レンダリングコストを確認してください。
• スケーラビリティ： データ量、トラフィック、テナント数、並行性、ペイロードサイズが増えた場合の動作を確認してください。リソース制限、キューやバックプレッシャーの動作、競合、ファンアウトを調べてください。
• インフラストラクチャ： プロジェクトの連携、デプロイやランタイムの前提、設定、マイグレーション、運用上の境界、ロールバック動作、障害からの復旧を確認してください。
• ライブラリの健全性： 既存のスタックと標準ライブラリを優先してください。新しい依存関係について、メンテナンス状況、ライセンス、脆弱性、バンドルやランタイムへの影響、サポート対象 API、変更履歴やマイグレーションの注意事項、ロックファイルの変更を確認してください。
• セキュリティ： ユーザー入力、外部データ、ログ、設定は境界において信頼できないものとして扱ってください。検証、認可、シークレット、インジェクション、XSS、SSRF、不正利用対策、依存関係のサプライチェーンリスクを確認してください。
• データ整合性と並行性： アトミック性、冪等性、順序、再試行、競合、トランザクション境界、作業の重複、部分的な失敗を確認してください。
• 可観測性： 重要な成功パスと失敗パスについて、有用な構造化ログ、メトリクス、トレース、アラート、診断情報、エラーの可視性を確認してください。
• 保守性： 密結合、重複、共有モジュール内の機能ロジック、循環依存、複雑さを軽減せず別の場所へ移すだけの抽象化を探してください。不明瞭な型境界や、警告なしのフォールバックも確認してください。
• 可読性： 名前、制御フロー、局所的な理解のしやすさ、デッドコード、コメント、ファイルサイズ、無関係な処理フローに継ぎ足された条件分岐を確認してください。

レビュープロトコル

レビューでは、毎回次の順序で進めてください。

1. 意図を把握する。 タスクや仕様、関連する計画、現在のチェックアウト、最近のコミットを読みます。期待される動作の変更と、正確な対象範囲を明示してください。
2. まずテストを読む。 変更に関するテストを特定し、実装の詳細ではなく動作をテストしていることを確認して、不足しているリグレッションテストやエッジケースのカバレッジを記録してください。
3. 実装の全体的な文脈を読む。 差分の一部だけをレビューしてはいけません。動作を理解するために必要な呼び出し元、標準ヘルパー、型境界、設定、依存関係をたどってください。
4. 10 個すべての軸を確認する。 該当事項がない軸も含め、それぞれを分けて確認してください。影響が本当に異なる場合を除き、同じ指摘を複数の軸で繰り返してはいけません。最終レポートでは重複を整理します。
5. 検証の内容を確認する。 実際に実行したテスト、lint、型チェック、ビルド、手動確認、UI 変更のスクリーンショット、ベンチマーク、依存関係チェックを記録してください。実行していないチェックを実行したと主張してはいけません。
6. 判定を示す。 未解決の CRITICAL または HIGH の指摘が残っていない場合に限り、承認してください。優先度の低い作業を先送りする場合は、その理由、担当者や次の対応（判明している場合）、残存リスクを記録してください。

深刻度とステータスの判断

深刻度の意味を一貫して使用してください。

深刻度	意味	デフォルトの判断
CRITICAL	悪用可能なセキュリティ上の問題、データ損失、コア機能の破損、または本番環境への即時投入を妨げる問題	承認をブロックします
HIGH	発生の可能性が高いバグ、重大なセキュリティ上または契約上の問題、あるいは大きな影響を及ぼす構造上のリグレッション	通常は承認をブロックします
MEDIUM	影響範囲が限定された、保守性、パフォーマンス、スケーラビリティ、可観測性、または正確性に関する重大な不足	対象範囲内ならマージ前に修正し、それ以外は先送りする旨を記録します
LOW	影響が限定的な改善、仕上げ、または局所的な整理	プロジェクトのルールで定められていない限り任意です

アクションの状態には既存の Status 列を使用してください。 required、recommended、optional、accepted-risk、または resolved を指定します。レビュー対象の範囲内に修正され、検証済みであることを示す証拠がない限り、指摘事項に resolved のラベルを付けてはいけません。

構造上の解決策

問題が構造上のものである場合は、具体的な解決策を挙げてください。可動部分を減らせる選択肢を優先します。

• 条件分岐の連鎖を、型付きモデルまたは明示的なディスパッチャーに置き換える。
• 重複する分岐を、明確な単一のフローにまとめる。
• オーケストレーションとビジネスロジックを分離する。
• 機能固有のロジックを、それを所有するパッケージに移す。
• 似たものを新たに追加するのではなく、正式なヘルパーを再利用する。
• 型の境界を明確にし、下流の分岐をなくす。
• API を明確にせず、間接性を増やすだけの中継ラッパーを削除する。
• ヘルパーを抽出するか、大きなファイルを目的別のモジュールに分割する。

コードが一度重複しただけで、広範な抽象化を推奨しないでください。実際に共有される不変条件、または3つ目のユースケースによって正当化される場合に一般化してください。

変更の規模と分割

差分がテストに合格するかどうかだけでなく、変更後のファイルサイズと変更規模も確認してください。

~100 changed lines   → easy to review
~300 changed lines   → acceptable for one logical change
~1000 changed lines  → split the change
~1000 total lines in one file → inspection signal; consider decomposition

これらは確認時の目安であり、自動的な却下基準ではありません。変更が大きすぎる場合は、スタック、ファイルグループ別、横方向、または縦方向への分割を推奨してください。機能を安全にするために小規模な整理が必要な場合を除き、リファクタリングと新しい動作は分けてください。

デッドコードと依存関係の健全性

リファクタリング後は、到達不能または未使用のコードを明示してください。Axis ワーカーは、不確かなコードを黙って削除してはいけません。シンボルと未使用と見られる理由を列挙し、別途削除するか、検証済みの整理として判断することを推奨してください。

依存関係を変更する場合は、既存のスタックで問題を解決できるか、パッケージのメンテナンス状況とライセンス、既知の脆弱性、バンドルまたはランタイムへの影響、サポート対象の API、変更履歴や移行に関する注意事項、ロックファイルの差分を確認してください。1つの論理的な変更につき依存関係のアップグレードは1つにすることを優先し、ロックファイルを手作業で編集してはいけません。

作業の割り当て前に対象範囲を確認する

計画を作成する前に、次の作業を行ってください。

1. .agents/chats/current.md が存在する場合は読みます。
2. 関連する進行中の計画または参考計画を読みます。
3. 現在のチェックアウトと最近のコミットを確認します。
4. 正確なレビュー対象の範囲、または作業ツリーの対象範囲を特定します。
5. プロジェクトのルールと関連するメモリのトピックを読みます。

保存された引き継ぎ情報を現在のチェックアウトと照合してください。古いブランチ、ファイル、コミット、または検証済みという主張を決して信用しないでください。

再利用可能なプランを実行する

scripts/review-plan.template.js を次の場所にコピーします。

.agents/plans/YYYY-MM-DD-<slug>.js

DATE、SLUG、PROJECT_CONTEXT、レビュー範囲を入力します。次を選択します。

const MODE = "sequential"; // or "parallel"

各軸で、1 つのフラットなプランファイルを作成します。

YYYY-MM-DD-<slug>-01-correctness.md
...
YYYY-MM-DD-<slug>-10-readability.md
YYYY-MM-DD-<slug>-FINAL.md

軸ワーカーはファイルを書き込むため、config: { $kind: "general" } にする必要があります。 関連するファイルをすべて読み、アプリケーションのソースを変更せず、ファイル内に正確なマーカーを含め、指定のファイルに書き込んだ後にのみ終了する必要があります。

FILE_WRITTEN: <exact-path>

マーカーがない場合、ランナーは未解決として扱い、10 個すべての軸から確認があるまで集約しません。

各軸の結果には、次の内容を含める必要があります。

• 正確なレビュー範囲と関連する根拠。
• 担当する軸と、該当事項がない場合はその旨を明示した記述。
• 重大度、場所、影響、推奨される修正、ステータスを含む指摘事項。
• 実施した検証、または実施できなかった検証。
• 該当する場合は、構造上の改善策、デッドコードに関する注記、依存関係に関する注記。
  • FILE_WRITTEN: <exact-path> をファイルと応答の最後の空でない行にします。ディスパッチャーは応答だけでなく、ファイル自体を確認します。

セッションをまたいで再開する

実行が中断された場合：

ls .agents/plans/YYYY-MM-DD-<slug>-*.md 2>/dev/null

出力ファイルを確認し、確認済みの軸 ID のみで DONE_IDS を更新します。

const DONE_IDS = [
  "01-correctness",
  "02-performance",
];

プラン全体を再実行します。該当する ID はスキップされ、不足している軸のみがディスパッチされます。最終レポートが存在し、完全であることを確認してから、FINAL_DONE = true に設定します。チャットが無応答であることや、不完全なファイルから完了したと判断しないでください。

最終レポート

最終プランでは指摘事項の重複を除き、重大度順にマスターテーブルを並べ替え、具体的な優先作業項目をグループ化し、次のエージェントが作業に着手できる十分なコンテキストを提示します。さらに、次の内容も含める必要があります。

• コンテキストと意図の簡潔な概要。
• 判定：APPROVE、APPROVE_WITH_FOLLOW_UP、REQUEST_CHANGES のいずれか。
• 未解決のブロッカーと、対応を先送りした重大度の低いリスク。
• 検証の根拠と、明示された不足事項。
• 該当する場合は、変更規模／分割、依存関係、デッドコードに関する結論。

アプリケーションコードは変更しません。

レビュー後：

1. 10 個すべての軸ファイルと最終レポートが存在することを確認します。
2. フロントマターと相対リンクを確認します。
3. 該当するテスト、lint、型チェック、コンパイル、ビルドを実行します。
4. git diff --check を実行します。
5. 検証結果と未解決のリスクを最終プランに記録します。
6. CRITICAL または HIGH の指摘事項に、根拠なしで resolved が付けられていないことを確認します。
7. 未解決の CRITICAL または HIGH の指摘事項が残っている間は、承認を表明しないでください。 テンプレートではこの事後条件が適用されます。最終レポートには、機械可読な **Verdict:** 行を含める必要があります。