テストを直してpushしたのに、CIが失敗する。
フロントエンド・APIどちらのテストがこけているのかを調査し、ログを確認する。
修正したが、今度は共有モジュールの依存関係でインストールステップが失敗する。
モノレポのアプリケーションでは、意図しない連鎖ゲームによるCI復旧時間（ MTTR ）の増加が心理的なストレスになりがちです。また、AIコーディングによるコード生成の高速化は、CIパイプラインの実行数を増加させ、失敗したCIの確認や修正コストをより増やすリスクも内包しています。
「push してからでないと分からない」問題を軽減する方法について、CircleCI は研究を続けています。2026に公開した State of Software Deliveryでは、feature ブランチの活動が増える一方で main ブランチのスループットは低下し、ワークフローの失敗率が近年で最悪の水準に達したと報告されています。
CircleCIでは、「すべての問題をCIにて検証させないこと」を提案しています。手元の開発サイクルあるいはエージェントのコーディングセッションを「Inner Loop」、そしてCIやレビュー・デプロイリリースなどのチーム・PJ単位のワークロードを「Outer Loop」と定義します。そしてAIが高速化するInner Loopの成果物で、Outer Loopが詰まらないようにすることを目指す必要があると提唱しています。
この記事では、React SPA / Hono REST API / PostgreSQL という3層モノレポに対して、Inner Loopでの検証をAIの速度で実現する方法を紹介します。
デモリポジトリについて
今回は以下のようなモノレポで構成されたアプリをベースに紹介します。ReactアプリとHonoのAPI、そしてPostgreSQLを利用したデータベースを利用する３層アプリケーションです。
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
API 層はテスト時に PostgreSQL へ接続します。この記事はデプロイには踏み込まず、push 前の検証（インナーループ）に絞ります。
事前準備
Chunk Sidecarを動かす用の CircleCI アカウント（無料）
Chunk Sidecarを使った検証には、CircleCIアカウントが必要です。無料プランで試すことができますので、アカウント登録だけ済ませておきましょう。
その後[ User Settings → Personal API Tokens ] からPersonal API TOkenを発行しておきましょう。
Git リポジトリのUpstream設定
Git リポジトリ側にも準備が必要です。Chunk Sidecar を使うには、コードベースが GitHub リポジトリに pushされている必要があります。そのため、git remote add originコマンドでプロジェクトと GitHub リポジトリを接続しておきましょう。
$ git remote add origin git@github.com:<your-account>/<your-repo>.git
$ git push -u origin main
# origin が設定されていることを確認する
$ git remote -v
origin git@github.com:<your-account>/<your-repo>.git (fetch)
origin git@github.com:<your-account>/<your-repo>.git (push)
Step 1. chunk CLI を入れて初期化する
Chunk Sidecar のセットアップは chunk CLI を使います。macOSなどでは、Homebrew からインストールできます。
$ brew install CircleCI-Public/circleci/chunk
$ chunk --version
chunk version 0.7.77
次に CircleCI で認証を行いましょう。chunk auth set circleciコマンドで Personal API Token を登録します。
$ chunk auth set circleci
その後プロジェクトルートで chunk init を実行しましょう。chunk init は package.json を読み取ってパッケージマネージャ（今回は pnpm）と test スクリプトを検出し、それを検証コマンドとして .chunk/config.json に記録します。同時に、Claude Code 用の .claude/settings.json にフック設定を生成します
$ chunk init
Detected package manager: pnpm
Detected command: test (pnpm test)
✓ Wrote .chunk/config.json
✓ Wrote .claude/settings.json
モノレポでは、chunk init はルートの pnpm test を 1 本だけ拾います。apps/web / apps/api / packages/shared を個別には登録しません。生成された config は次のとおりです。
{
"commands": [
{ "name": "install", "run": "pnpm install --frozen-lockfile" },
{ "name": "test", "run": "pnpm test", "role": "gate", "timeout": 300, "limit": 3 }
]
}
レイヤー別に検証したい場合は、次のような形で .chunk/config.json に名前付きコマンドを足しましょう。
{
"name": "test-api",
"run": "pnpm --filter api run test",
"role": "gate",
"timeout": 300,
"remote": true
},
{
"name": "test-web",
"run": "pnpm --filter web run test",
"timeout": 120,
"remote": true
}
続いて CircleCI の Organization を登録します。[Organization Settings > Overview]からOrganization IDを取得しましょう。
あとはchunk config set orgIDコマンドで登録するだけです。
$ chunk config set orgID <your-org-id>
最後にChunk Sidecarをコーディングエージェントが使うためのスキルをインストールします。
% chunk skill install
コマンドを実行すると、Claude Codeのスキルとしてインストールされます。
% ls -la ~/.claude/skills | grep chunk
drwxr-xr-x 3 hidetaka staff 96 3月 27 16:11 chunk-review
drwxr-xr-x@ 3 hidetaka staff 96 7月 9 11:41 chunk-sidecar
drwxr-xr-x 3 hidetaka staff 96 3月 27 16:11 chunk-testing-gaps
Step 2. Chunk sidecar をエージェントにセットアップさせる
セットアップが完了した後は、コーディングエージェントにセットアップ等の指示も任せましょう。
「chunk sidecar をセットアップして」と伝えるか、以下のようにスラッシュコマンドで指示することで、エージェントがスキルを使用します。
/chunk-sidecar Use when the user says "validate on the sidecar", "run tests on the sidecar", "sync to sidecar", "sidecar dev loop",
"check this on the sidecar", "validate remotely", "scaffold test-suites.yml", "set up smarter testing", "write .cir…
──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
❯ /chunk-sidecar
──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
スキルを起動した後は、エージェントが Sidecar の作成やリモート環境との同期・スナップショットの保存とテストの実行などが自律的に実行されます。
エージェントに任せず手元で直接検証を回したいときは、chunk validate --remote を実行します。Chunk Sidecarで実行されるテスト・検証コマンドについては、chunk validate --listコマンドで確認できます。
% chunk validate --list
install: pnpm install --frozen-lockfile
test: pnpm test
test-api: pnpm --filter api run test
test-web: pnpm --filter web run test
Step 3. テスト環境を共有可能なスナップショットに保存する
Dockerでコンテナイメージを作成してチームへ共有するように、Chunk Sidecarを利用したmicroVMも環境を共有可能な形で保存できます。microVMにはスナップショット作成機能があり、chunkコマンドから作成を指示できます。
CLIから直接実行する場合は、次のようなコマンドを実行しましょう。
$ chunk sidecar snapshot create --name my-app-baseline
✓ Created snapshot 6be94926-58b2-4eaa-9794-dfd0bbd69257
✓ Deleted sidecar <source-id>
エージェントに「スナップショットを作成しなさい」と指示することでも作成できます。その場合も内部的にはchunk sidecar snapshot createコマンドが実行されています。
作業を再開するときは、snapshot から新しい sidecar を起動しましょう。
$ chunk sidecar create --name my-app-dev --image <snapshot-id> --org-id <your-org-id>
チームで確実に共有するために、作成したスナップショットのIDを固定することも可能です。
$ chunk config set validation.sidecarImage <snapshot-id>
スナップショットを作成しておくことで、毎回行う必要がある環境セットアップなどの手順を省略し、検証タスクとしてのコマンド実行だけにフォーカスできます。
Step 4. エージェントが Chunk Sidecar を使って検証しながら開発をする
chunk init を実行すると、 .claude/settings.json にClaude Code 用に2つのフックが登録されます。
{
"permissions": { "allow": ["Bash(chunk:*)"] },
"hooks": {
"PreToolUse": [{
"matcher": "Bash(git commit*)",
"hooks": [ ... ]
}],
"Stop": [{
"hooks": [ ... ]
}]
}
}
PreToolUseフックでgit commitコマンドを実行する前に検証を強制させています。同時にエージェントの行動ターンが終了するたびにトリガーされるStopフック側でも、軽量な検証タスクを実行できます。Claude Codeはこの２つのHookを利用して Chunk Sidecar が用意した検証環境上でのテストやLintといった検証タスクを実施します。
もしClaude Code以外のコーディングエージェントを使う場合でも、Hookにchunk validateコマンドを定義すれば、同様のタイミングでの検証を実現できます。
どのテストをサイドカーで回すか
最後に、Chunk Sidecarに任せるテストと任せないテストについて整理しましょう。
今回のような３層アプリケーションでは、次のようなテストが必要となります。
- Reactアプリケーションに対する単体テスト
- Honoアプリケーションに対する単体テスト
- HonoアプリケーションとPostgreSQLとの統合テスト
- ReactアプリケーションとHonoアプリケーションとの統合テスト
- ３層全体を通したE2Eテスト
Chunk Sidecarでの検証は、このうち単体テストのみをターゲットとします。結合テストを行うとなると、PostgreSQLサーバーを実際に起動させたり、HonoのAPIを起動させる必要があります。このような種類のテストを行うには、microVMを利用するよりもCIサービスまたはローカル上で Docker コンテナを利用する方が効率的です。
よって Chunk Sidecar での検証については、単体テストやリント・型チェックといった、依存関係の少ない項目にフォーカスすることをお勧めします。
まとめ
この記事では、React SPA / Hono API / PostgreSQL の3層モノレポに対して、push 前の検証ループを組む手順を紹介しました。
| ステップ | やること |
|---|---|
| Step 1 |
chunk init で CLI を初期化し、レイヤー別の検証コマンドを .chunk/config.json に登録する |
| Step 2 |
/chunk-sidecar スキルでエージェントにChunk Sidecar をセットアップさせる |
| Step 3 | 検証環境をスナップショットに固めてチームで共有する |
| Step 4 |
PreToolUse / Stop フックで、コミット前・ターン終了時に自動検証を走らせる |
単体テストや Lint / Type Checkなどをエージェントの開発サイクル内で実行することにより、pushして数分と経たずに CI が failして修正作業に戻るという手戻りをなくせます。また Stop フックでの検証がまわることによって、エージェントが犯した小さなミスを、早い段階で検知できるようになり、それによる将来的な不具合の顕在化を阻止的ます。
人間がコードを push し、PRを作成前にやる検証作業をエージェントに仕組みとして矯正する。 開発サイクルをより信頼でき、トークン効率の良い形に支援するためのハーネスとして、Chunk Sidecar をお試しください。
参考リンク
- Chunk sidecars overview and setup: https://circleci.com/docs/guides/toolkit/how-to-use-chunk-cli/
- Introducing Chunk sidecars: https://circleci.com/blog/chunk-sidecars/
- Chunk sidecar snapshots: https://circleci.com/blog/chunk-sidecar-snapshots/
- Chunk sidecar agent hooks: https://circleci.com/blog/chunk-sidecar-agent-hooks/
- 検証用リポジトリ: https://github.com/hidetaka-cci/demo-chunk-hono-postgre
- 検証レポート（詳細ログ）: リポジトリ内
chunk-monorepo-verification-report.md