🚀

コードレビューにClaude Code subagentsを導入したら、レビューレベルが改善した話

koh789

2026/03/05に公開

 はじめにこんにちは！
みなさんは、コードレビューの負担に悩んでいませんか？マイクロサービスが増えるにつれて、レビュー対象のコードも増え続け、セキュリティやパフォーマンス、テストカバレッジなど、チェックすべき観点も多岐にわたるようになりました。レビュー待ち時間が開発速度のボトルネックになってしまう…そんな経験、ありませんか？
私たちも同じ課題を抱えていました。AIレビューを導入していたものの、求める水準に達していなかったのです。そこで、Claude Code subagentsを導入し、専門特化したエージェントによるレビュー体制に刷新したところ、驚くほどレビューの質が向上しました。
この記事では、コードレビューのAI化について、その取り組みを共有します。

 この記事で分かること従来のAIレビューの限界と課題
Claude Code subagentsの設計と実装
GitHub Review APIとの統合方法
導入による効果と今後の改善点

 対象読者AI活用によるコードレビュー自動化に興味のある方
Claude Codeの活用事例を知りたい方
レビュー品質と速度の両立に悩んでいる開発チーム

 背景と課題
 既存のAIレビュー体制の限界私たちはClaude Codeを使ったAIレビューを既に導入していました。レビュー観点を定義したCLAUDE_PR_REVIEW_GUIDE.md（約100行）で、以下の観点をカバーしていました：
# 従来の構成
CLAUDE_PR_REVIEW_GUIDE.md（約100行）
├── 機能性
├── 可読性と保守性
├── セキュリティ
├── パフォーマンス
├── テストとドキュメント
└── 設計と一貫性（SOLID等の原則、DDD/クリーンアーキテクチャ）
しかし、一見すると網羅的に見えるものの、各観点が簡潔に記載されているだけで、求めるレビュー水準に達していないという課題がありました。特に以下の専門領域では、表層的なチェックに留まってしまい、深い問題を見逃してしまうことが多かったのです。

 特に水準に達していなかった領域

領域
問題点


ソフトウェア設計
SOLID等の原則やDDD/クリーンアーキテクチャの具体的なチェック項目が不足。

セキュリティ
OWASP Top 10の各項目の詳細な検証基準がなく、表層的なチェックのみ。暗号化の実装や競合状態の検出が不十分

パフォーマンス
効率性の観点が曖昧で、具体的なボトルネックやリソース管理の問題を指摘できない


 なぜ今この課題に取り組むのかマイクロサービスアーキテクチャを採用している私たちのプロジェクトでは、以下の要求が年々厳しくなっていました：

コードベースの拡大: サービス数の増加に伴い、レビュー対象コードが増大

セキュリティ要件の厳格化: GCP Secret Manager、OWASP Top 10対策が必須

設計原則の遵守: DDD/クリーンアーキテクチャの原則を全サービスで統一
従来のレビュー体制では、これらの要求水準を満たせないことが明らかになりました。

 解決策の全体像 - Before/After
この図が、私たちが実現した変化の全体像です。

 Before（左側）: 単一のレビューガイドラインのみを参照Claude（単一エージェント）がCLAUDE_PR_REVIEW_GUIDE.md（約100行）を参照

特徴: 全体をカバーするが深さに限界、直列的な処理
従来は、1つのAIエージェントが1つのレビューガイドラインを読み込んで、すべての観点を順次チェックしていました。シンプルな構成ですが、各観点の専門性が低く、処理も直列的で時間がかかっていました。

 After（右側）: 専門特化したsubagents + 詳細なルールファイル各専門エージェント（Software Design Agent、Security Agent、Test Coverage Agent）が独立して動作

.claude/rules/配下の詳細なルールファイル（計1,600行以上）を参照

特徴: 専門性、並列処理による高速化、網羅性、構造化された報告
新しい構成では、4つの専門エージェント（Software Design、Security、Test Coverage、Performance）が並列で動作します。各エージェントは自分の専門分野に特化したルールファイルを参照し、深いレビューを実行します。さらに、これらのルールファイルは開発時にも参照されるため、開発とレビューで同じ基準を共有できます。

 この変化により実現できたこと
専門性の向上: 各観点（設計、セキュリティ、テスト）で深いレビューが可能に

処理速度の向上: 並列処理により、レビュー時間を大幅短縮

一貫性の確保: .claude/rules/による統一基準で、開発とレビューの両方で同じルールを適用

