software-code-review

コードレビュー

このスキルは、既存の変更をレビューするためのものです。SKILL.mdをツールカタログにすることなく、適切なチェックリスト、レビュー方式、プラットフォームのワークフローへエージェントを案内します。

クイックリファレンス

タスク	使用するもの	主な参照先
一般的なPRまたは差分のレビュー	基本のレビューフローと重大度基準	references/operational-playbook.md
AI生成またはエージェント作成の変更	人間が関与するレビューのルールとプラットフォームの制御	references/automation-tools.md
AIレビューのツールやインテグレーションの構築・調整	事前レビューの決定論的ゲート、サイズに応じた計画パス、自己反証フィルターパス	references/deterministic-vs-llm-routing.md
バックエンド／APIのレビュー	エラー処理、コントラクト、永続化、運用性	assets/backend-api/api-review.md
フロントエンドのレビュー	アクセシビリティ、レスポンシブ動作、Core Web Vitals	assets/web-frontend/frontend-review.md
モバイルのレビュー	プラットフォームのパターン、ライフサイクル、権限、UX	assets/mobile/mobile-review.md
インフラストラクチャのレビュー	CI/CD、IaC、シークレット、デプロイの安全性	assets/infrastructure/infrastructure-review.md
スマートコントラクトのレビュー	アクセス制御、再入可能性、安全でない前提	assets/blockchain/crypto-review.md
データ／MLのレビュー	パイプライン、実験、モデル、デプロイ	assets/data-ml/ml-diff-review-overlay.md

このスキルを使用する場合

主なタスクが次のいずれかの場合に、このスキルを使用します。

• PR、マージリクエスト、または差分をレビューする
• 正確性、セキュリティ、信頼性、保守性に関する問題を見つける
• テストの不足とリグレッションのリスクを評価する
• AI生成またはエージェント作成の変更を、マージ前に批評する
• 動作を維持する小規模なリファクタリングを提案する

このスキルを使用しない場合

• グリーンフィールドのアーキテクチャ → software-architecture-design
• 詳細なAppSec設計または正式な脅威モデリング → software-security-appsec。このスキルは汚染の経路と不足している制御を指摘し、関連するスキルが修正方法を設計します
• 測定に基づくパフォーマンス調査（プロファイリング、負荷テスト、キャパシティ） → 最適化にはsoftware-performance、テスト設計にはqa-testing-performanceを使用します。このスキルは差分で確認できるホットパスのリグレッションを指摘し、測定が必要な項目を引き継ぎます
• 新機能をゼロから実装する → スタック固有の実装スキルを使用します
• レビューエージェントのチームを選定または起動する（レビュー委員会、並列レビュー担当者、ディベート） → agents-subagents。このスキルは、各レビュー担当者が適用するレビュー基準を引き続き提供します

ワークフロー

1. レビュー対象を確認します。差分、PR、マージリクエスト、生成コード、または対象を絞ったファイル群が該当します。
2. レビューが主なタスクでない場合は、アーキテクチャのみの質問や正式なセキュリティ設計の質問を、関連するスキルに振り分けます。
3. 変更された制御フローとデータコントラクトをたどり、次の順序でレビュー方式を適用します。正確性、セキュリティ、信頼性、パフォーマンス、保守性。
4. コードにその分野固有の視点が実際に必要な場合に限り、スタック別のオーバーレイを適用します。
5. 根拠を添えて具体的な指摘を返し、プラットフォーム固有の主張はナビゲーション用の参照先で確認します。

レビュールーティング

ユーザーがより狭い範囲を指定しない限り、次の順序でレビュー方式を適用してください。

1. 正確性とエッジケース
2. セキュリティとデータの取り扱い：差分内の各シンクに対する制御可能な入力を追跡します（security-focused-review-guide.md）。パッチではなく脅威モデルの検討が必要な指摘は、software-security-appsec に回します。
3. 信頼性と運用性
4. パフォーマンスとコスト：差分で確認できるホットパスのリグレッションのみを対象とします。測定に関する質問は software-performance に回します。
5. 保守性とテストカバレッジ

