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

先分类，再让 Claude Code 修复

Node 或 Astro 构建失败时，很多人会把完整日志贴给 Claude Code，让它一次性修好。这样常常把第一条失败、原因候选和无关整理混在一起。

这个循环把 bug report 模板 和 评审流程清单 用到构建失败上。目标是在15分钟内缩小原因、给出最小诊断，并留下修复后的证据。

按固定顺序取证

每次都用同样顺序：状态、build，必要时测试。

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

第一次运行不一定要成功。真正重要的是保存第一条失败行。它通常比最后的堆栈噪音更接近根因。

把日志分成四类

分类不需要完美。依赖或 import、运行时 shape 不匹配、测试期望漂移、权限边界，已经覆盖很多日常失败。

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";
}

有了分类，提示词就会变得具体。你可以要求最小诊断，而不是笼统修复。

可复制的排查提示词

请阅读这个失败的构建日志。
不要建议大范围重构。
请返回:
1. 第一条失败行
2. 最可能的原因
3. 最小诊断命令
4. 最小代码或配置修复
5. 修复后的验证命令

关键是禁止大范围重构。构建错误排查最好一次只处理一个假设和一个证明命令。

失败例：太早升级依赖

看到 “Cannot find module” 就安装依赖，看到 “undefined” 就到处加 null check，都是常见错误。如果真正原因是 import path、frontmatter 或生成文件，修改会变得更乱。

对公开内容站来说，只看本地 build 成功也不够。收入导线需要公开 URL、正确 h1、canonical、CTA 和 Gumroad 链接都正常。

下一步导线

需要命令提醒时先领取 免费 cheatsheet。想马上使用调试和评审提示词时购买 50 Prompt Templates。如果要整理 CI/CD、部署闸门和生产验证，请结合 Setup Guide 与 咨询。