ローカルではテストやインストールなどは問題なく進んでいたのに、いざ push すると CI がインストールステップで失敗するという現象が時折発生します。たとえばnpmでパッケージを管理しているアプリでは、以下のようなエラーが発生することがあります。

[chunk validate]: Running install: npm ci
npm error `npm ci` can only install packages when your package.json and
npm error package-lock.json ... are in sync.
npm error Missing: @emnapi/core@1.11.1 from lock file
npm error Missing: @emnapi/runtime@1.11.1 from lock file

本記事では、AI エージェントに実装を任せたセッションで、このような lock ファイルの不整合を push 前に検知する仕組みを紹介します。

CircleCI がリリースした Chunk を利用したローカルで CI 相当の検証を行うことにより、実行環境に依存するタイプの npm ライブラリを利用するプロジェクトで、push 後に CI がインストールステップで fail してしまう問題を解決します。

npm でネイティブ系パッケージのインストールに失敗するケース

WebAssembly ・ネイティブ系のライブラリをインストールしているか、依存関係に含めている場合、 npm install でライブラリをインストールすると、コマンドを実行した環境向けのパッケージのみがインストールされます。そのため、開発はmacOSでCIはLinux系のような異なる環境が開発サイクルの中に存在する場合、npm installした時と異なる環境では依存関係が見つからないというエラーが発生します。

この多くは、npm がプラットフォーム固有の optional 依存を package-lock.json に取りこぼす問題だとされています。

この現象は、通常のローカル開発では気づきにくいという厄介さがあります。ローカルで日常的に使う npm install はこの不整合を許容して進み、厳密に検査する npm ci は通常 CI でしか実行されないためです。つまり、push して CI が回るまで表面化しません。

`npm install` と `npm ci` の厳密さの違い

この不整合がローカルで表面化しないのは、日常的に使うコマンドが npm install だからです。両者の違いを次に示します。

観点	`npm install`	`npm ci`
lock との整合	差分があれば lock を更新して続行する	差分があればその時点で失敗する
node_modules	既存のものを再利用する	削除して作り直す
主な実行場所	ローカルの開発中	CI

npm install は lock ファイルとのずれを許容して進むため、不整合があっても気づけません。一方、CI が実行する npm ci は lock ファイルを厳密な正とするため、そこで初めて失敗します。結果として、この不整合は push して CI が回るまで表面化しません。

Chunk Sidecar で Push 前の検証を必須化する

このような CI 環境でしか発生しない問題を発見するには、CIと同等の実行環境を利用した検証を実装時に行う必要があります。CircleCI が2026/07時点でプレビュー提供中の Chunk Sidecarは、この「ローカルあるいはコーディングエージェントが利用できる、CIと同等の実行環境を microVMで提供する仕組み」です。

Chunk CLIを事前にインストールし、chunk initコマンドを実行しましょう。リポジトリやパッケージマネージャ・テストコマンドなどを分析して、Claude Code向けのHookなどを設定します。

% chunk init
Detected package manager: npm
Detected command: test (npm test)
✓ Wrote .chunk/config.json
✓ Updated .gitignore with sidecar tracking patterns
✓ Wrote .claude/settings.json

Next step: scaffold .circleci/test-suites.yml for Smarter Testing
  Ask your AI coding agent to scaffold .circleci/test-suites.yml — the
  chunk-sidecar skill covers the file shape and per-language patterns.
  Or rerun with --skip-test-suites=false to use built-in Go/pytest templates.
✓ Project initialized

簡単な nodejs アプリで chunk initとchunk skill installを実行すると、テストコマンドなどのタスクが.chunk/config.jsonに登録されます。

 % cat .chunk/config.json   
{
  "commands": [
    {
      "name": "install",
      "run": "npm ci",
      "remote": true
    },
    {
      "name": "test",
      "run": "npm test",
      "role": "gate",
      "timeout": 300,
      "limit": 3,
      "remote": true
    }
  ],
  "vcs": {
    "org": "hidetaka-cci",
    "repo": "vitest-run-changed-test"
  }
}

同時にClaude CodeのHookに、chunkコマンドを利用した検証が登録されます。


    "Stop": [
      {
        "hooks": [
+          {
+            "type": "command",
+            "command": "chunk validate",
+            "timeout": 600
+          }
        ]
      }
    ]

これによって、コーディングタスクがひと段落した（Stopした）タイミングにて、.chunk/config.jsonに定義された検証タスクが実行されます。

% chunk validate --list
  install: npm ci
  test: npm test

この仕組みによってnpm ciやnpm testコマンドが定期的に実行されるため、コーディングエージェントが push して CI を実行する前に問題を発見できます。


⏺ Ran 1 stop hook 
⎿  Stop hook error: [chunk validate]:
Running install: npm ci
npm error code EUSAGE
npm error
npm error `npm ci` can only install packages when your package.json and package-lock.json or npm-shrinkwrap.json are in sync. Please update your lock file with `npm install` before continuing.
npm error  npm error Missing: @emnapi/core@1.11.1 from lock file

Claude Codeが問題を検知したため、この後コマンドを実行してpackage-lock.jsonの更新が実行されます。

  Ran 2 shell commands
  package-lock.json を更新しました。テストは引き続き74件パスしています。

実際の作業では、package-lock.jsonの変更についてこの後報告があり、それを読んだことで著者がnpmにおける既知の Issue （npm/cli#4828）由来だと気づきました。そしてこの後問題を確実に回避するために、パッケージマネージャーを pnpmへ移行させています。

まとめ

パッケージマネージャーの仕様やライブラリの作りによっては、ローカルでは問題なく動くアプリが CI のインストールステップで失敗することがあります。

Chunk Sidecar のような CI 相当の検証をローカルで行う仕組みを取り入れることで、このような不整合を push 前に検出できます。本記事の事例では、ローカルで 74 件のテストがすべて通過したにもかかわらず、chunk の検証ゲートが実行した npm ci が lock ファイルの不整合を検出しました。AI エージェントによるコード生成は高速ですが、生成物がクリーンな環境でも成立するかは別の問題です。CI 相当の検証を inner loop に置くことで、この差を push 前に埋められます。

次のステップ

chunk を試す手順は次のとおりです。

Chunk CLI をインストールする
プロジェクトで chunk init および chunk skill install
を実行し、スタックと検証コマンドを検出させる
AI エージェントから検証を inner loop で実行する