はじめに
REALITY で Server エンジニアをしているあさだです。今回は Claude Code GitHub Actions に触れる機会があり、実際に試した内容を記事としてまとめさせていただきます。
対象とするのは、以下のような課題です。
- Jira に CS 起点の不具合情報が来る
- Server / iOS / Android / Unity / Web など複数リポジトリを横断する必要がある
- 原因特定までに時間がかかり、属人化しやすい
これらを AI エージェントによって構造的に解決する方法 をご紹介させていただきます。
この記事で得られること
- マルチリポジトリ不具合調査を Claude Code GitHub Actions で自動化する設計パターン
- GitHub ActionとArtifactsを利用した、AIエージェントのオーケストレーション設計パターン
- 実行結果をもとに AI が自らフローを改善する Self-Improving パイプラインの実装例
対象読者
- AI を活用した開発ワークフロー（AI-Driven Development）に興味があるエンジニア
- GitHub Actions での自律型エージェント構築を検討している方
- 不具合調査（Triage）の工数削減を目指している方
使用技術
| 技術 | 用途 |
|---|---|
| Claude Code Action | GitHub Actions 上での AI による調査・コード修正・コマンド実行 |
| Claude Opus 4.5 | 複雑な推論と仮説生成を行う LLM モデル |
| GitHub Actions | ワークフローの実行環境 |
| Google Vertex AI | エンタープライズ向け Claude API 利用 |
Claude Code GitHub Actions とは
Claude Code GitHub Actions は、GitHub Actions 上で AI エージェントを使って作業を自動化することができます。
ワークフローに組み込むことで、Issue の作成や更新、Pull Request の作成などをトリガーに、AI エージェントがコードベースを確認したり、コメントや修正案を提示したりすることが可能になります。
全体像：やりたいこと
REALITY は、複数のプラットフォーム（iOS, Android, Unity, Web, Server）が複雑に連携しており、不具合が発生した際に「どこに原因があるか（サーバーAPIなのか、クライアントのロジックなのか）」を特定する調査に多くの時間を費やしています。
この調査プロセスを効率化するため、Jira のチケット情報（CSに送られてきたユーザーからの不具合情報とログによる一次調査）を入力として、Claude Code GitHub Actions による横断調査の完全自動化を目指しました。
想定フロー:
検証環境の構築
Claude Code GitHub Actions を動かすための基盤についてご紹介します。
社内でのエンタープライズ向けのセキュリティ・コンプライアンス要件を満たす必要があるため、GitHub Actions から Vertex AI 経由で Claude API にアクセスするための設定を行います。
必要なアカウント・サービス
| サービス | 必須/任意 | 用途 |
|---|---|---|
| GitHub Organization | 必須 | リポジトリホスティング、GitHub Actions |
| Google Cloud Platform | 必須 | Vertex AI 経由で Claude API にアクセス |
前提として以下の状態が必要です。
- GitHub Actions が有効なリポジトリがあること
- Google Cloud プロジェクトがあり、Vertex AI API が有効化されていること
- 使用するサービスアカウントに Vertex AI 経由での Claude API アクセス権限があること
1. Google Cloud 設定（Vertex AI 連携）
Vertex AI 経由で Claude API を使用するため、Google Cloud (GCP) 側で Workload Identity 連携の設定を行います。（詳細な手順は割愛しますが、以下のリソース作成が必要です）
- Workload Identity Pool の作成
- GitHub OIDC Provider の作成
- サービスアカウントの作成
-
Vertex AI ユーザー権限の付与 (
roles/aiplatform.user) - Workload Identity バインディング: GitHub リポジトリからのアクセスを許可
2. GitHub App 設定
AI エージェントが複数のリポジトリを横断してコードを調査するため、適切な権限を持った GitHub App を作成します。
-
GitHub App の作成と App ID の取得:
GitHub Variables にCLAUDE_APP_IDとして保存します。 -
秘密鍵の生成:
GitHub Secrets にCLAUDE_APP_PRIVATE_KEYとして保存します。
3. GitHub リポジトリ設定
ワークフローを実行するリポジトリに、以下の Secrets と Variables を設定します。
Secrets
| Secret 名 | 値 | 用途 |
|---|---|---|
CLAUDE_APP_PRIVATE_KEY |
PEM形式の秘密鍵 | GitHub App 認証 |
SLACK_BOT_TOKEN |
Slack Bot Token | 通知・情報収集用（任意） |
JIRA_API_TOKEN |
Jira API Token | チケット情報取得用（任意） |
Variables
| Variable 名 | 値 | 用途 |
|---|---|---|
GCP_CLAUDE_WORKLOAD_IDENTITY_PROVIDER |
Provider パス | GCP 認証 |
GCP_CLAUDE_SERVICE_ACCOUNT |
サービスアカウント | GCP 認証 |
CLAUDE_APP_ID |
GitHub App ID | App Token 生成 |
Claude Code GitHub Actions の検証
まずはシンプルに「不具合調査」を行わせるワークフローを作成して検証しました。
以下は検証に使用したワークフローの全容です。
検証用の ワークフロー
.github/workflows/investigate.yml として以下を配置します。
検証用のワークフロー
name: Investigation
on:
issues:
types: [labeled]
jobs:
investigate:
# investigation ラベルが付いた場合のみ実行
if: github.event.label.name == 'investigation'
runs-on: ubuntu-latest
permissions:
contents: read
issues: write
id-token: write # Workload Identity に必須
steps:
# 1. リポジトリをチェックアウト
- name: Checkout repository
uses: actions/checkout@v4
# 2. Google Cloud 認証（Workload Identity）
- name: Authenticate to Google Cloud
uses: google-github-actions/auth@v2
with:
workload_identity_provider: ${{ vars.GCP_CLAUDE_WORKLOAD_IDENTITY_PROVIDER }}
service_account: ${{ vars.GCP_CLAUDE_SERVICE_ACCOUNT }}
# 3. GitHub App Token 生成（クロスリポジトリアクセス用）
- name: Generate GitHub App Token
id: app-token
uses: actions/create-github-app-token@v1
with:
app-id: ${{ vars.CLAUDE_APP_ID }}
private-key: ${{ secrets.CLAUDE_APP_PRIVATE_KEY }}
owner: ${{ github.repository_owner }}
# 4. Claude Code Action 実行
- name: Run Claude Code
uses: anthropics/claude-code-action@v1
with:
use_vertex: "true"
model: "claude-opus-4-5@20251101"
max_turns: 30
github_token: ${{ steps.app-token.outputs.token }}
# 許可するツール定義
# 基本的なファイル操作に加え、GitHub MCPツールやBashスクリプトを許可
allowed_tools: |
Read
Write
Edit
Glob
Grep
Task
Bash(scripts/*)
mcp__github__search_code
mcp__github__get_file_contents
mcp__github__list_commits
mcp__github__get_issue
mcp__github__get_issue_comments
mcp__github__add_issue_comment
mcp__github__create_pull_request
mcp__github__get_pull_request
mcp__github__get_pull_request_diff
...
# プロンプト
# Issue番号を渡して調査を開始させる
prompt: |
Issue #${{ github.event.issue.number }} を調査してください。
根本原因を特定し、修正案を提示してください。
env:
# Vertex AI 設定
ANTHROPIC_VERTEX_PROJECT_ID: ${{ vars.GCP_PROJECT_ID }}
CLOUD_ML_REGION: global
# 外部API設定（任意）
SLACK_BOT_TOKEN: ${{ secrets.SLACK_BOT_TOKEN }}
JIRA_BASE_URL: ${{ secrets.JIRA_BASE_URL }}
JIRA_EMAIL: ${{ secrets.JIRA_EMAIL }}
JIRA_API_TOKEN: ${{ secrets.JIRA_API_TOKEN }}
主要パラメータの解説
このワークフローにおける設定項目について解説します。
1. permissions の設定
permissions:
id-token: write # Workload Identity 認証に必須
Google Cloud (Vertex AI) との認証に Workload Identity を使用するため、id-token: write が必須となります。これがないと GCP 認証時に失敗します。
2. 実行パラメータ設定
Run Claude Code ステップの with で指定しているパラメータは以下の意図で設定しています。
use_vertex: "true" Google Cloud Vertex AI 経由で Claude API を利用するためのフラグです。Workload Identity を使用したセキュアな認証を行うために必須となります。
model: "claude-opus-4-5@20251101" 使用するモデルを指定しています。複雑な不具合調査には高い推論能力が求められるため、最上位モデルである Opus を選択しています。
max_turns: 30 エージェントが実行できるアクション（ツール実行や思考）の最大回数です。無限ループによるコスト超過を防ぐため、適切な上限を設定しています。
github_token: ${{ steps.app-token.outputs.token }} 通常の secrets.GITHUB_TOKEN ではなく、直前のステップで GitHub App から生成したトークンを使用しています。これは、今回の調査対象が「リポジトリ横断（iOS, Android, Server など）」であり、現在のリポジトリ以外への読み取り権限が必要になるためです。
3. allowed_tools の設定
Claude Code が使用できるツールを明示的にホワイトリスト形式で指定します。
-
Read,Write,Edit: 基本的なファイル操作 -
Task: サブエージェント（後述）を起動するために必要 -
Bash(scripts/*): 任意のコマンド実行は危険なため、例としてscripts/ディレクトリ配下のスクリプトのみ実行可能に制限 -
mcp__github__*: GitHub MCP サーバーが提供する機能（コード検索や Issue 操作など）
動作検証
ここまでの設定により、以下のように検証を行いました。
- テスト用の Issue を作成
-
investigationラベルを付与 - Actions タブでワークフローの実行を確認
直面した課題
単純な構成で実行したところ、エラーなく終了はするものの、調査の質において実用には耐えないいくつかの課題に直面しました。
-
推測による回答
チケット内に記載された文言（エラーメッセージなど）をキーワードにしてリポジトリを検索し、少しでもヒットしたコードを「原因」として報告してしまうケースが多発しました。
また、コードのロジックや仕様を深く追わず、表面的なキーワードマッチングに近い推測が行われていました。 -
視野の狭い調査
本来であれば「クライアント（Unity）での操作 → サーバーAPI呼び出し → DB更新」という一連のシーケンスを確認すべきところ、単一のリポジトリ（例：サーバー側だけ）の一部分のコードに着目してしまい、システム全体の整合性を見落とすことがありました。 -
ターン数による調査打ち切り
複数のリポジトリをまたいで調査しようとすると、設定されたターン数max_turns:30を超過してしまうことがある。 -
コンテキスト不足による調査打ち切り
複数のリポジトリをまたいで調査しようとすると、読み込むファイル数が膨大になり、トークン制限やコンテキストウィンドウの限界により、調査が中途半端な状態で終了したりハルシネーションをおこしてしまう。
これらの課題から、「単一のプロンプトで全てを解決させるのは難しい」 という結論に至り、より高度なワークフローの構築の必要がありました。
スキルとサブエージェントを用いたアーキテクチャでの解決の試み
前述の課題を解決するため、まず以下の 2 つのアプローチを試みました。
-
スキル（Skills）
調査手順や判断基準を構造化した、再利用可能なプロンプトテンプレート -
サブエージェント
特定の観点や役割に専門特化した子エージェントによる並列・分担調査
スキル（Skills）とは
スキルとは、Claude Code において特定の作業やタスクを自動的に実行させるための、再利用可能なプロンプト定義です。
.claude/skills/ 配下にディレクトリとして配置し、その中の SKILL.md にタスク内容や制約条件を記述することで、Claude Code は必要に応じて該当スキルを読み込みます。
これにより、単一のプロンプトでは表現しづらい 専門的・手順依存なタスク を、一定の品質で安定して実行できるようになります。
スキルを活用することで、たとえば以下のように、
調査プロセス全体を段階的なチェックリストとして定義したワークフローを構築できます。
スキルによるワークフローの定義サンプル
## Research synthesis workflow
Copy this checklist and track your progress:
```
Research Progress:
- [ ] Step 1: Read all source documents
- [ ] Step 2: Identify key themes
- [ ] Step 3: Cross-reference claims
- [ ] Step 4: Create structured summary
- [ ] Step 5: Verify citations
```
**Step 1: Read all source documents**
Review each document in the `sources/` directory. Note the main arguments and supporting evidence.
**Step 2: Identify key themes**
Look for patterns across sources. What themes appear repeatedly? Where do sources agree or disagree?
**Step 3: Cross-reference claims**
For each major claim, verify it appears in the source material. Note which source supports each point.
**Step 4: Create structured summary**
Organize findings by theme. Include:
- Main claim
- Supporting evidence from sources
- Conflicting viewpoints (if any)
**Step 5: Verify citations**
Check that every claim references the correct source document. If citations are incomplete, return to Step 3.
(引用: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices)
サブエージェントアーキテクチャ
サブエージェントとは
サブエージェントとは、Claude Code の Task ツールを用いて起動される子エージェントです。
各サブエージェントは メインエージェントとは独立したコンテキスト を持ち、特定のタスクに集中して処理を行います。
この仕組みにより、メインエージェントのコンテキストを肥大化させることなく、調査や解析といった比較的重い処理を委譲することが可能になります。
サブエージェントを使うメリット
| メリット | 説明 |
|---|---|
| コンテキスト分離 | 各サブエージェントが独自のコンテキストを持つため、メインエージェントのトークン制限を回避できる |
| 並列実行 | 複数のリポジトリや調査対象を同時に処理でき、全体の調査時間を短縮できる |
| 専門特化 | サブエージェントごとに、アーキテクチャ理解・ディレクトリ構造・Go / Swift / C# などの言語知識といった専門性を持たせられる |
general-purpose サブエージェントの使用
本ワークフローでは、探索や修正といった汎用的なタスクを実行できる、
Claude Code 組み込みの general-purpose サブエージェント を採用しました。
実行時に与えるプロンプトは、あらかじめ定義したサブエージェント定義をもとに動的に生成しています。
プロジェクト固有のサブエージェントを個別に定義することは目的としておらず、
スキルに依存した振る舞いを持つサブエージェントとして扱いたかったためです。
general-purpose をベースにすることで、
- サブエージェント定義をプロジェクト構成から切り離せる
- スキル単位での再利用が可能になる
といった、疎結合で再利用性の高い設計を実現しています。
サブエージェントを使用する際の注意点
サブエージェントを Task ツールで実行する場合、
メインエージェントが TaskOutput を逐次確認すると、長大な調査ログを何度も読み返すことになり、
コンテキスト消費やターン数の無駄遣いにつながります。
そこで、本ワークフローでは以下のルールを明示的に組み込みました。
- [ ] TaskOutput による実行待機やログ確認を行わない
- [ ] サブエージェントが出力したファイルの内容を、メインエージェントが直接読み込まない
- [ ] 出力予定ファイルの「存在確認」のみをもって、サブエージェントの実行完了を検知する
この設計により、
メインエージェントは「結果の詳細」ではなく 「成果物が生成されたかどうか」 のみを判断材料とし、
不要なコンテキスト消費やターン浪費を最小限に抑えることができます。
スキルの呼び出し
スキルのトリガーが適切に記述されていれば、Claude Code GitHub ActionsのJob履歴を確認することで、適切にスキルが実行されているかを確認することができます。
プロンプト例
prompt: |
Issue #${{ needs.check-trigger.outputs.issue_number }} を調査してください。
Jobのログ
ツール: Skill
入力パラメータ:
{
"skill": "investigating-bugs",
"args": "Issue #123"
}
出力:
Launching skill: investigating-bugs
TypeScriptユーティリティによる外部API連携
Claude Code は非常に柔軟にタスクをこなすため、放っておくと
- Slack API をその場で叩くスクリプトを書く
- Jira API の呼び出しロジックを毎回生成する
といった形で、調査とは無関係な「実装作業」にターン数を消費してしまいます。
そこで、外部API連携は以下の方針に統一しました。
- [ ] **インラインスクリプトは禁止**
- [ ] **事前に用意されたTypeScript で実装したクライアントをユーティリティとして利用**
- [ ] ワークフロー上では「ユーティリティを呼ぶだけ」にする
スキルとサブエージェントを用いたアーキテクチャにおける課題
スキルとサブエージェントを組み合わせたアーキテクチャを構築し、以下のような処理を段階的に自動化しました。
- Jira チケットに記載された不具合内容の抽出・要約
- 各リポジトリのアーキテクチャ理解および調査
- 不具合原因の調査および対応者の選定
- 最終レポートの生成
これらの処理をスキルとして整理し、メインエージェントが各フェーズをサブエージェントに委譲する構成としたことで、ワークフロー全体としては比較的規模の大きいものになりましたが、出力結果の品質は高く、実用に耐える手応えを得ることができました。
一方で、前述の通り、サブエージェント利用時のコンテキスト消費を抑えるためにプロンプト上で工夫を施したものの、
サブエージェントへの委譲や、その実行結果の確認を繰り返す過程でメインエージェントのコンテキストが徐々に蓄積していくという課題が残りました。
その結果、ワークフローの各フェーズにおいて複数回 Compact によるコンテキスト圧縮が発生している様子が確認されました。
Compact はコンテキストサイズを抑えるために有効な仕組みである一方、実行時間や消費ターン数に直接影響するため、ワークフロー全体の効率という観点では改善の余地があると感じました。
GitHub Actions による AIエージェントのオーケストレーションによる解決
前述の課題に対し、
GitHub Actions 自体をオーケストレーターとし、
各Jobを「独立した reusable workflow（再利用可能なワークフロー)」として分割実行する構成を採用しました。
- 各Job = 独立したエージェント実行単位
- Job間で コンテキストを共有しない
- 成果物は Artifacts のみで受け渡す
これにより、
どのJobも「過去の実行履歴を一切知らない」状態で開始できます。
ワークフローの分割
単一のワークフロー内で一つのエージェントが全フェーズの実行を管理する構成では、
調査が進むにつれてコンテキストが継続的に蓄積し、
最終的にコンテキスト肥大化がボトルネックとなっていました。
分割実行アプローチによる解決では、
ワークフローをJob単位に分割し、
各Jobを 「独立したエージェント実行単位」 として扱います。
各Jobの成果物は、必要最小限の情報のみを
JSON Artifacts として後続Jobへ受け渡すことで、
エージェント間でのコンテキスト共有を意図的に遮断します。
これにより、メインエージェントのコンテキスト圧縮の発生を抑えることができます。
従来構成：単一Job・単一メインエージェント
分散構成：Job分割 + Artifacts
Artifacts 受け渡し例
name: minimal-agent-artifact
on:
workflow_dispatch:
jobs:
agent-a:
runs-on: ubuntu-latest
steps:
- name: Run Agent A
uses: anthropics/claude-code-action@v1
with:
prompt: |
調査結果を JSON で出力してください
Output: result.json
- name: Upload artifact
uses: actions/upload-artifact@v4
with:
name: result
path: result.json
agent-b:
needs: agent-a
runs-on: ubuntu-latest
steps:
- name: Download artifact
uses: actions/download-artifact@v4
with:
name: result
- name: Run Agent B
uses: anthropics/claude-code-action@v1
with:
prompt: |
Input: result.json
内容を要約して JSON で出力してください
Output: summary.json
可観測性の向上
Job分割 + Reusable Workflow + Artifacts による構成で、ワークフロー全体の可観測性の向上も期待できます。
可観測性の向上ポイント:
-
Job単位にスキルを分離
「Issue解析」「Slack取得」「Jira取得」など処理ごとにスキルを定義し、.claude/skills/<phase-name>/SKILL.mdに管理が可能。
Job実行時は対象スキルのみを読み込む。 -
Job単位の進捗可視化・ログ分離
ワークフローがJob単位で分離し、処理進捗やログを GitHub Actions UI 上で直感的に把握可能。 -
Job単位でのコスト追跡
トークン数・ターン数・実行時間をJob単位で記録・比較可能。 -
失敗箇所の即時特定と再実行
Artifactsの再利用により、問題のあるJobだけ再実行可能。
不具合調査レポートの出力例
調査レポートの出力例
# 調査レポート
## 問題概要
アイテム購入時にコインは消費されるが、アイテムが付与されないケースがある
## 影響
- 影響ユーザー: 高負荷時に購入を行ったユーザー
- 発生頻度: イベント開始直後などのスパイク時
- 優先度: Critical
---
## 原因候補（Hypotheses）
### Hypothesis 1: 購入処理のトランザクション境界不備（信頼度: 85%）
**原因分析**:
決済（コイン消費）とアイテム付与（インベントリ更新）が同一トランザクション内で実行されていない。
高負荷時にDB接続エラー等でアイテム付与のみが失敗した場合、ロールバックされずにコインだけが減る状態になる。
**対象ファイル**:
- `backend/internal/shop/usecase/purchase.go:85-110`
- `backend/internal/domain/inventory/repository.go:45-60`
**根拠**:
1. コード解析の結果、`PurchaseUsecase` 内で2つの異なるリポジトリメソッドを呼び出しているが、共通の `Tx` オブジェクトが渡されていない
2. 過去の類似事象（#402）ではリトライ処理でカバーしていたが、今回はタイムアウトによりリトライも失敗している
修正案:
// backend/internal/shop/usecase/purchase.go
- func (u *PurchaseUsecase) BuyItem(ctx context.Context, userID string, itemID string) error {
- if err := u.coinRepo.Consume(ctx, userID, price); err != nil {
- return err
- }
- if err := u.itemRepo.Grant(ctx, userID, itemID); err != nil {
- return err // ここで返るとコイン消費が確定してしまう
- }
- return nil
- }
+ func (u *PurchaseUsecase) BuyItem(ctx context.Context, userID string, itemID string) error {
+ // ユニットオブワークパターンにより同一トランザクションで実行
+ return u.txManager.Do(ctx, func(tx context.Context) error {
+ if err := u.coinRepo.Consume(tx, userID, price); err != nil {
+ return err
+ }
+ if err := u.itemRepo.Grant(tx, userID, itemID); err != nil {
+ return err // ロールバックされる
+ }
+ return nil
+ })
+ }
シーケンス図:
## 推奨担当者
| 順位 | 担当者 | スコア | 理由 |
|-----|-------|-------|------|
| 1 | @shop-team-lead | 0.85 | 決済周りのアーキテクト兼オーナー |
| 2 | @backend-dev-a | 0.75 | 直近でトランザクション管理のリファクタリングを実施 |
| 3 | @sre-member | 0.40 | DBパフォーマンスチューニング担当 |
(備考)プロンプトによる不具合調査精度の工夫
各種スキルはAIエージェントにあらかじめ自動で生成させておりますが、
期待する出力を行わせるために以下のような指示をしています。
シーケンス図を生成させる
AI エージェントが出力した調査結果の説明では、
- 本当にリポジトリを横断して確認したのか
- クライアント → サーバー → DB の流れを理解しているのか
が判別できなかったため、シーケンス図を出力させることで、
- 調査対象が網羅されているか
- 処理順序の理解が正しいか
- 「どこで失敗すると、どんな不整合が起きるのか」
を 一目で検証可能 できるようにしました。
3つの仮説を必須とさせる
すべての調査結果には、必ず3つの原因仮説（Hypotheses）を提示させるようにしています。
認知バイアスの軽減
├── 確証バイアス: 最初に見つけた原因に固執することを防止
├── アンカリング: 一つの仮説に引きずられることを防止
└── 視野狭窄: 別の可能性を見落とすことを防止
改良後の結果との課題
いくつか既存のJiraチケットを用いてワークフローを検証した結果、
人間が調査を開始する前段階としては十分に実用的な情報量を自動生成できることが確認できました。
一方で、弊社のリポジトリ規模では
1チケットあたりの実行時間は30分〜60分規模となり、
分割したJob数に比例して、実行コストは無視できない水準になります。
これは、
- マルチリポジトリ横断調査
- Job分割による逐次実行
- 高推論モデルの使用
といった設計上の選択によるトレードオフであり、実行時間およびコストの観点から、今後は、Jobやサブエージェントごとに使用する LLM を切り替える、無駄なターン消費の検知など、調査品質を維持しつつコストを抑える設計が課題となります。
自己改善（Self-Improving）パイプライン
こちらのワークフロー自体の不具合や、ユーティリティスクリプトのバグ、スキル設計の不備に対応するため、
AIが自らワークフローを修正・改善する自己改善パイプラインをあらかじめ用意しています。
このパイプラインは、各 GitHub Actions の Job 実行後に起動され、
Job の実行ログを入力として AI エージェントに与える構成になっています。
エージェントはログを解析し、
- 実行エラーや想定外の挙動の検出
- プロンプト設計上の問題点の特定
- スクリプトや設定ファイルの修正案の生成
を自律的に行います。
自己改善パイプラインの必要性
Claude Code を用いたワークフローは、
サブエージェントやスキルの追加によって容易に複雑化します。
その結果、
- スキルやエージェントの肥大化
- 実行ログの長大化
- どこに問題があるのか分かりづらい状態
に陥りやすくなります。
これを人手で毎回デバッグするのはかなり難しいと感じたため、このような仕組みを取り入れてみました。
自己改善の流れ
自己改善の流れ
1. 問題の検出
ワークフローのJobの失敗時や定期監査で、[self-improve] プレフィックス付きIssueが自動作成されます。
## 問題
Investigation ワークフロー実行中に、`mcp__github__list_branches` ツールの使用権限がないエラーが発生しています。
ワークフローは成功として完了していますが、調査中に以下のエラーが発生：
Claude requested permissions to use mcp__github__list_branches, but you haven't granted it yet.
## 優先度
レベル: Warning
理由: Jobは成功するが、不必要なエラーログとツール呼び出しの失敗が発生している
2. 人間による承認
approved ラベルの付与は人間が行います。これにより、意図しない変更が自動適用されることを防ぎます。
3. TDDアプローチによる修正
prompt: |
Issue #${{ github.event.issue.number }} の内容を実装してPRを作成してください。
TDD原則に従い、テストを先に作成してください。
- テスト作成（失敗確認）
- 最小限の実装
- テスト成功確認
- PR作成
4. AIレビューと自動マージ
作成されたPRはAIによるレビューを受け、問題がなければ自動的にリリース用のPRを作成します。
5. PRレビューフロー
PRレビューフロー
6. 自己改善による効果
AI エージェントは、多少の指示の不足や設定不備などを、独自で解決して処理を進めてしまいますが、
実行ログを解析させることで、
- 実行を許可していないツールの使用による失敗
- 不要または曖昧なプロンプト指示
- ワークフロー設定やスキル設計の過不足
といった問題点が明確になり、
次回以降の実行に向けた修正が自動的に反映されていることを確認できました。
その結果、再実行時には
- ツール試行による失敗が減少する
- 想定外のエラーを解決するケースが減る
- プロンプトがより安定した形に収束する
といった改善が見られています。
これにより、Claude Code GitHub Actionsで課題となる無駄なターン数の消費を抑えることにつながりました。
まとめ
本記事では、Claude Code GitHub Actions を用いて、
Jira の不具合チケットを起点に、原因特定・修正案提示・担当者特定までを自動化する AI ワークフローの設計と、その検証結果を紹介しました。
単一のプロンプトによる調査では、推測ベースの結論に寄りがちであったり、コンテキスト不足によって調査が打ち切られるといった課題に直面しました。
また、スキルやサブエージェントを導入しただけでは、メインエージェントのコンテキスト肥大化を完全に防ぐことは困難でした。
最終的に、GitHub Actions のJob分割と Artifacts を活用した「オーケストレーション型」のアーキテクチャを採用し、各Jobのコンテキストを分離することで、
コンテキスト圧縮を回避しつつ、リポジトリを横断した質の高い調査を自動化できる手応えが得られました。
さらに、実行ログを入力として AI 自身がワークフローやプロンプトを修正する 自己改善（Self-Improving）パイプライン を組み込むことで、複雑化しがちなワークフロー構成に対しても、継続的に改善を回せる運用モデルを構築できることを確認しました。
一方で課題として、実行時間や費用といったコスト面は軽視できず、タスクごとに適切な LLM を選択して使用する、無駄なターン消費を検知し、プロンプトを改善するなど、コスト効率を意識したワークフロー設計が今後の重要な検討事項になります。
今後の展望としては、今回紹介した不具合調査に限らず、
同様のアプローチをワークフローのオーケストレーション層として設計することで、
- コード生成や修正に対する AI レビュー
- レビュー結果を評価する監査 Job
- 判定結果に応じた特定 Job の条件付き再実行
といった 開発プロセス全体を対象とした AI オーケストレーションへの応用などを考えています。
本記事で紹介した設計パターンや考え方が、
AI を活用した開発ワークフローの構築に取り組む方の参考になれば幸いです。
※ 本記事で紹介した構成図やフローは概念的なものであり、
実際の実装詳細とは一部異なる場合があります。
REALITY株式会社の有志メンバーにより運用されているPublicationです。 このPublicationの記事はREALITY株式会社所属社員による個人の見解であり、所属する組織の公式見解ではありません。
Discussion