CircleCI Chunk で、休んでいる間にフレーキーテストを自動修正

テストが失敗したとします。しかし、再実行すると成功します。あなたは、その原因を深く追究することなく、次の作業に移ります。

このように、ほとんどのチームが、フレーキーテストが発生すると、テストが成功するまで再実行するという対処法をとります。たしかに、失敗したテストの再実行は、一時的な回避策や問題の切り分けに役立ちます。しかし、再実行では根本的な問題は解決しません。長期的には、CI リソースの浪費につながり、コードの不安定さを覆い隠してしまう可能性があります。

一方で、フレーキーテストの修正には何時間もの作業が必要になることがあります。誰も優先したくない退屈なデバッグ作業です。

では、その作業が自動化されるとしたらどうでしょうか。CI システムがテストの失敗を分析し、原因を特定、あなたが休んでいる間に検証済みの修正案まで準備してくれるとしたら？

CircleCI の自律型検証エージェント Chunk なら、まさにそれが実現します。Chunk はテスト履歴を分析し、フレーキーテストを特定するだけでなく、その根本原因を突き止め、検証済みの修正を含むプルリクエスト（PR）を自動で作成します。パイプラインのメンテナンスと安定化を自動で行うため、開発者は質の高いコードの作成に集中したり、十分な休息を取ったりできるようになります。

このガイドでは、Chunk のセットアップ手順を順を追って詳しく解説します。具体的には、Chunk の有効化、スケジュールの設定、テスト環境の整備、そして継続的な改善のためのステップです。これらの設定を完了すれば、Chunk は自動的に動作し、テストスイートの安定化を静かにサポートし続けます。

Chunk の導入方法

まずは、以下を準備してください：

CircleCI アカウント
CircleCI でテストを実行しており、 store_test_results ステップが設定されているプロジェクト（CircleCI はこれを使ってフレーキーテストを識別します）
OpenAI または Anthropic の API キー

Chunk は BYOK（Bring Your Own Key）モデルを採用しているため、コードは選択したプロバイダーに保管され、CircleCIには送信されません。

Chunk のセットアップ

Chunk を使うには、有効化とサービス接続が必要です。CircleCI のセットアップ画面の指示に従ってください：

Chunk を有効にする： CircleCI ウェブアプリから組織ページに移動し、サイドバーから「Chunk Tasks」を探します。「Get Started」をクリックし、プロンプトが表示されたら「Continue」をクリックします。
GitHub App を確認する： 組織に GitHub App がすでにインストールされていることを示すチェックマークアイコンが表示されるはずです。表示されない場合は、「Install CircleCI GitHub App」ボタンからインストールしてください（この手順を完了するには管理者権限が必要です）。現在 OAuth を使用している場合でも、既存のパイプラインに影響を与えたり、何かを移行したりすることなく、GitHub App を安全にインストールできます。
AI モデルプロバイダーを選択する：Anthropic または OpenAI のいずれかを選択します。
API キーを入力する：選択したモデルプロバイダーの API キーを追加します。
セットアップを完了する：「Next」をクリックすると、API キーが保存される circleci-agents というコンテキストが作成されます。

タスクの割り当て

Chunk のセットアップが完了したら、最初の「Fix flaky tests」タスクを割り当てます。ここでは、Chunk をいつ実行するか、どのように動作させるかを設定します。

Chunk task setup

まず、Chunk に分析させたいプロジェクトを選択します。プロジェクトはすでに CircleCI で実行されており、有効なテストスイートと store_test_results ステップが設定されている必要があります。

次に、実行スケジュールと動作制限を設定します。

Run frequency：Chunk がテストを分析するタイミングを選択します。

Daily：月曜〜金曜の毎朝 7:00（日本時間）に実行
Weekly：月曜日の朝 7:00（日本時間）に実行（デフォルト設定）
Monthly：毎月2日の朝 7:00（日本時間）に実行

Operational limits：Chunk が処理する作業量をコントロールします。

