Claude Codeビルドエラー切り分けループ: 15分で原因候補を絞る

ビルドエラーは「修正」より先に切り分ける

Node、Astro、Vite、Next.js のビルドが落ちると、ログ全文を Claude Code に貼って「直して」と頼みたくなります。しかしそれだけだと、最初に壊れた行、後続のノイズ、ついでのリファクタが混ざります。結果として、ビルドは通っても原因の説明が弱くなり、レビューで差し戻されます。

この記事では、バグ報告テンプレート、レビュー運用チェックリスト、検証レシート運用を、公開前のビルド失敗に当てはめます。ゴールは「1回で全部直す」ことではありません。15分で原因候補を1つまで絞り、最小修正と検証ログを残すことです。

この考え方は、harness という言葉で説明すると分かりやすいです。harness は、エージェントの足場です。Claude Code の賢さだけに任せるのではなく、どのログを見るか、どの仮説を許すか、どのコマンドで証明するかを先に固定します。

flowchart LR
  A[State] --> B[Build log]
  B --> C[First failing line]
  C --> D[One hypothesis]
  D --> E[Small fix]
  E --> F[Proof command]
  F --> G[Receipt]

15分ループの全体像

15分を3つに分けます。最初の5分は証拠取りです。まだファイルを編集せず、git status、失敗した build、最初の失敗行、関連ファイルだけを集めます。次の5分は仮説を1つに絞ります。依存関係、import path、frontmatter、型の形、権限、ネットワークのどれを疑うのかを決めます。

最後の5分で初めて修正します。修正後は、失敗したコマンドだけでなく、関連するページ、CTA、公開前チェックも見ます。特に ClaudeCodeLab のようなコンテンツサイトでは、build 成功だけでは足りません。記事の h1、canonical、heroImage、商品リンク、研修リンクが壊れていないかまで確認して、収益導線を守ります。

Masa の運用では、PRコメントや作業メモに「原因」「変更」「証拠」の3行を必ず残します。長い説明よりも、次に同じエラーを見た人が最初に何を確認すればよいかが重要です。Claude Code にも、この3行を返すように頼むと、レビューがかなり短くなります。

まず同じ順番で証拠を取る

最初に実行するコマンドの順番を固定します。毎回違う順番で試すと、ログの比較ができません。macOS、Linux、WSL なら次の shell 例をそのまま使えます。

git status --short
npm run build 2>&1 | tee build.log
status=${PIPESTATUS[0]}
if [ "$status" -ne 0 ]; then
  grep -Ein "error|failed|ERR_|Cannot|TypeError" build.log | head -n 20
  exit "$status"
fi
npm test -- --runInBand

Windows PowerShell では、npm の解決が shell によって変わることがあります。CI と同じ挙動に寄せるため、ここでは npm.cmd を明示します。

$ErrorActionPreference = "Continue"
git status --short
npm.cmd run build *> build.log
$buildExit = $LASTEXITCODE

if ($buildExit -ne 0) {
  Select-String -Path build.log -Pattern "error|failed|ERR_|Cannot|TypeError" |
    Select-Object -First 20
  exit $buildExit
}

npm.cmd test -- --runInBand

ここで大事なのは、成功させることではなく、最初に失敗した場所を保存することです。ログの末尾は、上流の失敗に引きずられた stack trace になりがちです。Claude Code へ渡す前に、最初の error だけを抜き出すと、余計な修正を減らせます。

Nodeで最初の失敗行を分類する

次のスクリプトは、保存した build.log から最初の失敗候補を取り出し、依存関係、実行時の未定義、テスト期待値、権限、Astro frontmatter のどれに近いかを分類します。scripts/triage-build-log.mjs として保存し、node scripts/triage-build-log.mjs build.log で動かせます。

#!/usr/bin/env node
import { readFileSync } from "node:fs";

const logPath = process.argv[2];

if (!logPath) {
  console.error("Usage: node scripts/triage-build-log.mjs build.log");
  process.exit(1);
}

