Claude Code × Backlog MCP Serverで実現する GitHub↔Backlog 自動連携 | cloud.config Tech Blog

はじめに

こんにちは。

株式会社FIXER 入社2年目の新屋です。

ソフトウェア開発の現場では、GitHubでコード管理をしつつ、Backlogでプロジェクトのタスクを管理しているケースは珍しくありません。しかし、2つのツールを並行して運用していると「GitHub IssueをBacklogにも転記する」という二重管理の手間が生まれます。

この記事では、GitHub Actions + Claude Code Action + Backlog MCP Server を組み合わせて、GitHub Issue/PRのコメント一つでBacklog課題を自動作成・更新する「@cc-backlog」ワークフローを作ったので、その設計と実装について紹介します。

対象読者

GitHubとBacklogを併用しており、二重管理の手間を減らしたいと考えている方
GitHub Actionsの基本的な使い方を理解している方
Claude Code ActionやMCP Serverを活用した自動化に興味がある方

この記事で紹介しないこと

GitHub Actionsの基本的な設定方法やワークフロー構文
Backlog MCP Serverのインストール・セットアップ手順
Claude Code Actionの導入手順
MCP（Model Context Protocol）自体の仕様

※本記事の文章は、一部生成AIを用いて作成しています。

1. 解決したい課題

GitHub × Backlog の二重管理問題

普段の開発で、以下のような手間に悩まされていました。

GitHub上で調査結果をまとめたIssueや不具合修正のPRを作成した後、同じ内容をBacklogにも手動で登録する必要がある
担当者の割り当て、優先度、期限などを両方のツールで個別に設定しなければならない
親PBI（Product Backlog Item）との紐付けを手動で管理しなければならず、漏れが発生しやすい

目指した姿

GitHub Issue/PRのコメント欄に「@cc-backlog」と書くだけで、Backlog側に子課題が自動作成されることを目指しました。

# これだけでBacklog課題が自動作成される（デフォルトは2日後が期限）
@cc-backlog
# 期限を5日後に指定することも可能
@cc-backlog 5
# PRレビューコメントでも使える
この部分のバリデーション追加をお願いします。
@cc-backlog 3

このように、コメントの書き方はシンプルで、期限の日数指定やPRレビューコメントでの利用にも対応しています。

2. アーキテクチャ全体像

システム構成

今回実装したワークフローは、以下の3つの要素で構成されています。

GitHub Issue/PR コメント (@cc-backlog)
        │
        ▼
GitHub Actions (cc-backlog.yml)
        │
        ├── Step 1: Backlog MCP 設定作成（インラインJSON）
        ├── Step 2: コメントメタデータ抽出
        └── Step 3: Claude Code Action 実行
                │
                ├── Backlog MCP Server (npx backlog-mcp-server)
                │     ├── get_issues（親PBI検索）
                │     ├── get_issue（親PBI詳細取得）
                │     ├── add_issue（子課題作成）
                │     ├── update_issue（子課題更新）
                │     ├── get_priorities（優先度取得）
                │     └── get_issue_types（課題種別取得）
                │
                ├── gh CLI（GitHub Issue/PR 情報取得・コメント投稿）
                └── Read ツール（TEAM_MEMBERS.md 読み込み）

ポイントは、Claude Code ActionがBacklog MCP Serverと gh CLIの両方を使い分けて、GitHub側とBacklog側の操作をひとつのプロンプトで完結させているところです。

技術スタックの選定理由

今回この技術スタックを選んだ理由は以下の通りです。

技術要素	選定理由
Claude Code Action	自然言語のプロンプトで複雑なビジネスロジックを書けて、MCP Serverとの連携も簡単
Backlog MCP Server	Backlog APIをMCPプロトコルでラップして、Claude Codeから直接操作できるようにする
GitHub Actions	GitHubイベントをトリガーにワークフローを自動実行でき、既存のCI/CDパイプラインとも統合しやすい

3. 処理フロー詳細

GitHub Actionsのワークフローでは、まずコメントからメタデータ（作成者、Issue/PR番号、期限日数）を抽出し、GitHub Secretsに格納したAPIキーを使ってBacklog MCP Serverの設定を動的に生成します。その後、Claude Code Actionが以下のタスクを自律的に実行します。

(1) 親PBIの自動検索

検索条件:
  - キーワード: 所定のプレフィックス（例: "PBI-XXX-"）を含む
  - ステータス: 「処理中」
  - 期間: 現在日時が startDate〜dueDate の範囲内
  - 複数ヒット時: startDate が最新のものを優先

スプリント単位で管理されている親PBIを自動的に特定し、子課題を正しい階層に紐付けてくれます。

(2) GitHub情報の取得と統合

gh コマンドでIssue/PRの詳細情報（タイトル、本文、ラベル、作成者、URLなど）を取得し、Backlog課題の各フィールドにマッピングしています。

(3) 担当者の自動マッピング

チーム内で管理している TEAM_MEMBERS.md ファイルから、GitHubユーザー名とBacklog IDの対応表を読み取って、自動的に担当者を割り当てるようにしています。

