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

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

CI が失敗したとき、多くの開発者は CircleCI の Web UI を開き、パイプライン → ワークフロー → ジョブと画面をたどって失敗したステップのログを確認しています。エラー箇所を特定したら、その内容をエディタにコピーし、修正方法を検討する必要があります。この一連の作業は手動で行うと数分から十数分を要し、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ファイルを配置する方法も用意されています。この場合プロジェクトごとに配置することも、ユーザーディレクトリ``に配置することも可能です。

% 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: 特定のジョブのログを収集する

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

2-1: 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

2-2: ジョブなどの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 を必ず指定してログ量を制限してください。フィルタなしで取得すると、Agent がログの途中で文脈を失い、正確なエラー分析ができなくなる可能性があります。

レート制限

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