flaky test を直す。テストカバレッジを少し上げる。細かいリファクタをする。どれも「やった方がいいが後回しになる」作業です。

CircleCI の提供する Chunk は、こうした作業をタスクとして受け取り、リポジトリ上でコードを読み、テストを走らせ、PR を作成するところまでを自律的に行うエージェントです。CircleCI の Web アプリの中で動きます。

ただし、React SPA / Hono REST API / PostgreSQL という3層構造のモノレポでは、API のテストが PostgreSQL に接続します。Chunk がそのテストを通すには、Chunk が作業する環境に PostgreSQL などをあらかじめセットアップしておく必要があります。この作業環境を定義するのが cci-agent-setup.yml です。

この記事では、モノレポや DB などの依存環境を持つアプリケーションで Chunk によるコーディングタスクを任せるための、cci-agent-setup.yml設定方法を紹介します。

前提条件

以下の3層モノレポ構成を想定します。

my-app/
├── apps/
│   ├── web/          # React SPA (Vite + React)
│   └── api/          # Hono REST API (Node.js)
├── packages/
│   └── shared/       # 共有型定義など
├── package.json      # ワークスペースルート (pnpm)
├── docker-compose.yml
└── .circleci/
    ├── config.yml            # 通常の CI パイプライン
    └── cci-agent-setup.yml   # ← この記事で作る

Step 1. Chunk by CircleCI を有効にする

最初に、組織側で Chunk を使える状態にします。設定は2か所です。

1か所目は、組織設定の Organization Settings → Advanced にある「Allow Chunk Tasks」です。これを有効にすると、組織内で Chunk タスクを設定・実行できるようになります。

2か所目は、Chunk Settings です。ここで対象リポジトリの GitHub App を接続し、モデルプロバイダを選びます。既定の CircleCI (Powered by Anthropic) を選べば API キーは不要で、1日あたり40万トークンを無償で使えます（12:00 UTC にリセット）。自前のキーを使う場合は Anthropic / OpenAI / Amazon Bedrock を選べます。いずれの資格情報も、組織の circleci-agents コンテキストに自動で保存されるため、手動で作る必要はありません。

Step 2. cci-agent-setup.yml で作業環境を定義する

cci-agent-setup.yml は、Chunk が「開発者のローカルマシン」の代わりに使う作業環境の初期状態を定義するファイルです。ビルド・テスト・デプロイのパイプラインを定義する .circleci/config.yml とは別物で、依存のインストールと周辺サービスの起動だけを記述します。ルールは、単一のワークフローと、cci-agent-setup という名前の単一ジョブを含めることです。テストを実行するステップは不要で、環境を立ち上げるところまでに徹します。

cci-agent-setup.yml では、通常の CircleCI Docker executor が使えます。そのため、サービスコンテナで PostgreSQL を併走させる、この記事の3層構成にそのまま合う書き方ができます。以下が最小構成です。

version: 2.1

orbs:
  node: circleci/node@7.1.0

workflows:
  cci-agent-setup:
    jobs:
      - cci-agent-setup

jobs:
  cci-agent-setup:
    docker:
      # プライマリコンテナ: Chunk とアプリコードが動く場所
      - image: cimg/node:20.11
        environment:
          DATABASE_URL: postgresql://circleci:password@localhost:5432/myapp_test
      # サービスコンテナ: API 層が接続する PostgreSQL
      - image: cimg/postgres:16.0
        environment:
          POSTGRES_USER: circleci
          POSTGRES_PASSWORD: password
          POSTGRES_DB: myapp_test
    resource_class: large
    steps:
      - checkout
      - node/install:
          install-pnpm: true
          pnpm-version: "9.15.0"     # package.json の packageManager に合わせる
      - node/install-packages:
          pkg-manager: pnpm
      - run:
          name: Wait for PostgreSQL
          command: dockerize -wait tcp://localhost:5432 -timeout 60s
      - run:
          name: Run database migrations
          command: pnpm --filter api run db:migrate