スタック別オーバーレイ：

• フロントエンド：assets/web-frontend/frontend-review.md
• バックエンド／API：assets/backend-api/api-review.md
• モバイル：assets/mobile/mobile-review.md
• インフラストラクチャ：assets/infrastructure/infrastructure-review.md
• ブロックチェーン：assets/blockchain/crypto-review.md
• データ／ML：assets/data-ml/ml-diff-review-overlay.md

プラットフォーム別オーバーレイ：

• GitHub：Copilot レビュー、リポジトリの指示、除外ファイル、Code Quality、マージキュー
• GitLab：Duo レビューの指示、マージリクエストの承認、承認ルール
• Bitbucket：Code Insights、ブランチ制限、必須チェック

ユーザーからプラットフォーム固有の自動化について質問された場合は、まず data/sources.json の公式情報を確認し、references/automation-tools.md を使用してください。

AI 支援レビューのルール

• 人間によるレビューが最終判断です。AI の指摘は確認されるまでは助言として扱います。
• AI 生成コードやエージェントが作成した PR は、レビューの手間が少ないタスクではなく、より多くのコンテキストを必要とするタスクとして扱ってください。ボトルネックはコード作成から検証に移るため、自動化によってレビューの作業量が減ると想定せず、それに応じてレビュアーの時間を確保してください。
• AI 生成コードは抽象的なスタイルガイドではなく、このコードベースの実際の規約に照らして評価してください。一般に慣用的かどうかより、周囲のコードとの一貫性を重視します。
• サードパーティ製ボットより、プラットフォーム標準の制御機能を優先してください。
  • リポジトリまたはパス固有のレビュー指示
  • 除外ファイル／生成ファイルのフィルター
  • 必須チェック、承認ルール、マージキュー
• ベンチマーク、価格、機能比較に関する主張を記憶だけに頼って受け入れないでください。まずツールの最新状況を確認してください。この分野（GitHub Copilot code review、CodeRabbit、Qodo／PR-Agent、および関連ツール）は、所有権、価格、機能が頻繁に変わります。references/automation-tools.md と data/sources.json を参照し、具体的な情報を引用する前に再確認してください。
• レビュアー向けの事実として、特定の AI モデルのバージョン／ID を指定したり引用したりしないでください。機能や挙動の変化が速く、情報がすぐに古くなるためです。
• エージェントによる PR の量が多い場合は、リスクレベルに応じて振り分けてください（認証、金銭、マイグレーション、インフラストラクチャ、公開 API は、完全な人間によるレビューのため CODEOWNERS にエスカレーションします）。エージェント PR の受付数をレビュアーの対応能力に合わせ、大規模なエージェントによる変更には積み重ねたレイヤーを必須とし、マージごとに担当人間レビュアーを明記してください。また、AI レビュアーはコメント数ではなく、対応された指摘の割合とノイズで評価してください。詳細：AI-Volume Review Policy。

AI 生成コードのレビュー用チェックリスト

AI が生成したコードやエージェントが作成した PR をレビューする際は、次の項目を確認してください。

チェック項目	確認する内容
存在しないインポート	存在しないパッケージやメソッド。npm info / pip index で確認します
古い API	非推奨のメソッド、古いシグネチャ、削除された機能
セキュリティ上の不備	入力検証の不足、ハードコードされたシークレット、SQL の文字列連結、エスケープされていない出力
エラーハンドリングの不足	正常系のみを想定している。try/catch、null チェック、タイムアウト処理がない
冗長な抽象化	不要なラッパー、時期尚早な一般化、過剰に複雑なパターン
コピー＆ペーストによる不整合	ファイル間で、よく似たコードブロックに微妙な不一致がある
見せかけのテスト	実装の詳細をアサートする、すべてをモックする、またはフレームワーク自体をテストするテスト
アクセシビリティの欠落	alt テキストがない、ARIA の不備、キーボード操作に対応していない、div の乱用
デザインシステムへの違反	既存のトークン、間隔、コンポーネントのパターンを無視したコンポーネント
自信満々だが誤ったコメント	実際の動作ではなく、コードがどう動作すべきかを説明する docstring

