0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

ローカルの `npm test` が通るのに CI で落ちる原因を chunk sidecar で push 前に検出する

0
Last updated at Posted at 2026-07-27

ローカルではテストやインストールなどは問題なく進んでいたのに、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前に検知する仕組みを紹介する記事です。

Bridging_the_npm_CI_Gap_-_Slide_9.png

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を試す手順は次のとおりです。

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

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?