circleci-logs と Cursor を組み合わせて、CI 失敗の調査から修正までを AI に任せる

Last updated at 2026-09-28Posted at 2026-03-19

CIが失敗したとき、多くの開発者はCircleCIダッシュボードを開き、パイプライン → ワークフロー → ジョブと画面をたどって失敗したステップのログを確認しています。エラー箇所を特定したら、その内容をエディタにコピーし、修正方法を検討します。この一連の作業は手動で行うと数分から十数分を要し、CIが頻繁に失敗するプロジェクトでは無視できない負担です。

circleci-logsは、CircleCIのジョブログやワークフロー情報、テスト結果をコマンドラインから取得するCLIツールです。JSON出力に対応しているため、CursorのAgentモードと組み合わせることで「CI失敗の検知 → ログ取得 → エラー分析 → コード修正」をAIエージェントに一括で任せるワークフローを構築できます。

本記事では、circleci-logsのインストールからCursor Agentとの連携設定、実際のCI失敗修正ワークフローまでを紹介します。

circleci-logs の概要

CircleCIのビルドは、以下の階層構造で管理されています。

Pipeline（パイプライン）  1回の git push や定期実行で起動される単位
 └─ Workflow（ワークフロー） ジョブの実行順序・依存関係を定義
     └─ Job（ジョブ）       個々の実行環境で動くステップの集まり
         └─ Step（ステップ）  実際のコマンド実行。ログはここに残る

circleci-logsは、この階層の各レベルに対応した3つのモードを提供します。

目的	コマンド	取得する情報
ジョブのログ取得	`circleci-logs -j <ジョブ番号>`	ステップ一覧とログ出力
ワークフローのジョブ一覧	`circleci-logs -w <ワークフローID>`	各ジョブのステータスと実行時間
パイプラインのワークフロー一覧	`circleci-logs -p <パイプライン番号>`	各ワークフローのステータス

AIエージェントとの連携においてCLIツールが必要な理由は明確です。Cursor Agentはターミナルコマンドを実行してその出力を読み取れますが、Webブラウザを操作できません。circleci-logsを介すことで、AgentはCircleCIのログへ直接アクセスできるようになります。

インストールと初期設定

circleci-logs のインストール

RustのパッケージマネージャCargoを使用してインストールします。circleci-logsはRust 1.87以上で動作し、依存ライブラリはCargoが自動的にダウンロード・ビルドするため、追加の手動設定は不要です。

cargo install circleci-logs

インストールが完了すると、circleci-logsコマンドがパスに追加されます。

もしCargoがない場合は、Rustをインストールしてください。

% brew install rust   
% cargo --version
cargo 1.94.0 (Homebrew)

CircleCI API トークンの設定

circleci-logsはCircleCI APIへのアクセスにPersonal API Tokenを使用します。CircleCI の Personal API Tokens ページでトークンを発行し、環境変数に設定します。

export CIRCLE_TOKEN="your-circleci-token"

exportする以外にも、専用の設定ファイルである.circleci-logs.tomlファイルを配置する方法も選択肢の1つです。この場合プロジェクトごとに配置することも、ホームディレクトリ（~）に配置できます。

% touch ~/.circleci-logs.toml

tomlファイルにはプロジェクトとトークンの２つが設定できます。projectについてはこのあと紹介する自動検知の仕組みが用意されているため、基本的には省略しても問題がなさそうです。ただしtokenにCircleCIのPersonal Access Tokenを設定するため、必ず.gitignore対象に含めましょう。

project = "github/your-org/your-repo"   # optional (auto-detected from git remote)
token = "your-circleci-token"            # optional (environment variable recommended)

基本的な使い方

ここからはcircleci-logsコマンドの使い方を紹介します。いくつかのユースケースが用意されていますので、２つ３つほどピックアップして紹介します。

1: 対話形式でインタラクティブにログを調査する

CircleCIに接続しているプロジェクトの中でcircleci-logs -iコマンドを実行してみましょう。.gitの情報を元にプロジェクトを自動で特定し、どのパイプラインについて調べるかをインタラクティブに選択できます。