構造化された報告: 各エージェントの指摘事項が整理され、優先順位が明確に
では、なぜこのような構成を選んだのでしょうか？

 Claude Code subagentsを選んだ理由単一AIレビュアーではなくsubagentsを選んだ4つの根拠

 1. 専門特化による深いレビュー各観点（品質、セキュリティ、テスト）に特化したsubagentsを作ることで、深い専門知識に基づくレビューが可能になります。たとえば、security-code-reviewerはOWASP Top 10に特化しており、各脆弱性パターンを詳細にチェックできます。

 2. 並列処理による高速化複数のsubagentsを同時実行することで、レビュー時間を大幅に短縮できます。従来は順次処理で30分かかっていたレビューが、並列処理により大幅に短縮されました。

 3. 実装とレビューの一貫性.claude/rules/ディレクトリでルールを一元管理することで、実装時もレビュー時も同じ基準を参照できます。AIがコードを実装する際にこれらのルールを参照し、レビュー時にも同じルールで評価するため、「実装はルール通りなのにレビューで指摘される」といった不整合がなくなります。開発プロセス全体で一貫した品質基準を保てます。

 4. GitHub統合の柔軟性GitHub Review APIと統合することで、PRのdiff上に直接インラインコメントを作成できます。レビュー結果が視覚的に分かりやすく、開発者の負担が軽減されます。

 読者の疑問を先読み「たしかにsubagentsは魅力的だけど、単一のAIレビュアーでもいいのでは？」
そう思われるかもしれません。でも、専門特化することで、各観点の深いレビューが可能になります。たとえば、security-code-reviewerは以下のような詳細な観点をチェックします：
SQLインジェクション対策（プリペアドステートメントの使用）
シークレット管理（GCP Secret Managerの活用）
入力検証とサニタイゼーション
暗号化の実装（bcrypt、Argon2の使用）
競合状態の検出（Mutexの適切な使用）
単一のAIレビュアーでは、これらすべてを同時に深くチェックするのは困難です。

 設計・実装の詳細
 全体アーキテクチャまず、全体のアーキテクチャを図で示します：
各subagentは専門分野に特化し、詳細なルールファイルを参照してレビューを実行します。そして、結果を統合してGitHub Review API経由でPRにコメントを投稿します。

 Phase 1: サブエージェント導入最初のステップは、専門特化したsubagentsの導入でした。

 実装したsubagentssoftware-design-reviewer（コード品質レビュアー）
SOLID等の設計原則のチェック（他. DRY、KISS、YAGNI..）
DDDの原則のチェック
クリーンアーキテクチャのチェック
コードの可読性、保守性の評価
エラーハンドリングの妥当性
循環的複雑度、マジックナンバーの検出
security-code-reviewer（セキュリティレビュアー）
OWASP Top 10対策の確認
シークレット管理（GCP Secret Manager）
入力検証・サニタイゼーション
暗号化の実装、競合状態の検出
test-coverage-reviewer（テストカバレッジレビュアー）
テストカバレッジの分析
テーブル駆動テストの確認
エッジケースのテスト漏れ検出
performance-reviewer（パフォーマンスレビュアー）
アルゴリズム複雑度の分析
データベースクエリの効率性（N+1問題、インデックス）
リソース管理とメモリリークの検出
ボトルネックの特定と最適化提案

 サブエージェント定義各subagentは以下のように定義しました：
.claude/agents/software-design-reviewer.md
---
name: software-design-reviewer
description: |
  コードの品質、保守性、ベストプラクティスへの準拠をレビュー
tools: Glob, Grep, Read, WebFetch, TodoWrite, WebSearch
model: inherit
---
toolsパラメータで使用可能なツールを指定し、model: inheritで親エージェントのモデルを継承します。これにより、各subagentが独立して動作しつつ、一貫性を保つことができます。

 より詳細な定義サンプル実際のエージェント定義ファイルは、フロントマター（メタデータ）とエージェント本体（プロンプト）から構成されます：
---
name: software-design-reviewer
description: |
  コードの品質、保守性、ベストプラクティスへの準拠をレビューする必要がある場合にこのエージェントを使用します。

  例:
  - 新しい機能や関数を実装した後
  - 既存のコードをリファクタリングする場合
  - 重要な変更をコミットする前
  - コード品質に不安がある場合
tools: Glob, Grep, Read, WebFetch, TodoWrite, WebSearch
model: inherit
---

あなたはソフトウェアエンジニアリングのベストプラクティスとクリーンコードの原則に特化したコード品質レビュアーです。

