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

ビルドエラーは「全文を読む」より先に分ける

NodeやAstroのビルドが落ちると、Claude Codeにログ全文を貼りたくなります。しかし最初から全部を直させると、最初の1行、原因候補、検証コマンドが混ざり、余計な修正が増えます。

この記事は バグ報告テンプレート と レビュー運用チェックリスト を実務のビルド失敗に当てはめたものです。15分で原因候補を狭め、修正後の証拠まで残します。

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

毎回違う順番でコマンドを打つと、Claude Codeも人間も迷います。最初は状態、build、必要ならtestの順に固定します。

git status --short
npm.cmd run build
npm.cmd run test -- --runInBand

重要なのは、成功させることではなく、最初に失敗した場所を保存することです。ビルドログの最後ではなく、最初の失敗行が原因に近いことが多いです。

ログを4種類に分ける

分類は完璧でなくて構いません。依存関係、実行時の未定義、テスト期待値、権限の4つに分かれるだけで、次の診断がかなり短くなります。

const patterns = [
  [/Cannot find module|ERR_MODULE_NOT_FOUND/i, "dependency or import path"],
  [/TypeError:.*undefined|undefined is not/i, "runtime null or shape mismatch"],
  [/Expected.*received|AssertionError/i, "test expectation drift"],
  [/EACCES|permission denied/i, "permission or sandbox boundary"],
];

export function classifyBuildLine(line) {
  const hit = patterns.find(([regex]) => regex.test(line));
  return hit ? hit[1] : "needs manual reading";
}

この程度の分類でも、Claude Codeへの依頼が変わります。「直して」ではなく「この分類で最小診断を出して」と言えるからです。

コピペできる依頼

この失敗したビルドログを読んでください。
広いリファクタは提案しないでください。
返してほしい内容:
1. 最初に失敗した行
2. もっともありそうな原因
3. 最小の診断コマンド
4. 最小のコードまたは設定修正
5. 修正後の検証コマンド

この依頼の良い点は、広いリファクタを禁止していることです。ビルドエラー対応では、原因候補を1つずつ潰す方が速く、レビューもしやすくなります。

失敗例: エラーを見た瞬間に依存を上げる

よくある失敗は、“Cannot find module” を見てすぐ依存を追加したり、“undefined” を見て広いnullチェックを入れたりすることです。どちらも本当の原因が import path や frontmatter 欠落なら、余計な変更になります。

また、公開サイトでは build 成功だけで終わるのも危険です。公開URL、正しいh1、canonical、CTA、Gumroadリンクまで確認して初めて収益導線が守られます。

15分を3つのブロックに分ける

ビルドエラー対応で一番もったいないのは、調査、修正、検証を同時に進めることです。15分しか使わない前提なら、時間を3つに区切ると迷いが減ります。

最初の5分は証拠取りです。ここでは何も直しません。git status、失敗コマンド、最初に落ちた行、関連ファイルだけを集めます。Claude Codeには「まだ修正しない」と明示します。

次の5分は仮説を1つに絞ります。依存関係なのか、frontmatterなのか、型の形なのか、権限なのかを選びます。候補が2つ以上残るなら、コード変更ではなく診断コマンドを1つだけ追加します。

最後の5分で最小修正と検証をします。ここで初めてファイルを編集します。修正後は、失敗したbuildだけでなく、該当ページの公開URL、h1、canonical、CTAも見るのが理想です。特にコンテンツサイトでは、build成功と公開反映は別物です。

このビルド失敗を15分で切り分けます。
今は修正しないで、次だけ返してください。
- 最初の5分で集める証拠
- 次の5分で確認する仮説
- 最後の5分で許可する最小修正
- build以外に見るべき公開URLの証拠

この型は、AstroだけでなくNext.js、Vite、Node CLIでも使えます。対象が違っても、最初に証拠、次に仮説、最後に最小修正という順番は変わりません。

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

ログを見た瞬間に修正へ進む前に、エラー種別ごとの「最初の一手」を決めておきます。これだけで、Claude Codeに余計な変更をさせる確率が下がります。

ログの見え方	まず疑うこと	最初の一手
Cannot find module	import path、生成ファイル、依存漏れ	依存追加より先にファイル存在とパスを確認
undefined is not	data shape、frontmatter、API応答	型や実データを1件だけ出力して確認
Expected ... received	テスト期待値、仕様変更、fixture	仕様変更か退行かを先に分類
permission denied	sandbox、実行権限、パス	実行してよい場所とコマンドを確認
Build failed だけ	上流の最初の失敗行	ログ末尾ではなく最初のerrorを抜き出す

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

収益導線では、ビルドエラー対応にも優先順位があります。無料PDFフォーム、Gumroadリンク、導入相談フォームに関わるエラーは先に直します。見た目だけの崩れでも、CTAが押せないなら収益に直結します。逆に、古い記事の細かい表記ゆれは、公開ブロッカーとは分けて後で直せます。

最後に、ログを保存する場所も決めておきます。pull request、作業メモ、またはチケットのどれか1つに、最初の失敗行、採用した仮説、実行した検証コマンドを書きます。後から同じエラーが出たとき、Claude Codeにそのメモを渡すだけで再調査の時間を短縮できます。

私の運用では、修正後のコメントに「原因」「変更」「証拠」の3行を必ず残します。長い説明よりも、次に同じ失敗を見た人が最初に何を確認すればよいかが分かることを優先します。これが残っていると、次回のClaude Codeへの依頼も短くなります。ログは捨てず、短い再利用資産として扱うのがコツです。特に公開直前のbuild失敗では、この3行が次の復旧速度を決めます。面倒でも最後に1分だけ残す価値があります。運用の再現性が上がります。チームでも確実に効きます。

この記事で紹介した内容を実際に試した結果

このループを使うと、修正量が小さくなります。以前はログの最後に出たエラーを見て広めに直していましたが、最初の失敗行を保存するだけで、import path、日付frontmatter、生成ファイル漏れのような原因に早くたどり着けました。

一方で、Claude Codeにログ全文だけ渡す運用では失敗しました。出力はそれらしく見えますが、どの仮説を検証したのかが残りません。レビューする人は、修正コードよりも「なぜそれが原因だと言えるのか」を見ます。だからこそ、プロンプトの返答に診断コマンドと証拠を含める必要があります。

次の導線

ログの読み方に不安があるなら 無料チートシート で基本コマンドを確認してください。レビューやデバッグ依頼をすぐ使いたいなら 50 Prompt Templates が役立ちます。チームのCI/CDや本番検証フローまで整えるなら Setup Guide と 導入相談 を使い分けてください。