<!-- TEAM_MEMBERS.md のイメージ -->
| 名前 | GitHubユーザー名 | Backlog ID |
|------|-----------------|------------|
| 山田 太郎 | yamada-taro-example | 1234567 |
| ... | ... | ... |

(4) 優先度の自動判定

GitHubのラベルからBacklogの優先度を自動的に判定するようにしています。

GitHubラベル	Backlog優先度
priority: high	高
priority: medium	中
priority: low	低
ラベル無し	中

(5) 冪等性の確保（作成 or 更新の判断）

同じGitHub Issue/PRに対して複数回 @cc-backlogが実行された場合、既存のBacklog課題を検索して、存在すれば更新、なければ新規作成するようにしています。これにより、二重登録を防ぎつつ、情報を最新の状態に保てます。

(6) Backlog課題の作成と結果フィードバック

最終的に、タイトル・本文・優先度・担当者・期限・親PBI紐付け・マイルストーンなどを自動設定してBacklog課題を作成します。処理の成功・失敗に関わらず、GitHub Issue/PRにコメントで結果を報告するようにしており、成功時はBacklog課題のURLを、失敗時はエラー内容を通知します。

4. Claude Code Actionを「ワークフローエンジン」として使う設計思想

プロンプトがビジネスロジックになる

従来のGitHub Actionsワークフローでは、条件分岐やAPIコールのロジックをすべてYAMLとシェルスクリプトで書く必要がありました。一方、@cc-backlog では、Claude Codeへのプロンプトがそのままビジネスロジックとして機能します。

例えば「親PBIが複数見つかった場合は、startDateが最新のものを優先する」というルールは、シェルスクリプトで書くと複雑なJSONパースと比較処理が必要ですが、自然言語のプロンプトなら簡潔に表現できます。実際にやってみると、ロジックの変更もプロンプトを数行修正するだけで済むので、メンテナンスがとても楽になりました。

MCP Serverによるツール抽象化

Backlog MCP Serverは、Backlog REST APIをClaude Codeが直接呼び出せる形に抽象化したツール群（`get_issues`, `add_issue` など）を提供してくれます。これにより、以下のようなメリットがあります。

認証管理の一元化: APIキーはMCP設定に一度だけ記述すればよい
エラーハンドリングの簡素化: MCP Serverがリクエスト/レスポンスの変換を担当する
ツールの発見性: Claude Codeが利用可能なツール一覧を自動的に認識し、適切なAPIを選択する

許可ツールによるセキュリティ境界

Claude Code Actionには allowed_tools というパラメーターがあり、実行可能なツールを明示的に制限できます。以下はワークフロー定義の抜粋です。

allowed_tools: |
  Read
  Bash(gh:*)
  mcp__backlog__get_issues
  mcp__backlog__get_issue
  mcp__backlog__add_issue
  mcp__backlog__update_issue
  mcp__backlog__get_priorities
  mcp__backlog__get_issue_types

これは最小権限の原則を意識した設計になっており、Claude Codeが意図しない操作（ファイル書き込み、課題削除など）をしてしまうリスクを抑えられます。

さらに、Backlog側のアクセス範囲もGitHub ActionsのSecretで制御しています。`BACKLOG_ALLOWED_PROJECT_KEYS` に許可するプロジェクトキーを設定しておくことで、設定されていないプロジェクトの課題にはアクセスできないようにしています。これにより、ツールレベルの制限に加えて、プロジェクト単位でもアクセス範囲を絞り、意図しないプロジェクトへの操作を防いでいます。

5. 実際に使ってみて

ここからは、チームで実際に @cc-backlog を運用してみた所感を紹介します。

導入状況

導入してからまだ2ヶ月ほどですが、チーム内の2、3人が週に数回のペースで使っています。特に、タスクとして元々積んでいなかった不具合修正やリファクタリングのIssue/PRに対して使うケースが多く、計画外のタスクをBacklogに素早く登録する用途で活躍しています。

感じている効果

導入前と比べて、以下の4つの効果を実感しています。

転記作業の削減: GitHub→Backlogの手動転記がなくなった
登録漏れの減少: 「あとでBacklogに登録しよう」と思って忘れるケースが減った
心理的負担の軽減: 転記作業自体は毎回1、2分程度だったが、GitHubで作業中に手を止めてBacklogを開くというコンテキストスイッチが地味にストレスだった。@cc-backlog ならGitHub上で完結するので、このストレスがなくなった
情報の一貫性向上: GitHubとBacklogの情報を自動で同期するため、内容のずれが起きにくくなった

運用で見えてきた課題

一方で、実際に運用してみて見えてきた課題もあります。

一番大きいのは、エラー時の原因特定が難しいことです。特に以下の2つのケースで苦労しました。

Backlog APIエラー: APIキーやパラメーターの問題で失敗したとき、GitHubコメントのエラー通知だけでは原因がわかりにくく、GitHub Actionsのログを見に行く必要があった
親PBIが見つからない: スプリントの切り替わりタイミングで親PBIが存在しなかったり、PBIのステータスが「処理中」に更新されていなかったりして検索にヒットしないケースが発生した

エラー時のフィードバックをより具体的にするのは、今後の改善ポイントだと考えています。