Claude Code 构建错误排查循环：15分钟缩小原因范围

先排查，再让 Claude Code 修改

Node、Astro、Vite 或 Next.js 构建失败时，最容易的做法是把完整日志贴给 Claude Code，然后说“帮我修好”。问题是，完整日志里通常混着第一条失败、后续堆栈、包管理噪音和顺手重构。构建也许会通过，但原因说明很弱，review 时很难判断哪一处修改真正有效。

这个流程把 bug report 模板、review workflow checklist 和 verification receipt workflow 用到构建错误上。目标不是一次性大修，而是在15分钟内把原因缩小到一个假设，做最小修改，并留下可复查的证据。

harness 可以理解成“给 agent 搭的工作脚手架”。Claude Code 负责读代码和推理，但人要先规定看哪段日志、允许哪种假设、用哪条命令证明。这个脚手架能防止一次 build 修复变成大范围整理。

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分钟分成三个五分钟。第一个五分钟只取证，不改文件：git status、失败的 build 命令、第一条失败行、最小相关文件。第二个五分钟只选一个假设：依赖、import path、frontmatter、数据 shape、权限、网络或测试期望漂移。

最后五分钟才允许修改代码或配置。修改后不仅要跑失败命令，还要检查相关页面和 CTA。对内容站来说，绿色 build 不等于发布安全。h1、canonical、heroImage、产品链接和培训咨询链接都要看，收入路径不能因为修复 build 被破坏。

Masa 的作业记录只保留三行：原因、修改、证据。reviewer 不需要读长篇解释，但必须知道为什么选这个假设、改了什么、用什么命令或 URL 证明。让 Claude Code 最后也输出这三行，下一次遇到同类错误时可以直接复用。

按固定顺序收集证据

每次都用相同顺序执行命令。macOS、Linux 或 WSL 可以直接使用这个 shell 例子，它会保存日志并保留原始 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

Windows PowerShell 下建议显式调用 npm.cmd，避免不同 shell 对 npm 的解析不一致。

$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

第一次运行不需要成功。它的任务是保存最有用的第一条失败。日志末尾常常只是后续噪音，真正靠近根因的是最早的 error。

用 Node 分类第一条失败

把下面脚本保存为 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));

这个分类不用完美。它的作用是把提示词从“修复 build”改成“先证明或排除这个分类”。这样可以减少无意义的依赖升级、大范围 null check 和顺手清理。

用官方文档划清边界

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 运行时问题混为一谈。

按错误形态决定第一步

日志形态	先怀疑什么	第一动作
Cannot find module	import path、生成文件、依赖缺失	先确认文件和路径，再决定是否加依赖
ERR_MODULE_NOT_FOUND	ESM/CJS、扩展名、package exports	对照 Node 错误类型和 package 设置
undefined is not	data shape、frontmatter、API 响应	输出一条真实数据，不要先加 null check
Expected ... received	规格变化、fixture、snapshot	先判断是预期变化还是回归
permission denied	sandbox、CI 用户、写入路径	确认 working directory、用户和写入目标
只有 Build failed	上游第一条 error	抽取最早 error，而不是看最后堆栈

比如 Astro 文章站出现 undefined is not an object，真正原因可能只是某个语言文件缺少 heroImage、pubDate 或 lang。如果直接让 Claude Code 做全局防御式修改，构建可能通过，但内容质量问题被藏起来。

可复制的 Claude Code 提示词

请阅读这个失败的 build log。
不要建议大范围重构。
现在还不要编辑文件。

请返回:
1. 第一条失败行
2. 最可能的原因，只选一个
3. 验证这个原因的最小诊断命令
4. 允许的最小代码或配置修改
5. 修改后的验证命令
6. PR 评论用三行: 原因、修改、证据

多人同时编辑仓库时，要把范围写得更具体：只检查这个 slug，不要修改 reports，不要回退无关变更，保留 frontmatter identity fields。这些约束比“让模型更聪明”更重要。

四个实务用例

第一个用例是 Astro 多语言内容站。一个 locale 的 frontmatter 错误、未关闭的 MDX code fence、缺少 OGP 图片、内部链接路径错误，都可能让 build 失败。此时要求 Claude Code 只看目标 slug 的10个文件，并验证 YAML、code fence 和 body 长度。

第二个用例是 Node CLI 或 package 的 import 失败。Cannot find module 不一定是依赖没装，也可能是拼写错误、生成文件没跑、exports 限制或 ESM/CJS 混用。先用 node -p "require.resolve('package-name')" 或文件存在检查，再决定是否改依赖。

第三个用例是只在 CI 失败。常见原因包括权限、大小写敏感路径、Node 版本不同、secret 名错误、proxy 设置缺失。修改应用代码前，先让 Claude Code 列出 CI OS、working directory、Node 版本、环境变量名和写入路径。

第四个用例是测试期望漂移。Expected ... received 很容易通过更新 snapshot 解决，但可能批准了回归。CTA 链接、价格文案、Gumroad 链接、培训表单、文章 metadata 变更时，要先确认这是预期变化。

常见落坑

第一个坑是只看日志末尾。最后的 stack trace 可能只是结果，不是原因。保存第一条失败行和它前面的30行。

第二个坑是太早升级依赖。package 变更会影响 lockfile、CI cache 和运行时兼容性。如果只是 import path typo，升级依赖会让 review 变难。

第三个坑是 build 通过就结束。公开站还要确认 /zh/products/、/zh/training/、免费 PDF 表单、h1 和 canonical。修复 build 不应破坏转化路径。

第四个坑是允许顺手整理。build-fix PR 应该让假设很清楚。把格式化、重构、依赖升级和内容改写混在一起，会让人无法判断哪一处真正修好了问题。

产品和咨询导线

如果你想把这些提示词、检查清单和设置材料固定下来，可以看 ClaudeCodeLab 产品。如果团队需要把 CI gate、CLAUDE.md、权限规则、review receipt 和生产验证落到真实 repository，建议从 Claude Code 培训与咨询 开始。

延伸阅读可以看 权限审计清单 和 CI/CD 设置。个人练习可以先用免费 PDF 固定日常命令，团队导入则需要共享 prompt、共享证据格式和明确的审批责任。

实测后的变化

实际使用这个循环后，差分会变小。与其让 Claude Code 吞下整段日志并尝试一次性修复，不如先给它一条失败行、一个假设和一条验证命令。这个方法能更快区分 frontmatter 缺失、生成文件遗漏、import path 拼写错误和 CI 权限问题。真正有价值的不是第一次修好，而是留下下一次也能复用的证据。