const rules = [
  { name: "dependency or import path", regex: /Cannot find module|ERR_MODULE_NOT_FOUND|Cannot resolve/i },
  { name: "runtime null or shape mismatch", regex: /TypeError:.*undefined|undefined is not|Cannot read/i },
  { name: "test expectation drift", regex: /Expected.*received|AssertionError|Snapshot/i },
  { name: "permission or sandbox boundary", regex: /EACCES|EPERM|permission denied/i },
  { name: "Astro content or frontmatter", regex: /frontmatter|content collection|InvalidContentEntry|MDX/i },
];

const lines = readFileSync(logPath, "utf8").split(/\r?\n/);
const firstFailure = lines.find((line) => /error|failed|ERR_|Cannot|TypeError/i.test(line));
const matchedRule = rules.find((rule) => firstFailure && rule.regex.test(firstFailure));

console.log(JSON.stringify({
  firstFailure: firstFailure || "No obvious failure line found",
  bucket: matchedRule ? matchedRule.name : "needs manual reading",
  nextDiagnostic: matchedRule
    ? "Run one command that proves or disproves this bucket before editing files."
    : "Read the 30 lines before the first failure and classify manually.",
}, null, 2));

この分類は完璧でなくて構いません。目的は自動修正ではなく、Claude Code への依頼を狭くすることです。「依存関係かもしれない」なら、package.json と import path の確認から始めます。「Astro content or frontmatter」なら、記事本文の修正より先に site/src/content.config.ts と該当 frontmatter を見ます。

公式ドキュメントで確認する範囲を固定する

ビルドエラー対応では、公式ドキュメントを見る範囲も先に決めます。Claude Code 自体の接続、認証、制限、実行時エラーは Claude Code Error reference を見ます。CLAUDE.md、settings、hooks、MCP が読み込まれていない疑いがあるなら Debug your configuration を見ます。

Astro の記事サイトなら、frontmatter や content collection のエラーは Astro Content Collections が基準です。ERR_MODULE_NOT_FOUND のような Node 側のエラーコードは Node.js Errors を確認します。ここを混ぜると、Claude Code の問題なのか、アプリの build 問題なのか、Node の実行時問題なのかが曖昧になります。

公式リンクは、修正コードの根拠として使います。たとえば「Astro の schema が frontmatter を検証するから、記事ごとに heroImage を足す」と説明できればレビューしやすいです。逆に、公式根拠なしに依存を上げたり、設定を消したりする提案は、いったん止めます。

エラー種別ごとの最初の一手

ログを見た瞬間に修正へ進む前に、次の表で最初の一手を決めます。Claude Code への依頼も、この分類に合わせます。

ログの見え方	まず疑うこと	最初の一手
Cannot find module	import path、生成ファイル、依存漏れ	依存追加より先にファイル存在とパスを確認
ERR_MODULE_NOT_FOUND	ESM/CJS混在、拡張子、package exports	Node公式のエラー種別と package 設定を確認
undefined is not	data shape、frontmatter、API応答	実データを1件だけ出力して型と値を見る
Expected ... received	仕様変更、fixture、snapshot	仕様変更か退行かを先に分類
permission denied	sandbox、CI権限、実行場所	書き込み先と実行ユーザーを確認
Build failed だけ	上流の最初の失敗行	ログ末尾ではなく最初の error を抜く

たとえば Astro の記事サイトで undefined is not an object が出た場合、すぐに null check を足すのは早すぎます。heroImage、pubDate、lang のどれかが欠けているだけかもしれません。ここで「全記事を安全にする大きな修正」を頼むと、原因から遠い差分が増えます。

Claude Codeへ渡すプロンプト

ログを分類したら、Claude Code には次の形で渡します。広いリファクタを禁止し、診断コマンドと証拠を必ず返してもらいます。

この失敗したビルドログを読んでください。
広いリファクタは提案しないでください。
まだファイルを編集しないでください。