Maximum tests to fix per run： Chunk が１回の実行で対処するフレーキーテストの数。様子を見ながら少しずつ始めたい場合は少なめに、バックログを早く処理したい場合は多めに設定します。
Number of solutions to try per test：最初の修正が失敗した場合に、Chunk が試みる別の方法の数。１から始め、Chunk の最初の修正で不安定性が解消されない場合は増やしてみましょう。
Number of validation runs per test：修正の安定性を確認するために、Chunk が各テストを実行する回数。実行回数が多いほど確実ですが、処理時間も長くなります。
Maximum number of concurrent open PRs： Chunk が同時に作成できるプルリクの数。レビュー負荷が高い場合は少なめに、修正を素早く進めたい場合は無制限に設定します。

適切な設定は、チームのレビュー能力とフレーキーテストのバックログの大きさによって異なります。どこから始めればよいか分からない場合は、デフォルト設定がほとんどのチームに適しています。結果に基づいて、いつでもこれらの数値を調整できます。

「Start Task」をクリックしてセットアップを完了します。Chunk はすぐに実行を開始し、設定したスケジュールに従って動作します。

テスト環境の設定

Chunk は、テストをどのように起動すべきか正確に把握している場合に最も効果を発揮します。環境定義により、Chunk は依存関係インストール、サービス接続、テスト実行を適切に行えます。これらの詳細は、デフォルトブランチの .circleci/cci-agent-setup.yml ファイルで指定できます。

このファイルには、 cci-agent-setup という名前の単一のジョブを持つワークフロー（名前は任意）が必要です。Postgres を使用する Python プロジェクトの例は以下のとおりです：

version: 2.1

workflows:

  main:

    jobs:

      - cci-agent-setup

jobs:

  cci-agent-setup:

    docker:

      - image: cimg/python:3.12

      - image: cimg/postgres:15.3

    steps:

      - checkout

      - run:

          name: Install Dependencies

          command: |

            pip install -r requirements.txt

      - run:

          name: Setup Database

          command: |

            psql -c "CREATE DATABASE test_db;" -U postgres

こちらでは環境準備だけを記述してください。具体的には、依存関係のインストール、データベースのセットアップ、サービスの設定です。実際のテスト実行コマンドは不要です。Chunk が、メインの CircleCI 設定と指示ファイルを分析して自動的に判断します。cci-agent-setup.yml では Orb とカスタムリソースクラスが利用できます。

環境設定をテストするには、「Organization Settings」→「Chunk Tasks」を開き、三点メニューから「Chunk Environment」を選択します。ブランチで cci-agent-setup.yml ファイルを実行して動作を確認し、問題があれば修正を繰り返し、正常に動作したらデフォルトブランチにマージします。

（オプション）テスト規約をドキュメント化する

すべてのチームには、独自のテストパターン、よく使うツール、コードスタイルのルールがあります。これらを文書化すれば、Chunk が学習できます。こうしたコンテキストを提供することで、Chunk の修正提案がチームの標準に合ったものになります。

ガイダンスは次のいずれかの方法で追加できます：

リポジトリルートに claude.md または agents.md を作成し、テスト実行の一般的な手順を記載
.circleci/fix-flaky-test.md を作成し、フレーキーテスト特有のガイダンスを記載

以下は. .circleci/fix-flaky-test.md ファイルの例です：

## Command restrictions

- You MUST NOT use the `sleep()` command or `setTimeout()` for delays in any scripts
- You MUST NOT use `eval()` as it poses security risks
- Avoid using shell wildcards in destructive operations (e.g., `rm -rf *`)

## Code style preferences

- Prefer functional components over class components in React
- Use TypeScript `type` definitions instead of `interface` (this project enforces this via ESLint)
- Favor explicit error handling over try-catch-all patterns
- Use async/await syntax over Promise chains for readability

## Security considerations

- Always flag use of `dangerouslySetInnerHTML` in React components
- Highlight any potential SQL injection vulnerabilities
- Point out hardcoded credentials or API keys
- Flag any use of `eval()` or `Function()` constructors

## Documentation standards

- Complex algorithms MUST include explanatory comments

Chunk はこれらのファイルを自動的に検出し、修正を生成する際にそのルールを適用します。この手順を省略しても、動作する修正パッチは生成されますが、チームの推奨パターンと完全には一致しない可能性があります。

