GLOBIS TechPublicationへの投稿
🍋

Claude Code Action による PR レビューをスケールさせる活用術

yukin01
に公開
AI
GitHub Actions
Claude
Claude Code
tech

これは GLOBIS Advent Calendar 2025 シリーズ2 1日目の記事です。

はじめに

Claude Code Action は、GitHub Actions で Claude Code を使った自動コードレビューを実現する Anthropics 公式のアクションです。

https://github.com/anthropics/claude-code-action

本記事では、実際に運用する中で得られた知見をもとに、Claude Code Action（以下 CCA）をより効果的に活用するためのアプローチを紹介します。

対象読者

すでに CCA を導入済みか、これから本格的な運用を検討している方を想定しています。

前提

v1 を使用する

まず重要な前提として、v1 を使用することを推奨します。

- uses: anthropics/claude-code-action@v1

beta で導入したまま止まっている場合、v1 で追加された機能や改善を享受できていない可能性があります。移行ガイドを確認しつつ、是非 v1 への移行を検討してください。

コミット SHA で固定する

GitHub Actions のセキュリティベストプラクティスとして、バージョンをコミット SHA で固定することが推奨されています。これにより、タグの付け替えによる予期しない変更を防ぎます。

- uses: anthropics/claude-code-action@6902c227aaa9536481b99d56f3014bbbad6c6da8 # v1.0.18

インラインコメントを有効化する

CCA は、デフォルトではレビュー結果を PR コメントとして出力します。しかし、実際の運用では、該当箇所に直接インラインコメントが付く方が開発者にとって分かりやすく、修正もしやすいでしょう。

インラインコメントを有効化するには、--allowedTools オプションに MCP ツールを追加します。

- uses: anthropics/claude-code-action@v1
  with:
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    claude_args: |
      --allowedTools "mcp__github_inline_comment__create_inline_comment"

これにより、Claude Code が該当する行やコードブロックに直接コメントを付けられるようになります。

GHA ワークフローから Claude Code への指示を分離する

GitHub Actions のワークフローファイルにレビュー内容のプロンプトを直接書く運用を続けていくと、以下の課題を感じることがあります。

  • ワークフローファイルが肥大化して可読性が低下する
  • プロンプトの変更のたびにワークフローを修正する必要がある
  • 複数リポジトリで同じレビュー基準を使いたい場合に管理が煩雑になる

カスタムスラッシュコマンドによるプロンプトの分離

Claude Code にはカスタムスラッシュコマンドという機能があります。
.claude/commands/ ディレクトリに Markdown ファイルを配置することで、プロンプトを外部ファイルとして管理しつつ、任意に呼び出すことができます。

.claude/commands/review-pr.md
以下の観点でコードレビューを実施してください。

- セキュリティリスク(SQLインジェクション、XSS、認証・認可の不備など)
- パフォーマンス上の問題
- コードの可読性と保守性
- エラーハンドリングの妥当性

重大な問題がある場合はインラインコメントで指摘してください。

ワークフローはスラッシュコマンドを呼び出すだけのシンプルな構成に保てます。

- uses: anthropics/claude-code-action@v1
  with:
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    claude_args: |
      --allowedTools "SlashCommand,mcp__github_inline_comment__create_inline_comment"
    prompt: |
      /review-pr ${{ github.event.pull_request.number }}

設定ファイルによる引数の管理

--allowedTools や --mcp-config などの引数をワークフローファイルに直接記述すると、こちらも煩雑になりがちです。これらは設定ファイル経由で渡すことができます。

Claude Code は、デフォルトで .claude/settings.json と .mcp.json を読み込みますが、CI 環境でのみ適用したい設定（例: 特定のツールの制限、CI 専用の MCP サーバーなど）がある場合、CI 用の設定ファイルを別途用意すると管理しやすくなります。

CI 用の設定ファイルを作成する

  • .claude/settings.ci.json: CI 環境専用の Claude Code 設定
  • .mcp.ci.json: CI 環境専用の MCP サーバー設定
.claude/settings.ci.json
{
  "permissions": {
    "allow": [
      "Bash(gh pr comment:*)",
      "Bash(gh pr diff:*)",
      "Bash(gh pr view:*)",
      "Bash(gh pr checks:*)",
      "SlashCommand",
      "WebFetch",
      "WebSearch",
      "mcp__your-mcp-server"
    ],
    "deny": []
  }
}
.mcp.ci.json
{
  "mcpServers": {
    "your-mcp-server": {
      "command": "npx",
      "args": ["-y", "@your-org/mcp-server"]
    }
  }
}

これにより、ワークフローの引数で渡す --allowedTools や --mcp-config を最小限に抑えることができます。

- uses: anthropics/claude-code-action@v1
  with:
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    settings: .claude/settings.ci.json
    claude_args: |
      --mcp-config .mcp.ci.json
      --allowedTools "mcp__github_inline_comment__create_inline_comment"
    prompt: |
      /review-pr ${{ github.event.pull_request.number }}

サブエージェントでコンテキスト節約と時短

Monorepo のような大規模なコードベースでは、Claude Code が全体を探索すると時間とトークンを大量に消費します。