出典：幻覚の検出、AI によるデザインのアンチパターン

重大度の基準

指摘の立証条件。

ブロッカーまたは重大度の高い指摘を報告する前に、その分類に適した最小限の証拠を提示してください。到達可能な実行パスまたは状態遷移パス、失敗する例やテスト、あるいは具体的な契約との不一致がこれに当たります。違反している不変条件とユーザーへの影響を示し、確認できなかった前提があれば明記してください。制御可能な入力からシンクまでの追跡は、セキュリティおよび汚染データに関する指摘に限ってください。必要な到達可能性や契約を示す証拠が不明な場合は、欠陥だと断定せず、質問または条件付きのリスクとして報告してください。

優先度	ラベル	基準	レビュー対応
P0	BLOCKER	データ損失、セキュリティホール、正確性のバグ、本番パスでのクラッシュ	マージ前に必ず修正
P1	REQUIRED	エラーハンドリングの欠如、ロールバックの破損、未定義動作、SLA 違反	マージ前に必ず修正
P2	SUGGESTED	重要でないパスのテスト不足、軽微な非効率性、可読性の問題	この PR で修正するか、課題として管理
P3	OPTIONAL	スタイルの好み、命名の好み、将来的な改善	作成者が判断。ブロックしない

各指摘に優先度とラベルを付けてください。P0 と P3 の指摘を同じコメントスレッドにまとめないでください。

重大度の調整ルール（上から順に適用し、最初に該当したものを優先します）。

1. 重大度は、そのままマージした場合の影響であり、修正にかかる労力ではありません。金額を誤らせる 1 文字のオフバイワンは P0 です。動作する 200 行の読みにくいモジュールは P3 です。
2. 本番環境で到達不能なコード（デッドパス、無効な機能フラグ、テスト専用コード）は重大度を 1 段階下げ、前提を明記した質問として報告してください。到達可能性を示せないレビュー担当者が P0 を主張することはできません。
3. 認証、資金移動、マイグレーション、シークレット、パブリック API のいずれかに関わるものは、マージ後の対応がパッチではなくロールバックやデータ修復となるため、重大度を 1 段階上げてください。
4. テストの欠如には、そのテストで検出できたはずの動作の重大度を適用してください。リスクの高いパスにおけるバグ修正で回帰テストがない場合は P1、それ以外は P2、変更の少ないコードで不足が記録されている場合は P3 です。
5. 確信が持てない指摘は、事実であった場合の重大度で question: として報告してください。摩擦を避けるために不確実な指摘を P3 に引き下げてはなりません。また、勘で P0 と断定してはなりません。
6. 測定結果のないパフォーマンスに関する指摘は、差分によってホットパスに明らかに上限のない処理が導入されている場合（リクエストループ内の N+1、追加されたクエリでの全テーブルスキャン、上限のないインメモリコレクション）を除き、P2 を上限としてください。プロファイリングによる確認が必要な回帰の疑いは、software-performance に委ねてください。

省略する項目：レビュー時間をリスクの検討に充てるため、フォーマッティング（リンターが担当するものは、代わりにリンターを有効にしてください）、依存関係や契約のずれがないことを確認済みの生成ファイルやロックファイル、差分の影響範囲外にある既存の問題（別途記録してください）、PR の説明をコメントで繰り返すことは省略してください。

マージをブロックすべきでない場合

ブロックにはコストが伴います。価値の提供を遅らせ、次のやり取りを避けるために今後の変更をまとめるよう促し、重要度の低い意見の相違に使えば、レビュー担当者の信頼を損ないます。次の理由ではブロックしないでください。

