Claude Code Build Error Triage Loop: Narrow the Cause in 15 Minutes

Split the build error before asking for a fix

When a Node, Astro, Vite, or Next.js build fails, the fastest-looking move is to paste the whole log into Claude Code and ask it to fix everything. That often creates a noisy patch: the first failing line, follow-up stack traces, package changes, and unrelated cleanup all get mixed together.

This article turns the bug report template, the review workflow checklist, and the verification receipt workflow into a practical build-error triage loop. The goal is not a heroic one-shot repair. The goal is to narrow the cause in 15 minutes, apply the smallest fix, and leave proof that a reviewer can trust.

The useful mental model is a harness: a small operating frame around the agent. Claude Code can reason over code, but you still decide which log matters, which hypothesis is allowed, and which command proves the fix. That harness is what keeps a build-fix session from becoming a broad refactor.

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]

The 15-minute loop

Use three five-minute blocks. The first block captures evidence without editing files: git status, the failing build command, the first failing line, and the smallest set of related files. The second block chooses one hypothesis: dependency, import path, frontmatter, data shape, permission, network, or test expectation drift.

Only the final block allows a code or configuration change. After that change, run the command that failed and record the proof. For a content or revenue site, proof is not only a green build. Check the article URL, h1, canonical behavior, hero image, CTA links, product path, and training path. A build that passes while breaking conversion is still a production problem.

Masa’s working note for this loop is deliberately short: cause, change, evidence. A reviewer should be able to see why the hypothesis was chosen, what changed, and which command or URL proved it. Asking Claude Code to return those three lines makes the review smaller and gives the next incident a reusable starting point.

Capture evidence in a fixed order

Run the same commands in the same order each time. On macOS, Linux, or WSL, this shell version captures the build log and prints likely failure lines without losing the original exit code.

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

On Windows PowerShell, call npm.cmd explicitly so the command matches common CI and terminal behavior more closely.

$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

The first run does not need to pass. Its job is to preserve the first useful failure. The last stack trace can be downstream noise; the first error line is usually closer to the root cause.

Classify the first failure with Node

Save the script below as scripts/triage-build-log.mjs, then run node scripts/triage-build-log.mjs build.log. It does not repair anything. It turns a large log into one bucket and one diagnostic direction.

#!/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));

This classifier is intentionally small. Its purpose is to change the prompt from “fix the build” to “prove or disprove this bucket before editing files.” That shift prevents broad dependency upgrades, defensive null checks, and cleanup patches from hiding the actual failure.

Use official docs as boundaries

Keep official documentation links tied to the layer that failed. Claude Code connection, authentication, usage limit, and runtime messages belong in the Claude Code Error reference. If settings, hooks, MCP servers, or CLAUDE.md appear not to load, use Debug your configuration.

For Astro content sites, frontmatter and content collection failures should be checked against Astro Content Collections. For Node runtime codes such as ERR_MODULE_NOT_FOUND, use the Node.js Errors reference. Separating those sources keeps the diagnosis honest: Claude Code may be healthy while the app build is broken, or the app may be fine while the agent session cannot reach the API.

Do not use official links as decoration. Use them to justify the smallest repair. If Astro validates frontmatter through a collection schema, fixing one missing field is a clearer patch than adding null guards throughout the rendering layer.

First move by error shape

Log shape	First suspicion	First move
Cannot find module	import path, generated file, missing dependency	Check file existence and path before adding a package
ERR_MODULE_NOT_FOUND	ESM/CJS mismatch, extension, package exports	Compare Node error type with package configuration
undefined is not	data shape, frontmatter, API response	Print one real record before adding null checks
Expected ... received	spec change, fixture, snapshot drift	Classify as intended change or regression first
permission denied	sandbox, CI user, write path	Check working directory, user, and allowed write target
only Build failed	upstream first error	Extract the first error line, not the final stack trace

This table is not meant to replace reading. It prevents the first repair from being random. In an Astro article site, undefined is not an object may mean a missing heroImage, pubDate, or lang field. A wide null guard could make the build pass while hiding a content quality issue.

Copyable Claude Code prompt

Use this prompt after you have a log and a bucket. It asks Claude Code to reason before editing.

Read this failing build log.
Do not suggest broad refactors.
Do not edit files yet.

Return:
1. the first failing line
2. one most likely cause
3. the smallest diagnostic command for that cause
4. the smallest code or config fix you would allow
5. the proof command after the fix
6. a three-line PR receipt: cause, change, evidence

When other people are working in the same repository, add the scope explicitly: “Only inspect and edit this slug”, “Do not touch reports”, “Do not revert unrelated changes”, and “Preserve frontmatter identity fields.” That instruction matters more than model quality when the working tree is busy.

Four practical use cases

The first use case is an Astro multilingual content site. The build can fail because one locale has invalid frontmatter, an unclosed MDX fence, a missing hero image, or a link that becomes invalid after route generation. Ask Claude Code to inspect only the target slug, compare the ten locale files, and validate YAML and code fences before proposing edits.

The second use case is a Node CLI or package import failure. Cannot find module does not automatically mean “install a dependency.” It can be a typo, a missing generated file, a package exports rule, or an ESM/CJS mismatch. Run node -p "require.resolve('package-name')" or a direct file-existence check before changing dependencies.

The third use case is CI-only failure. Local builds may pass while CI fails because of permissions, case-sensitive paths, a different Node version, a missing secret, or a proxy. Before changing application code, ask Claude Code to list the CI operating system, working directory, Node version, environment variable names, and write targets.

The fourth use case is test expectation drift. Expected ... received is easy to silence by updating snapshots, but that can approve a regression. For CTA links, pricing copy, Gumroad links, training forms, or article metadata, decide whether the change is intended before accepting a fixture update.

Concrete pitfalls

Pitfall one is reading only the end of the log. The final stack trace may be a consequence, not a cause. Save the first failure line and the 30 lines before it.

Pitfall two is upgrading dependencies too early. Package changes touch lockfiles, caches, CI behavior, and sometimes runtime compatibility. If an import path typo caused the failure, a dependency upgrade makes the patch harder to review.

Pitfall three is stopping at a green build. A public site also needs the revenue path checked. Confirm /en/products/, /en/training/, free PDF forms, article h1, and canonical behavior when the fix touches content or routing.

Pitfall four is allowing opportunistic cleanup. A build-fix PR should keep the hypothesis visible. If you mix formatting, refactors, dependency upgrades, and content rewrites, nobody can tell which change actually fixed the build.

Product and training CTA

If you want reusable prompts, checklists, and setup material for this workflow, start with the ClaudeCodeLab products. If your team needs CI gates, CLAUDE.md, permission rules, review receipts, and production verification designed around a real repository, use Claude Code training and consultation.

Related follow-up reading: permission audit checklist for agent boundaries and CI/CD setup for build gates. The free PDF path is useful for individual command fluency, but team adoption usually needs a shared prompt, a shared proof format, and a clear owner for approvals.

What changed after testing this loop

In practice, this loop makes the patch smaller. Instead of asking Claude Code to absorb the whole log and repair everything, the session starts with one failure line, one hypothesis, and one proof command. That was enough to separate missing frontmatter, generated-file gaps, import-path typos, and CI permission problems in real article and Node workflows. The best part is not the first fix; it is the reusable receipt left for the next failure.