circleci-logs -i
Select a pipeline:
> #6        main                           created      2026-03-17 15:10:22
  #5        main                           created      2026-03-17 11:34:23
  #4        main                           created      2026-03-16 20:15:58
  #3        main                           created      2026-03-16 19:24:52
  #2        main                           created      2026-03-16 17:49:44
  #1        main                           created      2026-03-16 17:23:46

flaky testなどによるリトライを行った場合、どのワークフローをみるかを選択できます。

Select a workflow:
  .. (back to pipelines)
> default                   success      2026-03-18 09:40:17
  default                   failed       2026-03-17 15:10:22
  .. (back to pipelines)

続いてログをチェックしたいジョブを指定しましょう。

Select a job:
  .. (back to workflows)
> #14      test-small                failed       2026-03-17 15:10:25
  #15      test-medium-parallel      success      2026-03-17 15:10:25
  #13      test-medium               success      2026-03-17 15:10:24
  #12      test-large                success      2026-03-17 15:10:25

最後にジョブの中のステップを選びます。

Select a step:
  .. (back to jobs)
> [success] Spin up environment                      3s
  [success] Preparing environment variables          0s
  [success] Checkout code                            0s
  [success] Enable Corepack & install pnpm           0s
  [success] Restoring cache                          3s
  [success] Install dependencies (pnpm ci)           0s
  [success] Saving cache                             0s
  [failed ] Run PBT (small / parallelism=1)          7m54s
  [success] Uploading test results                   0s
  [success] Uploading artifacts                      0s

ステップごとの結果や実行時間も表示されますので、「失敗したテストを調査」したい時や「遅いテストの原因」を調べたい時などにも使えそうです。