Chunk の修正をレビューする

Chunk がフレーキーテストを見つけて修正すると、修正案を含むプルリクエストを作成します。問題の原因、変更内容、検証方法が明確に説明されています。

各プルリクエストには以下が含まれます：

Run summary：Chunkが検出した問題と修正内容の概要
Root cause：テストが不安定になった理由を分かりやすく説明（例：決定性のないタイマー、ランダムなデータ、厳しすぎるアサーション）
Proposed fix：テストを安定させるための具体的なコード変更
Verification：不安定性が解消されたことを示すテスト再実行の結果

利用可能な場合、プルリクエストには分析の裏付けとなる過去の CI 実行結果や失敗ログも含まれます。

Chunk の作業状況は、CircleCI ウェブアプリから直接確認できます。Chunk Tasks ページでは、エージェントが分析したすべてのテストがリアルタイムで表示され、それぞれのステータスと結果を確認できます。

Chunk task page

各行は分析中のテストを表し、プロジェクト名、完了時刻、プルリクエストが作成されたかどうかが表示されます。これにより、どのテストが修正されたか、どのテストがまだ対応が必要かを一目で確認できます。

タスクをクリックすると詳細なレポートが表示されます。

Chunk details

上部の Run Summary セクションには、検出された根本原因、適用された修正、再実行の検証結果といった最も重要な情報がまとめられています。その下に、さらに２つのタブがあります：

Code diff：Chunk が提案したコード変更を元のテストと並べて表示します。CircleCI の UI 上で直接レビューやマージができる便利な機能です。
Logs：エージェントの推論プロセス、分析手順、検証結果の全体を表示します。このタブで、Chunk がどのように結論に達したかを理解できます。修正が不完全な場合や、失敗した試行のデバッグが必要な場合に役立ちます。

修正が不完全でプルリクエストが作成されなかった場合でも、結果はダッシュボードに保持されます。推論内容を確認し、設定を調整することで、後から再分析できます。

（オプション）アドホックタスクの実行

定期的なメンテナンスサイクルとは別に、単発の変更を Chunk に処理させたいケースもあるでしょう。例えば、非推奨コードのクリーンアップや、テストスイートの一部を標準化する際などです。

そんな時に便利なのが、アドホックタスクです。

「Organization Settings」 →「Chunk Settings」を開きます。
三点メニューから「Submit Ad Hoc Task」を選択します。
任意の既存ブランチから、Chunk に完了してもらいたいタスクの内容を具体的に記述します。（例：非推奨の API 呼び出しをすべて最新のクライアントライブラリに更新」など）

Chunk は、この記述に基づいて変更作業を実施し、そのブランチに自動でプッシュします。

アドホックタスクは、.circleci/cci-agent-setup.yml で定義した環境を使用するため、定期メンテナンスと同じコンテキストと依存関係で動作します。結果はChunk Tasks ダッシュボードで、フレーキーテストの修正と一緒に確認できます。

継続的な改善

最初のスケジュール実行後は、Chunk Tasks ページで処理内容を確認しましょう。ログで成功箇所と問題箇所が分かります。このフィードバックを活用して設定を改善していきます。

Chunk がテスト実行で躓いた場合は、cci-agent-setup.yml に足りない依存関係を追加するか、指示ファイルでテストコマンドをより明確に記述します。修正内容がチームの方針と合わない場合は、ドキュメントに具体的なガイドラインを追記してください。

Chunk の PR レビュー時は、繰り返し出てくるパターンに注目しましょう。タイミングの問題が繰り返し発生する場合は、より適切な非同期処理パターンをドキュメント化する必要があるかもしれません。ランダムデータの問題が頻発する場合は、テストデータ生成の仕組みの導入を検討しましょう。こうしたパターンから、新たなフレーキーテストを未然に防ぐ方法が見えてきます。

Chunk の修正内容に問題がないことを確認したら、チームのレビュー体制に合わせて、同時並行で処理する PR の動作制限を調整します。同時に処理する PR の数を増やせば、より迅速に作業を進めることができます。一方で、PR が溜まりすぎている場合は、同時実行数を減らしましょう。