Claude Code 用「Code Reviewer サブエージェント」完全ガイド：`code-reviewer.md` の実装解説と導入・運用ノウハウ

Claude Code 用「Code Reviewer サブエージェント」完全ガイドcode-reviewer.mdの実装解説と導入・運用ノウハウ【免费下载链接】claude-howtoA visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-howtoコードを書いたあと、そのままコミットしていませんか。本記事では、Claude Code のサブエージェントとして動作するコードレビュー専門エージェント定義ファイルja/04-subagents/code-reviewer.mdを題材に、「セキュリティ → パフォーマンス → 品質 → テスト → 設計」の優先順位を持つ自動レビュー人材をどう定義するかを、フロントマターの解析からレビュー出力フォーマット、インストール・運用方法まで実践的に解説します。読み終えると、このコードレビューエージェントを自分のプロジェクトの.claude/agents/に導入し、コード変更のたびに自動で品質・セキュリティレビューを回す運用を再現できるようになります。1. 前提知識サブエージェントとは何かClaude Code のサブエージェントは、メインの会話とは独立したコンテキストウィンドウを持つ専門化された AI アシスタントです。特定の目的・専用ツール・カスタムシステムプロンプトを持たせ、複雑なタスクを委譲することで、メインコンテキストの汚染を防ぎます。この仕組みの全体像はja/04-subagents/README.mdに詳しく、サブエージェントの定義ファイルは「YAML フロントマターMarkdown のシステムプロンプト」という形式で.claude/agents/配下に配置します。code-reviewerはこのフォルダ群の中でも特に「コード変更の直後に自動的に呼び出してほしい」設計が徹底されているエージェントで、description に Use PROACTIVELY と明記することで Claude の自動委譲プロアクティブな呼び出しを促しています。2. エージェント定義ファイルの全体像ja/04-subagents/code-reviewer.mdの冒頭は次の YAML フロントマターです。--- name: code-reviewer description: Expert code review specialist. Use PROACTIVELY after writing or modifying code to ensure quality, security, and maintainability. tools: Read, Grep, Glob, Bash model: inherit ---各フィールドの意味フィールド値役割namecode-reviewerサブエージェントの一意な識別子小文字ハイフン。code-reviewer (agent)のような メンションや、claude --agent code-reviewerで指定しますdescription冒頭にUse PROACTIVELYを含む文章エージェントが「いつ呼び出されるべきか」を自然言語で記述。プロアクティブな自動委譲を促すキーワードが含まれていますtoolsRead, Grep, Glob, Bashエージェントに許可するツールの限定リスト。レビューは基本的に読み取りとコード検索で完結するため、Write/Edit 系は付与されていませんmodelinherit使用モデルを親セッションから継承この定義は、ja/04-subagents/README.mdに記載されたサブエージェント一般の設定フィールドnamedescriptiontoolsdisallowedToolsmodelpermissionModemaxTurnsskillsmcpServersmemoryなどの中から、レビュー用途に最小限必要な項目だけを選んでいる点がポイントです。「サブエージェントには目的に必要なツールのみ与える」というベストプラクティス同 README 参照を忠実に体現しています。ツール設定の補足toolsを省略するとすべてのツールを継承しますが、この定義ではRead, Grep, Glob, Bashに絞っています。また v2.1.113 のネイティブ macOS/Linux ビルドでは Glob・Grep が Bash 経由のbfsugrepとして提供されますが、フロントマターでの記載方法は同じですja/04-subagents/README.md。3. 呼び出されたときの動作フローシステムプロンプト本文は、まずエージェントの役割を定義し、その直後に「呼び出されたら」の手順を番号付きで指示しています。あなたはコード品質とセキュリティの高い水準を確保するシニアコードレビュアーである。 呼び出されたら 1. git diff を実行して直近の変更を確認する 2. 修正されたファイルに焦点を当てる 3. 直ちにレビューを開始するこの設計の要点は次の 2 点です。git diffを最初に実行するレビュー対象は「さっき書いたばかりの差分」に限定します。Bashツールが許可されているからこそ実行可能なステップです。「直ちにレビューを開始する」と明示するレビュアーに「まず状況を質問する」などの遠回しな行動を取らせず、即行動に移らせる指示です。実プロジェクトでサブエージェントの実行前チェックをさらに自動化したい場合は、hooksを使うパターンもja/04-subagents/README.mdに例示されていますPreToolUse フックでセキュリティチェックスクリプトを起動する例。code-reviewer本体はコードの静的レビューに集中し、実行前のガードはフックや後述の skill・plugin 側で補完する構成にできます。4. レビューの優先順位5 段階レビュー観点が散漫にならないよう、code-reviewerは検討順序を明示的に列挙しています。優先順位観点具体的チェック対象1セキュリティ問題認証、認可、データ露出2パフォーマンス問題O(n²) 操作、メモリリーク、非効率なクエリ3コード品質可読性、命名、ドキュメント4テストカバレッジ不足しているテスト、エッジケース5デザインパターンSOLID 原則、アーキテクチャセキュリティ問題が最優先であるのは、認証・認可の欠陥やデータ露出は修正コストが最も高く、リリース後の影響が致命的になりうるためです。この順序は、このリポジトリ内の関連資産とも一貫しています。たとえばコードレビュー用スキル03-skills/code-review-specialist/SKILL.mdは、セキュリティ分析認証・認可問題、データ露出リスク、インジェクション脆弱性、暗号の弱点、機密データのログ出力を第一に掲げ、その後パフォーマンス、品質、保守性と続けています。5. レビューチェックリストcode-reviewerはレビュー中に漏れを防ぐためのチェックリストを持っています。コードが明確で読みやすい関数と変数の名前が適切重複コードがない適切なエラー処理シークレットや API キーの露出なし入力バリデーションが実装されている良好なテストカバレッジパフォーマンスへの配慮がなされているこの「簡潔な 8 項目」を、より検査項目の多い詳細チェックリストに展開したい場合、リポジトリには完成度の高い参照実装があります。03-skills/code-review-specialist/templates/review-checklist.mdは、SecurityPerformanceQualityTesting の 4 カテゴリにわたって具体的なチェックボックスを用意しており、たとえば「ハードコードされた認証情報がないか」「N1 クエリがないか」「関数は 50 行未満か」「テストカバレッジ 80% 超」などをレビュー中に 1 件ずつ確認できます。code-reviewer.mdをベースに、より網羅的なレビューが必要な場合はこのチェックリストをシステムプロンプトに貼り込む拡張が容易です。6. レビュー出力フォーマットレビュー結果の品質は「指摘の表現がどれだけ構造化されているか」で決まります。code-reviewerは各問題に対して6 つのフィールドを必ず埋めるよう指示しています。フィールド内容重大度SeverityCritical / High / Medium / LowカテゴリCategorySecurity / Performance / Quality / Testing / Design場所Locationファイルパスと行番号問題の説明何が問題で、なぜ問題なのか推奨修正コード例影響システムへの影響さらに、フィードバックは優先度別に 3 段階で整理すると明記されています。Critical な問題必須修正警告修正すべき提案改善を検討最後に「問題の修正方法を具体的な例で示す」とあり、指摘だけして修正案を渡さないレビューアーを防いでいます。この「指摘の記録フォーマットをテンプレート化する」考え方を発展させたものが、03-skills/code-review-specialist/templates/finding-template.mdです。こちらは Issue ごとに Severity のチェックボックス、Category の選択肢、現在のコードと修正コード例の並記、影響分析テーブル、レビュアー所見、著者レスポンス欄まで含む本格的なテンプレートで、複数人でのレビュー記録を残す用途にそのまま転用できます。7. 具体的なレビュー例N1 クエリ問題code-reviewer.mdは、抽象的な指示だけではなく完成されたレビュー出力の具体例を 1 件提示しています。これにより、エージェントは「期待されるアウトプットの形」をワンショットで学習できます。### 問題N1 クエリ問題 - 重大度High - カテゴリPerformance - 場所src/user-service.ts:45 - 問題ループが各イテレーションでデータベースクエリを実行している - 修正JOIN またはバッチクエリを使用する - 影響データサイズに応じて応答時間が線形に増加するここから読み取れるのは次の点です。場所は「ファイル:行番号」形式で必ず特定するsrc/user-service.ts:45。修正は具体策レベルJOINバッチクエリの使用まで書く。影響はデータ量に対するスケーリング観点で説明する「線形に増加」ことで、重大度 High の根拠を示す。この例で示された「N1 クエリ」のような典型的な問題を体系的に見つけたい場合は、03-skills/code-review-specialist/scripts/analyze-metrics.pyのような定量計測スクリプトの併用が有効です。このスクリプトは対象ファイルから関数数・クラス数・平均行長・複雑性スコアifforwhileなどのキーワード数による概算を算出し、レビュー前の定量的なデータ収集を支援します同フォルダのcompare-complexity.pyはリファクタリング前後の循環複雑度を比較できます。code-reviewerの Bash 実行と組み合わせれば「人間の目による静的レビュースクリプトによる数値エビデンス」の両輪でレビュー品質を高められます。8. このエージェントを自分のプロジェクトに導入する8-1. インストールファイルの配置code-reviewer.mdはコピーして使う即戦力のファイルです。導入先は 2 つの選択肢がありますja/04-subagents/README.mdの「インストール手順」節に準拠。# プロジェクト専用推奨このプロジェクトの変更時のみに使う mkdir -p .claude/agents cp /data/web/disk1/git_repo/GitHub_Trending/cl/claude-howto/ja/04-subagents/code-reviewer.md .claude/agents/ # 全プロジェクト共通すべてのプロジェクトでレビューエージェントを使いたい場合 mkdir -p ~/.claude/agents cp /data/web/disk1/git_repo/GitHub_Trending/cl/claude-howto/ja/04-subagents/code-reviewer.md ~/.claude/agents/エージェント定義のロード優先順位は、CLI 定義--agentsJSON プロジェクト.claude/agents/ ユーザー~/.claude/agents/ プラグインplugin のagents/の順ですja/04-subagents/README.md。8-2. 認識確認と呼び出し方法インストール後、エージェントが読み込まれたか確認します。claude agents利用可能なエージェントの一覧組み込みユーザープロジェクトをソース別にグループ化にcode-reviewerが表示されれば成功です。呼び出し方法は主に 3 通りあります。方法例特徴プロアクティブ自動コード変更を指示するだけで自動委譲description の Use PROACTIVELY が効く明示的な委譲 Have the code-reviewer subagent look at my recent changes会話中に名前で指定メンション code-reviewer (agent) review the auth module自動委譲のヒューリスティクスをバイパスして確実に起動さらに、セッション全体をこのエージェントをメインにして回すことも可能です。# CLI フラグでメインエージェントとして起動 claude --agent code-reviewer # settings.json に常駐設定 # { agent: code-reviewer }9. リポジトリ内の関連リソースでレビュー体制を拡張するcode-reviewerを中核に据えつつ、同じリポジトリ内の資産を組み合わせることで「単発レビュー」から「レビュー体制」へ拡張できます。9-1. 観点を分離した兄弟エージェント04-subagents/secure-reviewer.mdtools: Read, Grepの最小権限でセキュリティ監査に特化認証・認可問題、データ露出、インジェクション攻撃の検出。機能変更なしの読み取り専用監査が必要なときに使います。04-subagents/clean-code-reviewer.md正しさではなく可読性・保守性に特化命名、関数の長さ、引数の数、重複・デッドコード、コメントの質。code-reviewerの品質面をさらに深掘りしたいときに併用できます。テスト側は04-subagents/test-engineer.mdカバレッジ 80% 以上を目標に単体・統合テストを設計が補完します。04-subagents/README.mdのアーキテクチャ図にあるように、メインエージェントが「コードレビューテストドキュメント」の各サブエージェントへ委譲し、結果を統合してユーザーへ返す構成を組めます。レビュー観点ごとに専門エージェントを分離するのは、ja/04-subagents/README.mdが掲げる「1 エージェント 1 責務」のベストプラクティスにも合致します。9-2. skill によるスキル化同じコードレビュー機能を「サブエージェント人の定義」ではなく「スキル再利用可能な機能」として持ちたい場合は、03-skills/code-review-specialist/SKILL.mdを参照してください。こちらはレビューの際に参照すべきチェックリスト・発見事項テンプレート・計測スクリプトをフォルダ単位で束ねた構成になっており、サブエージェントのシステムプロンプトに読み込ませて「レビュー専門人材ツールセット」として一体運用する拡張も可能です。9-3. plugin によるレビューワークフローのパッケージ化PR レビューを定型ワークフローとして回すなら、07-plugins/pr-review/commands/review-pr.mdが参考になります。セキュリティ分析・テストカバレッジ検証・ドキュメント更新・コード品質チェック・パフォーマンス影響評価を含む包括的な PR レビューを開始するコマンドとして定義されており、同プラグインにはcheck-security.md・check-tests.mdコマンドやsecurity-reviewerperformance-analyzertest-checkerといったエージェントが含まれます。code-reviewerの思想を、複数コマンド・複数エージェント・フックでパッケージ化した上位互換の例として読み解けます。10. ベストプラクティスまとめja/04-subagents/README.mdのベストプラクティス節と突き合わせると、code-reviewer.mdは次の原則をすべて満たしています。description に Use PROACTIVELY を含め、自動委譲を促す— コード変更後のレビュー漏れを防ぐ要役割を明確に定義する— 「シニアコードレビュアーとして品質とセキュリティの高水準を確保する」レビュー優先順位を明示する— セキュリティ → パフォーマンス → 品質 → テスト → デザインの順行動ステップを具体的に書く—git diff→ 変更ファイルに焦点 → 直ちにレビュー開始出力フォーマットを固定する— 6 フィールドCritical警告提案の 3 段階整理修正コード例付き実例で期待値を示す— N1 クエリ問題の完成形レビューを 1 件提示ツールを最小限に絞る— 読み取り中心のRead, Grep, Glob, Bashのみ許可「指摘は必ず具体的な修正例付きで」「場所はファイル:行番号で特定」「影響の根拠まで書く」というこのエージェントの出力規律は、そのまま人間のコードレビューのチーム標準としても流用できます。ja/04-subagents/code-reviewer.mdを雛形に自分のチームのルール必須の禁止事項やコーディング規約などを追記すれば、プロジェクト固有の「コードレビュー品質の番人」を数分で手に入れられるでしょう。補足本記事で引用した日本語版ja/04-subagents/code-reviewer.mdに対応する英語オリジナルは04-subagents/code-reviewer.mdです。内容を比較しながら読み進めると、サブエージェント定義の翻訳・ローカライズの作法も学べます。フロントマターのdescriptionはエージェントの自動委譲判断に使われるため、原文のまま維持されている点にも注目してください。【免费下载链接】claude-howtoA visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-howto创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考