返してほしい内容:
1. 最初に失敗した行
2. もっともありそうな原因を1つ
3. その原因を確認する最小の診断コマンド
4. 許可する最小のコードまたは設定修正
5. 修正後の検証コマンド
6. PRコメントに残す「原因・変更・証拠」の3行

このプロンプトの強い点は、Claude Code に「作業の順番」を渡していることです。原因が曖昧なまま修正へ進ませません。特に複数人が同じリポジトリを触っているときは、関係ない slug、生成レポート、他人の差分を触らない条件もここに追加します。

3つ以上の実務ユースケース

1つ目は、Astro の多言語記事サイトです。content.config.ts の schema、10言語の frontmatter、OGP画像、内部リンクが揃っていないと build が落ちます。この場合、Claude Code には「対象 slug の10ファイルだけ読む」「updatedDate 以外の identity field は変えない」「code fence と YAML を検証する」と依頼します。

2つ目は、Node CLI や npm package の import 失敗です。Cannot find module は依存不足とは限りません。拡張子なし import、type: module、exports、生成ファイル未作成でも起きます。最初に node -p "require.resolve('package-name')" や Test-Path で存在確認をしてから、依存追加を判断します。

3つ目は、CI だけで落ちる build です。ローカルでは通るのに CI で permission denied、環境変数不足、proxy、case-sensitive path の問題が出ることがあります。この場合は、Claude Code にコード変更を頼む前に、CI の working directory、Node バージョン、OS、secret 名、書き込み先を並べてもらいます。

4つ目は、テスト期待値のズレです。Expected ... received を見て snapshot を更新するのは簡単ですが、仕様変更か退行かを先に分ける必要があります。UI の文言、CTA の href、Gumroad リンク、研修フォームの遷移先が変わったなら、仕様として受け入れる前にビジネス導線の持ち主に確認します。

具体的な落とし穴

一番多い落とし穴は、ログの最後だけを見ることです。最後の stack trace は、最初の import 失敗や frontmatter 失敗の結果として出ているだけかもしれません。先頭の error を保存せずに修正すると、症状だけを隠します。

次に危ないのは、依存をすぐ上げることです。package update は lockfile、CI cache、runtime、Node バージョンまで波及します。import path の typo で済む問題に対して依存を上げると、差分が大きくなり、レビューの焦点がぼやけます。

3つ目は、build 成功だけで終わることです。公開サイトでは、CTA が押せるか、/products/ と /training/ の導線が残っているか、内部リンクが404になっていないかも検証対象です。特に広告審査や教材販売では、記事本文の品質と収益導線の品質を分けて考えないほうが安全です。

4つ目は、Claude Code に「ついでの整理」を許すことです。ビルドエラー対応のPRで大きなリファクタを混ぜると、原因が正しかったのか、たまたま通ったのかが分からなくなります。切り分けのPRでは、最小修正と検証ログを優先します。

収益導線まで検証する

ビルドエラーを直したあと、記事として公開するなら CTA も確認します。個人で型を増やしたい読者には 商品一覧 が自然です。チームで CI、権限、レビュー、公開確認まで整えたい読者には Claude Code研修・導入相談 が合います。

さらに周辺記事として、権限監査チェックリスト と CI/CDセットアップ も一緒に確認すると、build エラーだけでなく、再発防止のルールまで作れます。無料で始めるなら 無料チートシート で日常コマンドを固定し、繰り返し使うプロンプトや設定例は商品ページへ進むのが現実的です。

実際に試した結果、ログ全文を渡して一気に直すより、最初の失敗行、仮説1つ、検証コマンド1つに絞ったほうが差分は小さくなりました。以前は undefined を見て広めの null check を足していましたが、frontmatter の欠落、生成ファイル漏れ、import path の typo に早く戻れるようになりました。最後に「原因・変更・証拠」を残すだけで、次回の Claude Code への依頼も短くなります。