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 ---

各フィールドの意味

フィールド	値	役割
`name`	`code-reviewer`	サブエージェントの一意な識別子（小文字＋ハイフン）。`@"code-reviewer (agent)"`のような @メンションや、`claude --agent code-reviewer`で指定します
`description`	冒頭に"Use PROACTIVELY"を含む文章	エージェントが「いつ呼び出されるべきか」を自然言語で記述。プロアクティブな自動委譲を促すキーワードが含まれています
`tools`	`Read, Grep, Glob, Bash`	エージェントに許可するツールの限定リスト。レビューは基本的に読み取りとコード検索で完結するため、Write/Edit 系は付与されていません
`model`	`inherit`	使用モデルを親セッションから継承

この定義は、ja/04-subagents/README.mdに記載されたサブエージェント一般の設定フィールド（name／description／tools／disallowedTools／model／permissionMode／maxTurns／skills／mcpServers／memoryなど）の中から、レビュー用途に最小限必要な項目だけを選んでいる点がポイントです。「サブエージェントには目的に必要なツールのみ与える」というベストプラクティス（同 README 参照）を忠実に体現しています。

ツール設定の補足：toolsを省略するとすべてのツールを継承しますが、この定義ではRead, Grep, Glob, Bashに絞っています。また v2.1.113+ のネイティブ macOS/Linux ビルドでは Glob・Grep が Bash 経由のbfs／ugrepとして提供されますが、フロントマターでの記載方法は同じです（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は、Security／Performance／Quality／Testing の 4 カテゴリにわたって具体的なチェックボックスを用意しており、たとえば「ハードコードされた認証情報がないか」「N+1 クエリがないか」「関数は 50 行未満か」「テストカバレッジ 80% 超」などをレビュー中に 1 件ずつ確認できます。code-reviewer.mdをベースに、より網羅的なレビューが必要な場合はこのチェックリストをシステムプロンプトに貼り込む拡張が容易です。

6. レビュー出力フォーマット

レビュー結果の品質は「指摘の表現がどれだけ構造化されているか」で決まります。code-reviewerは各問題に対して6 つのフィールドを必ず埋めるよう指示しています。

フィールド	内容
重大度（Severity）	Critical / High / Medium / Low
カテゴリ（Category）	Security / Performance / Quality / Testing / Design
場所（Location）	ファイルパスと行番号
問題の説明	何が問題で、なぜ問題なのか
推奨修正	コード例
影響	システムへの影響

さらに、フィードバックは優先度別に 3 段階で整理すると明記されています。

Critical な問題（必須修正）
警告（修正すべき）
提案（改善を検討）

最後に「問題の修正方法を具体的な例で示す」とあり、指摘だけして修正案を渡さないレビューアーを防いでいます。この「指摘の記録フォーマットをテンプレート化する」考え方を発展させたものが、03-skills/code-review-specialist/templates/finding-template.mdです。こちらは Issue ごとに Severity のチェックボックス、Category の選択肢、現在のコードと修正コード例の並記、影響分析テーブル、レビュアー所見、著者レスポンス欄まで含む本格的なテンプレートで、複数人でのレビュー記録を残す用途にそのまま転用できます。

7. 具体的なレビュー例：N+1 クエリ問題

code-reviewer.mdは、抽象的な指示だけではなく完成されたレビュー出力の具体例を 1 件提示しています。これにより、エージェントは「期待されるアウトプットの形」をワンショットで学習できます。

### 問題：N+1 クエリ問題 - 重大度：High - カテゴリ：Performance - 場所：src/user-service.ts:45 - 問題：ループが各イテレーションでデータベースクエリを実行している - 修正：JOIN またはバッチクエリを使用する - 影響：データサイズに応じて応答時間が線形に増加する

ここから読み取れるのは次の点です。

場所は「ファイル:行番号」形式で必ず特定する（src/user-service.ts:45）。
修正は具体策レベル（JOIN／バッチクエリの使用）まで書く。
影響はデータ量に対するスケーリング観点で説明する（「線形に増加」）ことで、重大度 High の根拠を示す。

この例で示された「N+1 クエリ」のような典型的な問題を体系的に見つけたい場合は、03-skills/code-review-specialist/scripts/analyze-metrics.pyのような定量計測スクリプトの併用が有効です。このスクリプトは対象ファイルから関数数・クラス数・平均行長・複雑性スコア（if／for／whileなどのキーワード数による概算）を算出し、レビュー前の定量的なデータ収集を支援します（同フォルダの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.md：tools: 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-reviewer／performance-analyzer／test-checkerといったエージェントが含まれます。code-reviewerの思想を、複数コマンド・複数エージェント・フックでパッケージ化した上位互換の例として読み解けます。

10. ベストプラクティスまとめ

ja/04-subagents/README.mdのベストプラクティス節と突き合わせると、code-reviewer.mdは次の原則をすべて満たしています。

description に "Use PROACTIVELY" を含め、自動委譲を促す— コード変更後のレビュー漏れを防ぐ要
役割を明確に定義する— 「シニアコードレビュアーとして品質とセキュリティの高水準を確保する」
レビュー優先順位を明示する— セキュリティ → パフォーマンス → 品質 → テスト → デザインの順
行動ステップを具体的に書く—git diff→ 変更ファイルに焦点 → 直ちにレビュー開始
出力フォーマットを固定する— 6 フィールド＋Critical／警告／提案の 3 段階整理＋修正コード例付き
実例で期待値を示す— N+1 クエリ問題の完成形レビューを 1 件提示
ツールを最小限に絞る— 読み取り中心のRead, Grep, Glob, Bashのみ許可

「指摘は必ず具体的な修正例付きで」「場所はファイル:行番号で特定」「影響の根拠まで書く」というこのエージェントの出力規律は、そのまま人間のコードレビューのチーム標準としても流用できます。ja/04-subagents/code-reviewer.mdを雛形に自分のチームのルール（必須の禁止事項やコーディング規約など）を追記すれば、プロジェクト固有の「コードレビュー品質の番人」を数分で手に入れられるでしょう。

補足：本記事で引用した日本語版ja/04-subagents/code-reviewer.mdに対応する英語オリジナルは04-subagents/code-reviewer.mdです。内容を比較しながら読み進めると、サブエージェント定義の翻訳・ローカライズの作法も学べます。フロントマターのdescriptionはエージェントの自動委譲判断に使われるため、原文のまま維持されている点にも注目してください。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

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