サービスコンテナの PostgreSQL には localhost:5432 でアクセスできます。CircleCI の Docker executor はすべてのコンテナを同一ネットワークに置くため、特別な設定は不要です。プライマリコンテナに DATABASE_URL を渡し、dockerize -wait で起動を待ってからマイグレーションを実行しています。resource_class: large は、React のビルドと Hono のテストを同一コンテナで走らせるとメモリ不足でプロセスが kill されることがあるためです。まず medium で試し、OOM に遭遇したら上げる進め方でも構いません。

`cci-agent-setup.yml`のワークフロー名は、CICDで利用するワークフロー名と重複させない

Chunk はタスク実行時に、cci-agent-setup.yml の steps を内部の chunk-task というジョブに載せ替えて config.yml とマージします。このとき cci-agent-setup.yml と config.yml の両方のワークフロー名が main だと、Cannot find a definition for job named cci-agent-setup でコンパイル自体が errored になります。

上の例のようにワークフロー名を cci-agent-setup にして、config.yml 側の main と分ければ解消します。

.circleci/cci-agent-setup.yml をデフォルトブランチにコミットしてpushしておきましょう。

Step 3. タスクを投げて PR を受け取る

Chunk へのコーディング指示は、CircleCIダッシュボードのチャット UI から行えます。

対象リポジトリ・ブランチ・環境（Environment）を選び、やってほしいことを自然文で書くか、Extend test coverage のような定型スキルを選びます。

たとえば「フロントエンドアプリで、/users/count を呼び出してユーザー数を表示するようにして」というタスクを依頼してみましょう。Chunk はコードを読み、変更を加え、テストを走らせた上で PR を作成します。タスクが完了すると PR へのリンクや、Logs / Diffs / Pipelines タブの情報が表示されます。

このタスクは cci-agent-setup.yml で定義した環境の中で実行されます。実際のパイプラインを見ると、Wait for PostgreSQL と Run database migrations が走った上で Chunk task が実行されていることが確認できます。

Tips：claude.md でモノレポの作法まで渡す

Chunk は Claude Agent SDKの上に作られています。

そのため、Chunkでのコーディングタスクは、Claude Code 向けのドキュメントやハーネスをある程度認識します。そのため、claudeの /initコマンドなどでCLAUDE.mdファイルを生成しておくことで、テストの回し方やアーキテクチャの前提などをエージェントに伝えやすくなります。

例えば以下のようなMDファイルを配置してみましょう。pnpm のフィルタコマンド、テストが Vitest であること、DB が localhost:5432 にあること、docker-compose.yml やワークスペースルートを触るなという指示。このような指示を記載しておくことで、Chunk はルートで npm test を叩いて失敗したり、ローカル開発専用のファイルを触ったりするミスをなくせます。

# Project Guide for Chunk

## Architecture
This is a monorepo with 3 layers:
- `apps/web`: React SPA (Vite). Tests use Vitest.
- `apps/api`: REST API (Hono, Node.js). Tests use Vitest.
- `packages/shared`: Shared TypeScript types and utilities.

## Package Manager
pnpm workspaces. Always use `pnpm --filter <package>` to scope commands.

## Testing
- Frontend: `pnpm --filter web run test`
- API: `pnpm --filter api run test`

## Database
PostgreSQL is available at `localhost:5432` (see cci-agent-setup.yml).
Migrations: `pnpm --filter api run db:migrate`

## Do NOT
- Do not modify `docker-compose.yml` (local development only).
- Do not add dependencies to the workspace root.

まとめ

Chunk にモノレポの作業を任せるためにやることは、cci-agent-setup.yml で Chunk が作業する環境を用意することをお勧めします。あとはタスクを投げれば、Chunk がコードを読み、テストを走らせ、修正を PR として届けます。さらに claude.md を足せば、pnpm のフィルタや DB の場所といったモノレポ特有の作法まで踏まえて動いてくれます。

参考リンク

Chunk overview and setup: https://circleci.com/docs/guides/toolkit/chunk-setup-and-overview/
Chunk の事例（Anthropic customer story）: https://claude.com/customers/circleci
CLAUDE.md と /init について（Anthropic）: https://claude.com/blog/using-claude-md-files
検証用リポジトリ: https://github.com/hidetaka-cci/demo-chunk-hono-postgre