• P3 の指摘のみ（スタイル、命名の好み、「より良い」抽象化）。ブロックしない提案として残し、作者の判断に任せてください。
• 欠陥や保守性へのコストが特定されていない、正しいものの自分なら別の方法で書いたであろうアプローチ。
• 本当にリスクが低く、変更頻度も低いコードのテストカバレッジ不足。ただし、作者がその不足を明確に認め、追跡されている場合に限ります。
• 差分の影響範囲外にある既存の問題。今回のレビューの範囲を広げるのではなく、フォローアップを起票してください。
• 実際にはコードではなく、プロダクトや要件に関する意見の相違。レビューコメントで議論を蒸し返すのではなく、適切な担当者にエスカレーションしてください。

P0／P1 の指摘、本当にリスクの高い新しい動作に対するテスト不足、マージ後の修正にコストがかかる、または安全に修正できないもの（データ移行、公開 API の形状、セキュリティ境界）はブロックしてください。迷った場合は、ブロックする指摘と任意の指摘を分け、一方の優先度がもう一方に引きずられないようにしてください。

形だけの承認の検出

コメントが少なく迅速なレビューが、必ずしも問題とは限りません。よく書かれた小規模でリスクの低い変更は、すばやくレビューできるはずです。次の項目は、レビューが不十分である証拠ではなく、もう一度確認する必要があることを示す警告サインとして扱ってください。

• 400 LOC を大きく超える差分への承認（Cisco／SmartBear の指針は 200 行未満、400 行超は避ける）で、その規模に対してレビュー時間が不自然なほど短い場合（このヒューリスティックの根拠となる規模とペースのデータについては、references/large-pr-review-strategies.md と references/code-review-metrics.md を参照してください）。
• 認証、資金移動、移行、公開 API に関わる変更に対して、内容のあるコメントがゼロの「LGTM」。
• 不具合のすり抜け率が上昇傾向にある一方で、レビュー完了までの時間が短縮傾向にあるチームや個人。速度の向上は、精査の省略によるものと考えられます。
• 特定の行や動作に言及せず、PR の説明を言い換えただけの承認。

これらは、公開ランキングに使うのではなく、コーチングのきっかけとして活用してください（抜き取り確認、レビューをペアで行う、実際に何を読んだかを尋ねるなど）。ゲーム化を促すことなく追跡する方法については、references/code-review-metrics.md を参照してください。

コードだけでなくテストもレビューする

テストが成功していても、テスト品質をレビューしていない差分は、レビューが半分しか済んでいません。テストコードにも、本番コードと同じ厳密さで目を通してください。

• 新規または変更された動作に対して、修正がなければ失敗するテストが実際にあることを確認してください。変更と併せてたまたま成功するだけのテストでは不十分です。
• 観測可能な動作ではなく、実装の詳細を検証するテスト（すべてをモックする、内部の呼び出し回数を確認するなど）に注意してください。こうしたテストは簡単に成功し、リファクタリング時に何も検出できません。
• 正常系だけでなく、エラー経路や境界条件もテストされていることを確認してください。
• 回帰テストのないバグ修正は、スタイル上の細かな指摘ではなく、不完全な修正として扱ってください。

よくある落とし穴

• 最初に PR の説明を読み、その後で差分を確認すること。説明は主張として捉え、証拠とは見なさないでください。
• 動作上のリスク、移行のリスク、ロールバックの安全性にはほとんど時間をかけず、スタイルに大半の労力を費やすこと。
• 生成ファイル、スナップショット、ロックファイルの変更を、契約や依存関係のずれが隠れていないか確認せずにノイズとして扱うこと。
• 不具合の原因が周辺の不変条件、呼び出し元の想定、または終了処理の経路にあるのに、変更行だけをレビューすること。
• 不足しているシナリオ、境界条件、回帰を挙げずに、一般的な指摘として needs tests とだけ述べること。
• バージョンに左右される主張について、差分のコメントにあるベンチマーク、セキュリティ、フレームワークに関する記述を、実際に検証せず受け入れること。

よくあるアンチパターン