Claude Code にはサブエージェントという機能（Task ツール）があり、特定の範囲に絞った探索や分析を並列実行できます。これにより、コンテキストの節約と処理時間の短縮が可能です。

変更されたファイルの種別ごとにサブエージェントを起動してレビューを実施してください。
各サブエージェントは該当ファイルとその周辺コードのみを対象とし、並列で実行してください。

このようなプロンプトを追加することで、Claude が自動的に並列処理を行い、効率的なレビューを実現できます。

詳細は公式ドキュメントを参照してください。

https://code.claude.com/docs/ja/sub-agents

エージェントスキルで専門知識を共有する

Claude Code にはエージェントスキルという機能があり、特定の領域における専門知識や手順を外部ファイルとして定義できます。
個人的にまだそこまで使いこなせていないのもありますが、CCA においては必須とまでは感じていません。
まずはカスタムスラッシュコマンドやサブエージェントを使いつつ、それでもコンテキストが増大してレビューの質の低下が見られる場合には有効なアプローチになるかなと思います。

https://code.claude.com/docs/ja/skills

詳細な説明は公式ドキュメントに任せますが、スラッシュコマンドと違ってスキルは Claude Code が自律的に判断して使用するという点が特徴的です。
とはいえ、レビューにおいては必ず使用して欲しいので、サブエージェントのフロントマターでスキルを指定すると良いでしょう。

.claude/skills/coding-style/SKILL.md
---
name: coding-style
description: チームで定められたコーディング規約
---

## コーディング規約

- aaa
- bbb
- ccc
.claude/agents/coding-style-reviewer.md
---
name: style-reviewer
description: コーディングスタイルをレビューするエージェント
skills: coding-style
---

このサブエージェントはチームのコーディング規約に基づいてレビューを実施します。
変更されたコードが規約に準拠しているか確認してください。

プラグインで共通設定を再利用する

複数のリポジトリで CCA を運用する場合、レビュー基準やツール設定が共通であることが多いでしょう。

Claude Code にはプラグイン機能があり、共通設定を外部パッケージとして定義できます。これにより、設定の一元管理と再利用が可能になります。

例えば、組織共通のレビュー基準をプラグインとして定義し、各リポジトリで利用する運用が考えられます。
その場合はプラグイン専用リポジトリを作成して plugin_marketplaces で指定し、その中でインストールするプラグインを plugins で渡すことができます。

- uses: anthropics/claude-code-action@v1
  with:
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    plugin_marketplaces: |
      https://github.com/your-org/claude-plugins.git
    plugins: |
      pr-review-toolkit@your-org-plugin

詳細は公式ドキュメントを参照してください。

https://code.claude.com/docs/ja/plugins

デバッグ方法

最後に、CCA が期待通りに動作しない場合のデバッグ方法を紹介します。

View job からサマリーを確認する

まず、GitHub Actions の実行結果から View job でジョブの詳細を確認します。Claude Code が生成したサマリーやエラーメッセージが表示されるため、大まかな問題を把握できます。

ログを理解する

より詳細に調査するにはログを直接確認します。前提として CCA は内部的に以下のコマンドを実行して JSON ログを出力しています。

claude -p "prompt" --verbose --output stream-json

ログの出力レベルを制御する

CCA v1.0.16 からは、セキュリティ等の観点から簡略化されたログのみが表示されるようになりました。詳細なデバッグ情報が必要な場合は、show_full_output オプションを有効化できます。

- uses: anthropics/claude-code-action@v1
  with:
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    show_full_output: true  # すべての JSON 出力を表示

ログの読み方

出力されるログは JSON Lines 形式で、以下のような情報が含まれます。

最初の JSON ログ

"type": "system" かつ "subtype": "init" のログには、初期化時の情報が記録されています。

  • tools: 利用可能なツールのリスト
  • slack_commands: 有効化されたスラッシュコマンド
  • mcp_servers: MCP サーバーの接続ステータス
  • skills: 有効化されたエージェントスキル

ここで、想定していたツールやスラッシュコマンドなどが有効化されているか確認できます。

最後の JSON ログ

"type": "result" のログには、実行結果が記録されています。

  • permission_denials: 権限が不足して実行できなかったツールのリスト

例えば、スラッシュコマンドが実行されなかった場合、allowedTools に SlashCommand が含まれていない可能性があります。

これらのログを確認することで、設定ミスや権限不足を特定しやすくなります。

まとめ

本記事では、CCA をより効果的に活用するための実践的なテクニックを紹介しました。

  • インラインコメントの有効化
  • プロンプトと設定の分離
  • サブエージェントによる効率化
  • エージェントスキルによる専門知識の活用
  • プラグインによる設定の再利用
  • デバッグ方法の理解

これらのテクニックを活用することで、CCA をより柔軟かつ広範囲に運用できるようになります。ぜひ、実際の運用に取り入れてみてください。

GLOBIS Tech
GLOBIS TechPublication

日本発・世界をリードするEdTechカンパニーを目指す、株式会社グロービス デジタル部門のエンジニアが運営するPublicationです。 X(Twitter)でも情報発信中！

Discussion