## 参照すべきルールファイル

**重要**: レビュー前に以下のルールファイルを`Read`ツールで読み込み、詳細なチェック項目を把握してください：

1. **`.claude/rules/design_principles.md`** - 設計原則（SOLID、DRY/KISS/YAGNI）
2. **`.claude/rules/ddd.md`** - ドメイン駆動設計（DDD）
3. **`.claude/rules/architecture.md`** - アーキテクチャ（クリーンアーキテクチャ、レイヤー実装）
4. **`.claude/rules/golang_coding.md`** - Go規約とテスト標準

これらのルールファイルに記載されたチェックリストを使用して、コードをレビューしてください。

## 主要なレビュー領域

### 機能性
- **意図した機能の実現**: コードが要件や仕様に基づいて正しく機能しているか
- **要件との整合性**: 実装が設計ドキュメントや仕様書と一致しているか

### エラーハンドリング
- **欠落したエラーハンドリング**: エラーが適切に処理されているか
- **入力検証の堅牢性**: すべての入力が適切に検証されているか

### 可読性
- **コード構造**: コードがその目的を明確に伝えているか
- **マジックナンバー**: ハードコードされた値が定数として定義されているか

## 出力形式

各指摘事項は以下の形式で記載してください：

\`\`\`markdown
\### [ファイル名]

**[severity].** [行番号]: [指摘内容の要約]

[詳細説明]

\`\`\`

- **ファイル名**: リポジトリルートからの相対パス（例: `services/user-service/domain/user.go`）
- **severity**: 重要度
  - `must` - Critical Issues（即座の対応が必要）
  - `imo` - Important Issues（対応すべき）
  - `nits` - Minor Issues（あれば望ましい）
- **行番号**: 指摘対象の行番号（数値のみ）
- **詳細説明**: 影響、推奨事項、コード例など

**出力例**:

\`\`\`markdown
\### services/user-service/domain/user.go

**must.** 343: エラーハンドリングが不足しています

この関数はエラーを返す可能性がありますが、呼び出し元でチェックされていません。
エラーを適切に処理するか、意図的に無視する場合は `_ =` で明示してください。

**imo.** 156: 変数名が不明確です

変数 `d` は何を表しているか不明確です。`duration` や `date` など、より明確な名前を使用してください。
\`\`\`
この定義により、エージェントは：

参照すべきルールファイルを明示的に指定され、深い専門知識に基づくレビューが可能

統一された出力形式で指摘事項を返すため、メインエージェントが処理しやすい
**重要度（must/imo/nits）**を明示することで、開発者が優先順位を判断しやすい

 ルールファイルへの一元化従来のCLAUDE_PR_REVIEW_GUIDE.md（約100行）を削除し、内容を.claude/rules/配下に分割・詳細化しました：
ルールファイルの構成:
.claude/rules/
├── golang_coding.md         # Go基本規約、テスト標準（約200行）
├── architecture.md          # アーキテクチャガイドライン（約400行）
├── ddd.md                   # DDD（約250行）
├── design_principles.md     # 設計原則（SOLID,KISS,DRY...）（約250行）
└── security.md              # セキュリティ実装ガイドライン（約500行）
各ルールファイルには、具体的なチェック項目と実装例（Good/Bad）が記載されています。たとえば、security.mdには以下のような詳細な観点が含まれています：
セキュリティルールの例:
\# SQLインジェクション対策

\## ❌ Bad: 文字列連結
\```go
query := "SELECT * FROM users WHERE name = '" + userName + "'"
db.Query(query)
\```

\## ✅ Good: プリペアドステートメント
\```go
query := "SELECT * FROM users WHERE name = ?"
db.Query(query, userName)
\```

\## チェックリスト
- [ ] ユーザー入力を直接SQL文字列に連結していないか
- [ ] プリペアドステートメントを使用しているか
- [ ] ORMを使用している場合、エスケープ処理が適切か
このように、各観点を詳細に記載することで、AIレビューの精度が大幅に向上しました。

 並列処理の実装subagentsは並列で実行されます。/review-branchコマンドでは、以下のように並列実行を明示しています：
以下のサブエージェントで包括的にレビューしてください：

1. **software-design-reviewer** - コード品質、機能性、DDD & クリーンアーキテクチャ
2. **security-code-reviewer** - セキュリティ、OWASP Top 10、認証・認可
3. **test-coverage-reviewer** - テストカバレッジ、テーブル駆動テスト
4. **performance-reviewer** - パフォーマンス、効率性、リソース管理

**並列処理**: 可能な限りサブエージェントを並列で実行し、レビュー速度を向上させてください。
これにより、4つのsubagentsが同時に動作し、レビュー時間が短縮されます。

 Phase 2: インラインコメント機能の強化次のステップは、レビュー結果をGitHub上で視覚的に分かりやすくすることでした。

 課題：並列実行によるコメントの乱立Phase 1でサブエージェントを並列実行できるようになりましたが、新たな課題が発生しました。
問題点:
4つのsubagentsが並列で動作するため、何もしないとGitHubに個別のレビューコメントが大量に投稿されてしまう
各subagentが独立してコメントを投稿すると、通知も煩わしくなる
レビュー全体の一貫性が見えにくい
解決策:

そこで、以下の2つの要件を満たす必要がありました：

レビューの統合: 複数のsubagentsの指摘事項を1つのレビューとして統合する

インラインコメント: 一つのコメントにまとめて投稿すると、どのコードに対する指摘なのか分かりにくい。そのため、コードの差分に対して直接インラインコメントをする

 1. レビューの統合：サブエージェントの戻り値を型として表現並列実行を実現するにあたって、まず「レビューの統合」を実現するためにサブエージェントの戻り値（指摘事項）を型として表現することに取り組みました。
従来、サブエージェントのレビュー結果は自由形式のテキストとして返されていました。これではメインエージェントが指摘事項を適切に処理できません。そこで、指摘事項を構造化されたデータとして表現することにしました。
解決策:

各サブエージェントが返す指摘事項のフォーマットを統一し、以下の情報を含めるようにしました：

ファイルパス: 指摘対象のファイル

行番号: 指摘対象の行

重要度: must, imo, nits, q

指摘内容: 具体的な問題と修正提案
これにより、メインエージェントが複数のサブエージェントからの指摘事項を統合し、GitHub APIに投稿する処理が可能になりました。

 2. インラインコメント：GitHub MCPを使ったレビューコメントの統合投稿次に「インラインコメント」を実現するために、GitHub Review APIを活用した統合投稿に取り組みました。
当初はmcp__github_inline_comment__create_inline_commentという個別のコメント作成APIを使用していました。しかし、以下の課題がありました：
コメントが個別に投稿されるため、レビュー全体の一貫性が見えにくい
バッチ処理ができず、API呼び出し回数が多い
レビュー単位での管理ができない
そこで、GitHub Review APIに移行することで、これらの課題を解決しました。
API比較:


項目
旧API（inline_comment）
新API（Review API）


フロー
コメント単独作成
ペンディング → 追加 → 送信

一貫性
個別投稿
レビュー単位で管理

バッチ処理
不可
可能

GitHub統合
限定的
完全統合

Review APIの最大の利点は、ペンディングレビューという仕組みです。まず空のレビューを作成し、そこに複数のインラインコメントを追加していき、最後にまとめて送信できます。
実装したフロー:
これにより、4つのサブエージェントからの指摘事項を1つのレビューとしてまとめて投稿できるようになりました。
コメント形式の工夫別リポジトリで検証した際に成功したコメント形式を採用しました。接頭辞で重要度を明示することで、開発者が優先順位を判断しやすくしています：

**[重大]** / **must.** - 修正必須（セキュリティ、バグ、重大な問題）

**[改善推奨]** / **imo.** - 改善提案（パフォーマンス、可読性向上）

**[軽微]** / **nits.** - 軽微な指摘（コードスタイル、タイポ）

**[質問]** / **q.** - 質問（仕様確認、設計意図）
例：
**must.** エラーハンドリングが不足しています

この関数はエラーを返す可能性がありますが、呼び出し元でチェックされていません。
エラーを適切に処理するか、意図的に無視する場合は `_ =` で明示してください。

 GitHub Actionsとの統合GitHub Actionsワークフローを作成し、PRが作成されたタイミングで自動的にレビューを実行するようにしました：
name: AI Claude review
on:
  pull_request:
    types: [opened, reopened, ready_for_review]
  workflow_dispatch:
    inputs:
      pr_number:
        description: 'PR number to review'
        required: true
        type: number

jobs:
  auto-review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: anthropics/claude-code-action@beta
        with:
          prompt: |
            /review-branch --pr ${{ github.event.pull_request.number || inputs.pr_number }} を実行してください。

 レビューフローレビューの実行フローは以下の通りです：
各subagentが並列で実行され、結果を統合してからGitHub APIにコメントを投稿します。

 導入結果・効果
 定性的な効果（体感として）Claude Code subagentsの導入により、以下の効果を実感しています：

 1. レビュー品質の向上専門特化したsubagentsにより、以前は見逃していた問題を発見できるようになりました。
具体例:

セキュリティ: 競合状態の検出、暗号化アルゴリズムの不適切な使用

設計: SOLID原則違反、DDD境界づけられたコンテキストの不整合

テスト: エッジケースのテスト漏れ、テーブル駆動テストの不備
従来は「認証を適切に実装してください」といった抽象的な指摘でしたが、今は「bcryptを使用してパスワードをハッシュ化してください。MD5は脆弱なため使用を避けてください」といった具体的な指摘ができるようになりました。

 2. レビュー速度の向上並列処理により、複数観点のレビューを同時実行できるようになりました。体感として、レビュー待ち時間が大幅に短縮されました。

 3. 開発者の負担軽減自動インラインコメントにより、レビュー結果がPRのdiff上に直接表示されるため、どの行に問題があるのかが一目瞭然です。開発者はコメントを見ながら修正を進められるため、修正作業が効率化されました。

 4. 一貫性の向上.claude/rules/による統一基準で、常に同じレベルのレビューが実行されます。レビュアーによるばらつきがなくなり、チーム全体でコード品質の底上げができました。

 まとめClaude Code subagentsの導入により、コードレビューの質と速度が大幅に向上しました。

 成果
専門特化したsubagentsによる深いレビュー

並列処理による高速化

GitHub Review APIによるシームレスな統合
**.claude/rules/**による一貫性のあるレビュー基準
従来の単一レビュー定義（約100行）から、専門特化したsubagents + 詳細なルールファイル（計1,600行以上）に進化したことで、ソフトウェア設計、セキュリティ、パフォーマンスといった専門領域で、求める水準のレビューが実現できました。

 今後の展望レビュールールの継続的改善
新しいサブエージェントの追加（documentation-accuracy-reviewer）
レビュー結果の自動修正機能
いかがだったでしょうか？Claude Code subagentsを活用することで、コードレビューの自動化と品質向上を両立できます。もしコードレビューの負担や一貫性でお悩みの方がいれば、参考になれば幸いです。

 参考リンクClaude Code公式ドキュメント
GitHub Review API
OWASP Top 10
Clean Architecture
Domain-Driven Design
この記事は実際のプロジェクト経験に基づいていますが、サービス固有の情報は抽象化しています。

領域	問題点
ソフトウェア設計	SOLID等の原則やDDD/クリーンアーキテクチャの具体的なチェック項目が不足。
セキュリティ	OWASP Top 10の各項目の詳細な検証基準がなく、表層的なチェックのみ。暗号化の実装や競合状態の検出が不十分
パフォーマンス	効率性の観点が曖昧で、具体的なボトルネックやリソース管理の問題を指摘できない

項目	旧API（inline_comment）	新API（Review API）
フロー	コメント単独作成	ペンディング → 追加 → 送信
一貫性	個別投稿	レビュー単位で管理
バッチ処理	不可	可能
GitHub統合	限定的	完全統合

MG-DX Tech BlogPublication

はじめに

この記事で分かること

対象読者

背景と課題

既存のAIレビュー体制の限界

特に水準に達していなかった領域

なぜ今この課題に取り組むのか

解決策の全体像 - Before/After

Before（左側）: 単一のレビューガイドラインのみを参照

After（右側）: 専門特化したsubagents + 詳細なルールファイル

この変化により実現できたこと

Claude Code subagentsを選んだ理由

1. 専門特化による深いレビュー

2. 並列処理による高速化

3. 実装とレビューの一貫性

4. GitHub統合の柔軟性

読者の疑問を先読み

設計・実装の詳細

全体アーキテクチャ

Phase 1: サブエージェント導入

実装したsubagents

サブエージェント定義

より詳細な定義サンプル

ルールファイルへの一元化

並列処理の実装

Phase 2: インラインコメント機能の強化

課題：並列実行によるコメントの乱立

1. レビューの統合：サブエージェントの戻り値を型として表現

2. インラインコメント：GitHub MCPを使ったレビューコメントの統合投稿

コメント形式の工夫

GitHub Actionsとの統合

レビューフロー

導入結果・効果

定性的な効果（体感として）

1. レビュー品質の向上

2. レビュー速度の向上

3. 開発者の負担軽減

4. 一貫性の向上

まとめ

成果

今後の展望

参考リンク

Discussion