ひさしぶりに Backlog を使っています。ここに Claude Code や Codex、Hermes Agent といった AI エージェントを噛ませて、課題の作成・更新・コメント追加・一覧取得を自動化できないかを試したところ、実運用レベルで動くことがわかりました。
やり方自体はシンプルで、Backlog が公式に提供している REST API を叩くための API キーをエージェント側に渡すだけです。ただし、実際に発行してみると「これは公式に直してほしい」と感じるポイントもいくつか出てきました。この記事では、実現できたことと、公式に改善してほしい 2 点をまとめて共有します。
AI エージェントから Backlog を操作したい動機
Backlog をコードや Chat と切り離した「別世界」のままにしておくと、以下のような手作業が必要になります。
- 実装が終わった課題のステータスを、エディタ・ターミナルから離れて Backlog の Web UI で更新する
- Slack やチャットで受けた依頼を、あとで Backlog に転記する
- 週次で「今週動いた課題」の一覧を、ブラウザで検索して手で貼り付ける
AI エージェント側から Backlog を直接操作できるようにすると、これらは全部エージェントに任せられます。エージェントに「この修正 PR に対応する Backlog 課題を Done にして、コメントに commit URL を貼っておいて」と頼むだけで、あとは API 越しに動いてくれる、というのが目指したい姿です。
Backlog API キーの発行手順
Backlog の API キーは、公式ドキュメントの API の設定 に沿って、個人設定から発行できます。おおまかな流れは次のとおりです。
- Backlog スペースにログインし、右上のアイコンから「個人設定」に入る
- 左メニューの「API」を選ぶ
- 用途を書いたメモを入れて「登録」ボタンを押す
- 発行された API キーをコピーする
API キーはスペース単位・ユーザー単位で紐づき、そのユーザーが Backlog 上で持っている権限をすべて引き継ぎます。つまり、管理者ユーザーで発行すれば管理者相当、一般メンバーで発行すれば一般メンバー相当の操作が可能になります。
AI エージェントに API キーを渡す
エージェントに渡すときは、平文でプロンプトに埋め込むのではなく、環境変数から読ませる形にしておくのが無難です。以下のような環境変数を用意しておきます。
export BACKLOG_SPACE="your-space" # https://your-space.backlog.com の your-space 部分
export BACKLOG_API_KEY="xxxxxxxxxxxx"Backlog の REST API は、Backlog API ドキュメント にまとまっています。基本的な形は以下のようにクエリパラメータで API キーを渡すだけです。
curl -s "https://${BACKLOG_SPACE}.backlog.com/api/v2/projects?apiKey=${BACKLOG_API_KEY}"Claude Code や Codex に対しては、この呼び出し方をシェル経由で使わせれば、そのまま Backlog を操作できます。MCP サーバー経由で構造化された操作をさせたいケースでは、Backlog 向けの MCP サーバーを差し込む選択肢もあります。
実現できたこと
Claude Code・Codex・Hermes Agent のいずれからでも、以下のような操作がプロンプト一発で実行できるようになりました。
- 課題の一覧取得（プロジェクト・担当者・ステータスなどで絞り込み）
- 課題の新規作成、担当者アサイン、期日設定
- 課題のステータス変更（未対応・処理中・処理済み・完了）
- 課題へのコメント追加、Git 連携情報の付与
- Wiki ページの一覧取得、内容の読み取り
「PR がマージされたら、対応する Backlog 課題を完了にする」「Slack で受けた要件を、要約したうえで Backlog に起票する」「今週コメントがあった課題を要約する」といった運用は、これで大部分が自動化できます。
公式に改善してほしいこと
一方で、AI エージェントに渡す前提で運用しようとすると、Backlog の API キー実装は「もう一段整えてほしい」と感じるポイントが 2 つあります。
1. API キーが平文のままブラウザに表示され続ける
現在の Backlog の API キー画面は、一度発行した API キーが個人設定の画面上に平文のまま表示され続けます。ページを再訪すれば、いつでも平文で確認できる状態です。
これは、ペアプロや画面共有中に個人設定を開いてしまう、スクリーンショットを共有する、といった場面でうっかり漏らしてしまうリスクにそのままつながります。運用でカバーはできますが、「うっかり漏らせない」を仕様として担保できていないのが厳しいところです。
改善してほしいイメージとしては、以下のいずれかが望ましいと思っています。
- 発行時のみ平文で表示し、以降はマスクする（GitHub の Personal Access Token と同じスタイル）
- 一覧画面ではキーの末尾 4 文字だけを表示し、平文表示は「表示」ボタンを押した瞬間だけに限定する
- 表示時に監査ログを残す
2. API キーの権限を細かく設定できない
もう一つは、権限のスコープを絞れない点です。現状の API キーは、発行したユーザーが持つ Backlog 上の権限をそのままフル継承します。
- 特定のプロジェクトだけを対象にする
- 読み取り専用にする
- 課題の作成・コメントだけを許可し、削除は禁止する
- Wiki は読み取りのみ、課題は書き込み可能、といった組み合わせ
このいずれもキー側では制御できません。エージェントに渡すキーには、GitHub の Fine-grained personal access token や、Slack App のスコープ、AWS の IAM ポリシーのような「最小権限」を敷きたいのが本音です。
現状の運用でこれを埋めるには、以下のような回避策を取っています。
- エージェント専用の Backlog ユーザーを作り、そのユーザーを対象プロジェクトにだけメンバー追加する
- そのユーザーのプロジェクト権限を「一般ユーザー」や「レポーター」に絞る
- 危険度の高い操作（プロジェクト削除・ユーザー招待など）ができないロールでキーを発行する
Backlog 側でロールベースの制限が効くとはいえ、キーそのもののスコープを絞れないと、AI エージェント経由の運用ではどうしても「何かあったら影響範囲が広い」というリスクが残ります。
まとめ
Backlog は、AI エージェントから REST API を叩く運用が実用レベルで動きます。Claude Code・Codex・Hermes Agent のどれと組み合わせても、課題管理と実装の間の手作業をかなり削れます。
一方で、API キーの表示仕様と権限スコープの粒度は、少なくとも AI エージェント時代の運用としてはもう一段の改善余地があります。当面はエージェント専用ユーザー・最小プロジェクトアサインで運用しつつ、公式の API キー実装が Fine-grained 化する日を待ちたいところです。
以上、Backlog を Claude Code・Codex・Hermes Agent から操作するために API キーを発行してつなぎ込んだ、現場からお送りしました。