この記事は GENDA Advent Calendar 2025 - シリーズ 2 - 4日目の記事です。
はじめに - デフォルト設定の課題
anthropics/claude-code-action は GitHub Actions で手軽に AI コードレビューを導入できます。
レビュー自動化によるレビュアーの負荷軽減と、 Claude Code から /install-github-app コマンド一つで導入できる手軽さが魅力で、多くのプロジェクトで導入されています。
しかし、デフォルト設定のまま運用しているといくつかの課題に直面することがあります。
課題
ひとかたまりの長文レビュー
デフォルトの設定では、Pull Request (PR) 全体に対して1つの長いコメントでフィードバックが返ってきます。
網羅的ではあるものの、具体的な指摘箇所とコードの対応付けが難しく、「読むだけで疲れる」「重要な指摘を見落とす」といった問題が発生しがちです。
レビューを繰り返すと PR ページが縦に伸びて読みにくい
PR の指摘に対応した commit を push すると、レビューワークフローが再度動いて、その都度長文レビューが追加されます。
Claude によるコメントが複数追加されると、以下の問題が発生します。
- PR ページが縦に長くなり検索性が低下する
- 追加した commit が何を修正したものなのか確認しにくくなる
claude-code-action のオプションに use_sticky_comment: true を設定すると、Claude の長文コメントが最新の1つしか残らないようにできます。
しかし、最新のコメントしか残らないという問題があり、さらにv1リリース以降動かなくなってしまいました。 (最新版では修正されているかもしれません)
本家の利用方法
そんな課題を感じていた時、ふと「開発元はどうしているんだろう？」と思い、anthropics/claude-code-action リポジトリを覗いてみました。
そこで発見したのが、彼ら自身が運用しているレビューワークフローです。
これこそが開発者が考える「ベストプラクティス」であるはず。
実際に中身を見てみると、claude-review.yml 自体は小さく、プロンプトは /review-pr コマンドの1行だけでした。
動作の流れ
このワークフローは、以下のように1つのスラッシュコマンドが5つのサブエージェントを並列でレビューを実行する構成になっています。
この本家の運用方法を取り入れて自分たちのプロジェクト向けに若干カスタマイズすることで、レビュー品質は向上し、人間のレビュー工数が大幅に削減できました。
その改善の核心となる3つのポイントを紹介します。
改善のポイント
1. /review-pr によるマルチエージェントレビュー
単に「レビューして」と頼むのではなく、/review-pr というコマンド形式で指示を出します。
ワークフローに直接プロンプトを大量に記述するのではなく /review-pr のスラッシュコマンドにレビュー方法の詳細について記載します。
これにより、Claude は体系立てて PR を読み込み、GitHub MCP ツールを使って情報を収集し、レビューを行うという一連のフローを実行します。
スラッシュコマンド内ではレビュー観点ごとにサブエージェントを分けることで、それぞれ独立したコンテキストウィンドウで動作するため、本来の PR レビューという目的から逸脱するのを防ぎます。
2. インラインコメント (mcp__github_inline_comment__create_inline_comment)
最大の改善点は、インラインコメントの導入です。
claude-code-action では GitHub MCP とは別に mcp__github_inline_comment__create_inline_comment という MCP ツールが導入されています。
インラインコメントについては公式のドキュメントにもベストプラクティスとして載っています。
claude_args: |
--allowedTools "mcp__github_inline_comment__create_inline_comment"
これにより、Claude は PR 全体への長文コメントではなく、該当するコード行に直接コメントしてくれるようになります。
GitHub の「Files changed」タブで、コードと指摘をセットで確認できるため、人間のレビュアーからの指摘と同じ感覚で扱えます。
指摘箇所が明確になるだけで、レビューの消化効率は段違いに上がります。
対応が明らかな場合は suggestion を使って修正も促してくれます。
3. トリガー設定の最適化 (synchronize 削除)
「修正のたびにレビューが走る」問題には、ワークフローファイルの on.pull_request.types から synchronize トリガーを外すことで対応しました。
自動レビューはPR作成時のみで、修正途中の細かいコミットには反応させず、開発者の集中を削がないように配慮されています。
複数の修正が重なり、改めてレビューして欲しくなったら @claude /review-pr とコメントすることで、issue_comment で動作するワークフローの方から再度コードレビューをしてもらえます。
on:
pull_request:
types: [opened]
実際に導入したもの (抜粋)
スラッシュコマンド
review-pr.md
---
allowed-tools: Bash(gh issue view:*),Bash(gh search:*),Bash(gh issue list:*),Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*),Bash(gh pr list:*),Bash(gh api:*),Bash(jq:*),WebFetch,WebSearch
description: 5つの観点 (品質、パフォーマンス、テスト、ドキュメント、セキュリティ) からPRを包括的にレビューする
argument-hint: [owner/repo] [pr-number]
---
REPO: $1
PR NUMBER: $2
## ステップ 1: プロジェクトルールの読み込み
最初に、プロジェクトルートの CLAUDE.md ファイルを Read ツールで読み込み、プロジェクト固有のルール、開発環境、設計方針を確認する。この情報は、後続のすべてのサブエージェントに共有される。
## ステップ 2: サブエージェントによる包括的レビュー
以下の主要領域についてサブエージェントを使用して包括的なコードレビューを実行する:
- code-quality-reviewer (コード品質レビュアー)
- performance-reviewer (パフォーマンスレビュアー)
- test-coverage-reviewer (テストカバレッジレビュアー)
- documentation-accuracy-reviewer (ドキュメント正確性レビュアー)
- security-code-reviewer (セキュリティコードレビュアー)
**重要**: 各サブエージェントには、ステップ1で読み込んだ CLAUDE.md の内容を前提知識として提供する。各エージェント内で CLAUDE.md を再読み込みする必要はない。
## ステップ 3: フィードバックの統合と投稿
- 各エージェントには注目すべきフィードバックのみを提供するよう指示する
- 具体的な問題については積極的にインラインコメントでフィードバックを提供する
- 全般的な所見や称賛にはトップレベルコメントを使用する
- Pull Request をマージしてよいか、修正が必要かどうかを明示的に示す
エージェント
code-quality-reviewer.md
---
name: code-quality-reviewer
description: コード品質、保守性、ベストプラクティスへの準拠をレビューする必要がある場合にこのエージェントを使用します。例: 新機能や関数を実装した後、既存コードをリファクタリングした場合、重要な変更をコミットする前、コード品質について不確実な場合。
tools: Glob, Grep, Read, WebFetch, TodoWrite, WebSearch, BashOutput, KillBash
model: inherit
---
ソフトウェアエンジニアリングのベストプラクティス、クリーンコード原則、保守可能なアーキテクチャに関する深い専門知識を持つ、コード品質レビューのエキスパートです。
## レビュー項目
**クリーンコード分析:**
- 明確で説明的な命名規則
- 単一責任原則への準拠 (関数・メソッドのサイズ)
- コードの重複と DRY 改善
- 過度に複雑なロジックの簡略化
- 適切な関心の分離
**エラーハンドリングとエッジケース:**
- 潜在的な失敗ポイントに対するエラーハンドリング
- 入力検証の堅牢性
- エッジケースのカバレッジ (空の配列、境界条件)
- try-catch ブロック、Result 等のエラー伝播の適切な使用
**可読性と保守性:**
- コード構造と組織化
- コメントの適切な使用
- 制御フローの明確さ
- マジックナンバーや文字列の定数化
## iOS/Swift 固有のレビューポイント
- swift-format による自動フォーマットの適用
- async/await と @MainActor の適切な使用
- プロトコル指向プログラミングと値型/参照型の選択
- OpenID Connect 仕様への準拠
performance-reviewer.md
---
name: performance-reviewer
description: コードのパフォーマンス問題、ボトルネック、リソース効率を分析する必要がある場合にこのエージェントを使用します。例: データベースクエリや API 呼び出しを実装した後、既存機能を最適化するとき、データ処理ロジックを書いた後、アプリケーションの遅い動作を調査するとき、またはループ、ネットワークリクエスト、メモリ集約的な操作を含むコードを完成させたとき。
tools: Glob, Grep, Read, WebFetch, TodoWrite, WebSearch, BashOutput, KillBash
model: inherit
---
ソフトウェアシステムの全レイヤーにわたるパフォーマンスボトルネックの特定と解決に関する深い専門知識を持つ、エリートパフォーマンス最適化スペシャリストです。
## 分析項目
**パフォーマンスボトルネック分析:**
- アルゴリズムの複雑さ (O(n²) 以上の操作)
- 不要な計算、冗長な操作、繰り返し作業
- ブロッキング操作と非同期実行の機会
- 非効率な反復処理やネストしたループ
**ネットワーククエリ効率:**
- N+1 問題と欠落したインデックス
- バッチ処理の機会と不要なラウンドトリップ
- キャッシング、メモ化、リクエストの重複排除
- コネクションプールとリソース再利用パターン
**メモリとリソース管理:**
- 閉じられていない接続、イベントリスナー、循環参照
- ループ内での過度なメモリ割り当て
- ファイルハンドル、データベース接続のクリーンアップ
## iOS/Swift 固有の考慮事項
- ARC による適切なメモリ管理 (strong/weak/unowned)
- async/await の適切な使用とコンテキストスイッチのオーバーヘッド
- Task の優先度設定と並行処理の最適化
- バッテリー消費への影響と省電力モードでの動作
security-code-reviewer.md
---
name: security-code-reviewer
description: セキュリティ脆弱性、入力検証の問題、または認証/認可の欠陥に関してコードをレビューする必要がある場合にこのエージェントを使用します。例: 認証ロジックを実装した後、ユーザー入力処理を追加するとき、外部データを処理する API エンドポイントを書いた後、またはサードパーティライブラリを統合するとき。
tools: Glob, Grep, Read, WebFetch, TodoWrite, WebSearch, BashOutput, KillBash
model: inherit
---
アプリケーションセキュリティ、脅威モデリング、セキュアコーディングプラクティスに関する深い専門知識を持つ、エリートセキュリティコードレビュアーです。
## レビュー項目
**セキュリティ脆弱性評価:**
- OWASP Top 10 の脆弱性スキャン
- インジェクション攻撃 (SQL, NoSQL, コマンド)
- XSS と CSRF 保護のギャップ
- 弱い暗号化や不適切な鍵管理
- 競合状態と TOCTOU 脆弱性
**入力検証とサニタイゼーション:**
- 全てのユーザー入力の適切な検証
- 出力時の適切なエンコーディング
- ファイルアップロードのタイプチェック、サイズ制限
- パストラバーサル脆弱性
**認証と認可:**
- 安全な認証メカニズム
- 適切なセッション管理
- パスワードの適切なハッシュ化 (bcrypt, Argon2, PBKDF2)
- 保護されたリソースへのアクセスチェック
- 安全でない直接オブジェクト参照 (IDOR)
## iOS/OIDC 固有のセキュリティ要件
- PKCE フローの正しい実装 (code_verifier, code_challenge)
- ID Token の署名検証とクレーム検証
- Keychain の適切なアクセス制御
- HTTPS 通信の強制と証明書検証
- ASWebAuthenticationSession の安全な使用
- 機密情報のログ出力防止
test-coverage-reviewer.md
---
name: test-coverage-reviewer
description: テストの実装とカバレッジをレビューする必要がある場合にこのエージェントを使用します。例: 新機能の実装を書いた後、コードをリファクタリングするとき、モジュールを完成させた後。
tools: Glob, Grep, Read, WebFetch, TodoWrite, WebSearch, BashOutput, KillBash
model: inherit
---
テスト駆動開発、コードカバレッジ分析、品質保証のベストプラクティスに関する深い専門知識を持つ、エキスパート QA エンジニアおよびテストスペシャリストです。
## レビュー項目
**テストカバレッジの分析:**
- テストコードと本番コードの比率
- 未テストのコードパス、ブランチ、エッジケース
- 全てのパブリック API と重要な関数のテスト
- エラーハンドリングと例外シナリオのカバレッジ
- カバレッジ目標 (全体 55%、ブランチ 30%) の達成状況
**テスト品質の評価:**
- テストの構造と組織化 (arrange-act-assert パターン)
- テストの分離、独立性、決定論性
- モック、スタブ、テストダブルの適切な使用
- 明確で説明的なテスト名
- 具体的で意味のあるアサーション
**欠落しているテストシナリオ:**
- 未テストのエッジケースと境界条件
- 欠落している統合テストシナリオ
- カバーされていないエラーパスと失敗モード
## iOS/Swift Testing 固有の要件
- Swift Testing フレームワークの適切な使用 (@Test, #expect, #require)
- URLProtocol によるネットワーク通信のモック
- async/await テストの適切な実装
- OIDC 固有のテストシナリオ (認証フロー、ID Token 検証、トークンリフレッシュ)
documentation-accuracy-reviewer.md
---
name: documentation-accuracy-reviewer
description: コードドキュメントが正確で、完全で、最新であることを検証する必要がある場合にこのエージェントを使用します。具体的には、以下の場合に使用してください: ドキュメント更新が必要な新機能を実装した後、既存のAPIや関数を変更した後、ドキュメントレビューが必要なコードの論理的なまとまりを完了した後、またはコードレビューやリリースの準備をするとき。
tools: Glob, Grep, Read, WebFetch, TodoWrite, WebSearch, BashOutput, KillBash
model: inherit
---
コードドキュメント標準、APIドキュメントのベストプラクティス、テクニカルライティングに関する深い専門知識を持つ、テクニカルドキュメントレビューのエキスパートです。
## レビュー項目
**コードドキュメント分析:**
- 全てのパブリック関数、メソッド、クラスの適切なドキュメントコメント
- パラメータの説明と実際のパラメータの型・目的の一致
- 戻り値のドキュメントと実際の返却値の一致
- ドキュメント内の例が現在の実装で動作すること
- エッジケースやエラー条件の適切なドキュメント化
- 削除または変更された機能を参照する古いコメント
**README 検証:**
- README の内容と実際に実装された機能の一致
- インストール手順の最新性と完全性
- 使用例が現在の API を反映していること
- 設定オプションが実際のコードと一致すること
**API ドキュメントレビュー:**
- エンドポイントの説明と実際の実装の一致
- リクエスト/レスポンスの例の正確性
- パラメータの型、制約、デフォルト値の検証
- エラーレスポンスのドキュメントと実際のエラーハンドリングの一致
## iOS SDK 固有のドキュメント要件
- DocC 形式のドキュメントコメント (///, - Parameter, - Returns, - Throws)
- 日本語でのドキュメント記述
- OIDC/OAuth 関連の説明 (スコープ、環境設定、トークンの種類)
- データフォーマットの違いの明記 (生年月日: API vs ID Token)
導入後の効果
この構成に変更してから、コードレビュー体験は大きく変わりました。
- 複数の視点でのレビュー: 人間が見落としがちなエッジケースや、可読性の観点を AI が補完してくれます。
- 指摘の見落とし減少: インラインコメントになったことで、指摘箇所が明確になり、見逃しが激減しました。
- 修正コスト削減: 具体的な修正案 (Suggestion) が提示されることもあり、ボタン一つでコミットできる場合もあります。
- レビュー時間の短縮: 人間のレビュアーは、AI が指摘済みの単純なミスをスルーして、設計やロジック、仕様の整合性といった、より高度なレビューに集中できるようになりました。
まとめ
公式で運用されているワークフローを真似ることで、コードレビューの質とスピードが改善しました。
レビュー観点ごとの並列レビューという手法は Claude のサブエージェントの使い所としてばっちりはまっていると思います。
今後は、プロジェクト固有のルール (命名規則やアーキテクチャの制約など) をプロンプトやカスタム MCP で組み込み、さらにプロジェクトに特化したレビュアーへと育てていきたいと考えています。
まだ claude-code-action のデフォルト設定のままで消耗している方は、ぜひ本家の構成を試してみてください。
Discussion