• レビューを承認のための形式的な儀式として扱うこと。正しさやリリース時のリスクを検証せず、命名に軽くコメントするだけにとどまります。
• 実際の問題がより小さなバグ、ガードレールの不足、または弱い契約であるにもかかわらず、レビューで作者のアーキテクチャを書き換えること。
• 好みと欠陥を混同すること。好みは任意の指摘として扱い、ブロッキングコメントは正しさ、安全性、保守性のリスクに限ります。
• 複数の独立した問題を、根拠を添えた個別の指摘に分けず、大きなコメントスレッドにまとめてしまうこと。
• AI レビューの出力を権威あるものとして扱い、各指摘を実際の差分やローカルな文脈に照らして検証しないこと。

デフォルトのレビュー出力

デフォルトでは、次の内容を含めます。

• 意図とリスクの簡潔な要約
• P0 / P1 / P2 / P3 ごとに分類した指摘
• REQUIRED と OPTIONAL のラベル
• 具体的な修正案：最小限の差分、テストケース、または設定の修正
• 要件が本当に不明確な場合に限った追加質問

表現については assets/core/review-comment-guidelines.md を、最終確認の判断については assets/core/review-checklist-judgment.md を使用します。コメントの意図には Conventional Comments の規約（suggestion:、issue:、question:、nitpick:、praise:）に沿ったラベルを付け、口調に頼らず、ブロッキングか非ブロッキングかを明確にします。

ナビゲーション

コア資料：

• references/operational-playbook.md
• references/automation-tools.md
• references/review-checklist-comprehensive.md — 懸念事項ごとの完全なチェックリストと、「Looks Good To Me」および「Implementing Effective Code Reviews」に基づくレビュー手順の実践方法
• references/security-focused-review-guide.md
• references/large-pr-review-strategies.md
• references/code-review-metrics.md
• references/psychological-safety-guide.md
• references/dotnet-efcore-crypto-rules.md
• references/adversarial-review-protocol.md — 文脈を除いた引き継ぎと、固定優先順位による指摘の調整、2 人のレビュアーによるゲート、コミット前の意思決定レビューにおけるバッチサンプリング
• references/complexity-only-review-pass.md — 完全なチェックリストを補完する、過剰な設計のみを対象とした、範囲を絞ったタグ付きの迅速なレビュー
• references/deterministic-vs-llm-routing.md — レビュー前の決定論的なファイルゲート、サイズに応じた計画パスのしきい値、AI レビューツール向けの自己反証フィルターパス

テンプレート：

• assets/core/pull-request-description-template.md
• assets/core/review-comment-guidelines.md
• assets/backend-api/api-review.md
• assets/web-frontend/frontend-review.md
• assets/mobile/mobile-review.md
• assets/infrastructure/infrastructure-review.md
• assets/blockchain/crypto-review.md

ソース：

• data/sources.json - プラットフォームのステータスと廃止されたリンクの代替を含む、検証済みのソース一覧

情報の鮮度に関するプロトコル

ユーザーから次の内容を尋ねられた場合：

• 最適または最新のコードレビュー ツール
• 現在の PR 自動化の実践方法
• GitHub Copilot、CodeRabbit、Qodo、プラットフォーム標準の選択肢の比較
• あるツールが今も有用かどうか

次の対応を必ず行ってください。

1. ウェブ検索を行います。
2. ベンダーによる比較ブログよりも、公式ドキュメントやリリース／ステータスページを優先します。
3. data/sources.json を出発点となる情報源として使用します。
4. 独立して検証されていない限り、ベンダーの指標や事例紹介のパフォーマンス数値は、あくまで参考として扱います。

ウェブにアクセスできない場合は、その旨を伝え、data/sources.json に基づいて回答し、時期によって変わる助言については未検証であることを明記してください。

学習ループ

過去の判断や落とし穴が関連する場合は、learnings.consolidated.md があれば参照してください。必要な履歴を確認する場合、または参照可能な代替ファイルとして使う場合に限り、learnings.md を使用してください。それ以外の場合は、どちらも参照しないでください。

適用後に、覚えておく価値のあるパターン、再発を防ぐべき間違い、または意外だった分野の事実に気付いた場合は、agents-skills-feedback-loop/scripts/append_learning.py を使って、日付入りの箇条書きを 1 件 learnings.md に追記してください。SKILL.md 自体は変更しないでください。