ステップまで選択すると、ログが表示されます。

 ❯ src/test/FilterPanel.pbt.test.tsx:171:8
    169| describe('FilterPanel - callback properties', () => {
    170|   it('search input 変更時に setSearch が呼ばれる', () => {
    171|     fc.assert(
       |        ^
    172|       fc.property(
 ❯ src/test/FilterPanel.pbt.test.tsx:193:31)" to be called with arguments: [ '<' ]
 ❯ Property.predicate node_modules/.pnpm/fast-check@4.6.0/node_modules/fast-check/lib/fast-check.js:1329:99
 ❯ Property.run node_modules/.pnpm/fast-check@4.6.0/node_modules/fast-check/lib/fast-check.js:1298:24
 ❯ runIt node_modules/.pnpm/fast-check@4.6.0/node_modules/fast-check/lib/fast-check.js:2477:24
 ❯ check node_modules/.pnpm/fast-check@4.6.0/node_modules/fast-check/lib/fast-check.js:2509:204
 ❯ Proxy.assert node_modules/.pnpm/fast-check@4.6.0/node_modules/fast-check/lib/fast-check.js:2512:14
 Test Files  1 failed | 7 passed (8):171:8
      Tests  1 failed | 89 passed (90)
   Start at  06:10:35
   Duration  473.61s (transform 295ms, setup 592ms, import 1.09s, tests 462.80s, environmentJUNIT report written to /home/circleci/project/test-results/junit.xml
Exited with code exit status 1th exit code 1.

次のアクションを選択できるようになっていますので、他のステップもチェックするか、ここでコマンドを終了するかを選びましょう。

Log view:
  Back to steps
> Exit

このようにcircleci-logs -iコマンドを利用することで、CircleCIダッシュボードと同じようなステップにてCLIからログを調査できるようになります。

2: 特定のジョブのログを収集する

調査したいジョブやステップがすでにわかっている場合は、２つのアプローチでログ取得が行えます。

URLを直接渡す

シンプルな方法は、Slackやメールなどで通知されたCircleCIのURLをそのまま渡す方法です。ジョブのIDなどをURLから自動検知してくれますので、より直感的に使うことができます。

# URL を直接渡す（モードは URL の深さで自動判定）
circleci-logs "https://app.circleci.com/pipelines/github/org/repo/123/workflows/UUID/jobs/456"

コマンドを実行すると、失敗したジョブの詳細やステップごとのログが表示されます。--errors-onlyオプションを設定することで、エラーに関係のないログ出力を省略できます。

 ❯ src/test/FilterPanel.pbt.test.tsx:171:8
    169| describe('FilterPanel - callback properties', () => {
    170|   it('search input 変更時に setSearch が呼ばれる', () => {
    171|     fc.assert(
       |        ^
    172|       fc.property(
 ❯ src/test/FilterPanel.pbt.test.tsx:193:31)" to be called with arguments: [ '<' ]
 ❯ Property.predicate node_modules/.pnpm/fast-check@4.6.0/node_modules/fast-check/lib/fast-check.js:1329:99
 ❯ Property.run node_modules/.pnpm/fast-check@4.6.0/node_modules/fast-check/lib/fast-check.js:1298:24
 ❯ runIt node_modules/.pnpm/fast-check@4.6.0/node_modules/fast-check/lib/fast-check.js:2477:24
 ❯ check node_modules/.pnpm/fast-check@4.6.0/node_modules/fast-check/lib/fast-check.js:2509:204
 ❯ Proxy.assert node_modules/.pnpm/fast-check@4.6.0/node_modules/fast-check/lib/fast-check.js:2512:14
 Test Files  1 failed | 7 passed (8):171:8
      Tests  1 failed | 89 passed (90)
   Start at  06:10:35
   Duration  473.61s (transform 295ms, setup 592ms, import 1.09s, tests 462.80s, environmentJUNIT report written to /home/circleci/project/test-results/junit.xml
Exited with code exit status 1th exit code 1.


--- Uploading test results ---
Archiving the following test results
  * /home/circleci/project/test-results/junit.xml

Total size uploaded: 4.4 KiB


--- Uploading artifacts ---
Uploading /home/circleci/project/test-results to test-results
Uploading /home/circleci/project/test-results/junit.xml (29 kB): DONE
Total size uploaded: 28 KiB

ジョブなどのIDを渡す

もちろんパイプラインやワークフロー・ジョブなどのIDを指定して実行できます。この場合は--jsonオプションを使い、jqなどで必要なIDを取得するような方法もとれます。

# 1. パイプラインのワークフロー一覧を取得
circleci-logs -p 123 --json

# 2. 失敗ワークフロー内のジョブ一覧を取得
circleci-logs -w "workflow-uuid" --json

# 3. 失敗ジョブのエラーログを取得
circleci-logs -j 456 --errors-only --json

主要なオプション

circleci-logsは用途に応じた4つの主要オプションを提供します。

オプション	機能	使い分け
`--errors-only`	失敗ステップのみ表示	CI 失敗時の初回調査に使用
`--grep "PATTERN"`	正規表現でログ行をフィルタ	特定のエラーパターンを横断検索する場合に使用
`--tests --failed-only`	失敗したテスト結果のみ表示	テスト失敗時の原因特定に使用
`--json`	JSON 形式で出力	AI エージェントや他ツールとの連携に使用

「失敗したテスト結果のみをJSONで取得する」のような、オプションを組み合わせた使い方も可能です。

circleci-logs "https://app.circleci.com/pipelines/github/org/repo/123/workflows/UUID/jobs/456"--tests --failed-only --json
 | jq .
[
  {
    "name": "FilterPanel - callback properties > search input 変更時に setSearch が呼ばれる",
    "classname": "src/test/FilterPanel.pbt.test.tsx",
    "result": "failure",
    "message": "Error: Property failed after 352 tests\n{ seed: -1285882518, path: \"351:0:6:6\", endOnFailure: true }\nCounterexample: [{\"filterStatus\":\"open\",\"filterPriority\":\"\",\"search\":\"<\",\"sortBy\":\"createdAt\"},\"<\"]\nShrunk 3 time(s)\n\nHint: Enable verbose mode in order to have the list of all failing values encountered during the run\n ❯ buildError node_modules/.pnpm/fast-check@4.6.0/node_modules/fast-check/lib/fast-check.js:2434:16\n ❯ throwIfFailed node_modules/.pnpm/fast-check@4.6.0/node_modules/fast-check/lib/fast-check.js:2441:8\n ❯ reportRunDetails node_modules/.pnpm/fast-check@4.6.0/node_modules/fast-check/lib/fast-check.js:2457:14\n ❯ Proxy.assert node_modules/.pnpm/fast-check@4.6.0/node_modules/fast-check/lib/fast-check.js:2514:7\n ❯ src/test/FilterPanel.pbt.test.tsx:171:8\n\nCaused by: Caused by: AssertionError: expected \"vi.fn()\" to be called with arguments: [ '<' ]\n\nNumber of calls: 0\n\n ❯ src/test/FilterPanel.pbt.test.tsx:193:31\n ❯ Property.predicate node_modules/.pnpm/fast-check@4.6.0/node_modules/fast-check/lib/fast-check.js:1329:99\n ❯ Property.run node_modules/.pnpm/fast-check@4.6.0/node_modules/fast-check/lib/fast-check.js:1298:24\n ❯ runIt node_modules/.pnpm/fast-check@4.6.0/node_modules/fast-check/lib/fast-check.js:2477:24\n ❯ check node_modules/.pnpm/fast-check@4.6.0/node_modules/fast-check/lib/fast-check.js:2509:204\n ❯ Proxy.assert node_modules/.pnpm/fast-check@4.6.0/node_modules/fast-check/lib/fast-check.js:2512:14\n ❯ src/test/FilterPanel.pbt.test.tsx:171:8",
    "run_time": 2.654406528,
    "source": "unknown",
    "file": null
  }
]

--errors-onlyと--grepは排他的なオプションです。まず--errors-onlyで失敗箇所を絞り込み、続けて--grepで特定パターンを検索する順序で使いましょう。

--testsはCircleCIのstore_test_resultsステップを使用しているジョブでのみ利用できます。テスト結果が表示されない場合は、ジョブのconfig.ymlでstore_test_resultsが設定されているか確認してください。

Cursor などのAIコーディングツールとの連携

circleci-logsには、AIエージェント向けのスキル定義ファイルを自動生成する--help-skillオプションが用意されています。このファイルには、ツールの使い方、各オプションの意味、JSON出力のスキーマ、CI失敗調査の推奨手順が記述されています。

例えばCursorを使っている場合は、Agent Skillを配置するディレクトリを用意した上で、circleci-logs --help-skillを利用してファイルを生成すればセットアップは完了です。

# プロジェクトスコープ（このリポジトリ内でのみ有効）
mkdir -p .cursor/skills/circleci-logs
circleci-logs --help-skill > .cursor/skills/circleci-logs/SKILL.md

あとは以下のような指示をCursorへ指示すると、circleci-logsコマンドとAgent Skillを利用してCI/CDパイプラインを調査します。

最新のCI実行結果を調査し、時間のかかっているテストを特定して

調査結果をもとに、CursorのPlanモードを利用したテスト改善計画や、Debugモードを利用したテストエラーの調査などを進めることができます。

注意事項

API トークンの管理

CIRCLE_TOKENはCircleCI上のプロジェクトデータへのアクセス権を持つ認証情報です。以下の点に注意してください。

環境変数での設定を推奨します。設定ファイル.circleci-logs.tomlにトークンを記述する場合は、パーミッションを600に制限し、.gitignoreに追加してリポジトリへコミットされないよう設定してください
共有環境やペアプログラミング時は、トークンが他者に露出しないよう注意してください

フィルタなしのログ取得を避ける

circleci-logsのジョブログは、Dockerビルドや大規模テストスイートでは数千行以上になることがあります。AIエージェントのコンテキストウィンドウには上限があるため、--errors-onlyまたは--grepを必ず指定してログ量を制限してください。フィルタなしで取得すると、ログの途中で文脈を失うおそれがあり、正確なエラー分析は難しくなります。

レート制限

CircleCI APIにはレート制限が設けられています。circleci-logsはHTTP 429（レート制限超過）を受け取ると、Retry-Afterヘッダーに従って自動的にリトライします。短時間の大量リクエストはアクセスブロックを招くことがあります。Agentに連続して複数ジョブのログ取得を依頼する場合は留意してください。

まとめ

circleci-logsとCursor Agentの組み合わせにより、CI失敗時の調査・修正ワークフローを以下のように自動化できます。

--help-skillで生成したSKILL.mdを.cursor/skills/circleci-logs/に配置する
auto-runモードの許可リストにcircleci-logsを追加する
CIが失敗したら、AgentにURLとともに調査を指示する

circleci-logsの詳細な使い方については、GitHub リポジトリのREADMEを参照してください。

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up