Claude Code 错误排查检查清单

客户报错排查最怕信息少、动作多。你还没确认环境，就开始改代码；还没读错误原文，就连续运行命令；还没写范围，就承诺修复。用 Claude Code 前，先用清单把排查边界拉回来。

建议先读 用 Claude Code 排查客户报错时怎么做才稳，再搭配 Claude Code 常用命令检查清单 和 /templates 使用。

适合谁

适合接 bug 诊断、构建失败、页面报错、依赖冲突、配置缺失这类小单的新手。你需要先判断是否能低风险排查。

也适合已经收到报错截图，但不知道下一步该问什么的人。清单能帮你把截图变成结构化材料。

不适合谁

不适合客户不给错误原文、不提供复现步骤、也不允许测试，却要求保证结果的任务。

也不适合生产事故、真实数据、付款系统、账号权限和安全事件。这类排查需要更正式的授权和复核，不是普通小单流程。

具体步骤

1. 是否有错误原文？截图可以有，但要尽量拿到可复制文本。
2. 是否有复现步骤？页面、命令、按钮、输入、时间点要清楚。
3. 是否确认环境？本地、测试、预览、生产必须分开记录。
4. 是否知道最近变更？代码、依赖、配置、部署、账号权限是否变过。
5. 是否已脱敏？密钥、账号、真实数据、内部链接不能原样使用。
6. 是否先运行只读检查？查看文件、搜索关键词、看配置和 git 状态。
7. 是否需要本地验证？lint、test、build、dev server 要记录结果。
8. 是否避免高风险命令？部署、迁移、删除、重置、环境变量修改要单独授权。
9. 是否写清可能原因？不要只给一个猜测，要列优先级。
10. 是否写清客户下一步？需要补什么材料、如何验收、哪些没覆盖。

客户补充信息模板

为了判断这个报错是否适合我处理，请先提供：
- 错误原文或脱敏截图
- 复现步骤
- 当前运行环境
- 最近是否有代码、依赖、配置或部署变更
- 是否涉及密钥、真实数据、付款或管理员权限
- 你希望怎样验收修复结果

这段回复能阻止你在信息不足时直接报价完整修复。

排查记录模板

已确认事实：
已运行检查：
可能原因：
需要补充：
暂不处理：
建议下一步：

把记录写清楚后，Claude Code 可以帮你扩展原因和下一步，但最终结论仍要人工判断。

交付前检查

交付前确认三件事：第一，是否能说明错误来自哪里；第二，是否能说明你验证了什么；第三，是否能说明哪些内容没覆盖。三件事不清楚，就不要写“已修复”。

如果只是诊断，也要明确“本次未修改代码”或“本次只定位原因”。客户需要知道自己收到的是诊断结果还是修复结果。

判断结果分类

检查完以后，把结果分成三类。第一类是“可修复”：原因明确、范围小、可测试、权限低。第二类是“继续诊断”：信息还缺，但客户能补材料。第三类是“暂不承接”：需要生产权限、真实数据、数据库操作或正式审批。

这三类分类要写进客户回复。不要只在心里判断风险。客户看到分类后，更容易理解为什么你先做诊断，而不是马上承诺完整修复。

交付记录示例

本次诊断：
- 错误：构建时缺少测试配置
- 已确认：依赖安装正常，脚本存在
- 未确认：客户预览环境变量
- 未执行：生产部署、数据库、账号权限操作
- 下一步：请客户补充测试环境变量后复跑 build

这种记录既能保护边界，也能让客户知道你确实做了排查。

风险提醒

不要在客户没有授权的情况下访问后台或生产数据。错误排查不等于拥有全部访问权限。

不要把敏感日志放进第三方工具。先脱敏，再保留必要错误信息。

免责声明

本文仅供学习和项目流程参考，不构成安全、法律、财务或平台合规建议。Claude Code 功能、项目规则和客户验收要求可能变化，发布前需要人工复核。项目前请确认授权、脱敏、测试环境和交付边界。

CTA：排查前用 /templates 建一份错误记录；需要写客户回复时，用 /tools/proposal-generator 起草后人工复核。