Claude Code 排查客户报错时的常见错误

客户报错一来，新手很容易进入“马上修”的状态。Claude Code 看起来能给很多建议，但如果你没有错误原文、没有复现路径、没有环境信息，工具只能帮你猜。排查报错时，最重要的不是速度，而是证据顺序。

这篇适合搭配 Claude Code 错误排查检查清单 和 Claude Code 交付说明检查清单 使用。

适合谁

适合已经接触客户 bug 小单，但经常修到一半发现信息不够的新手。你可能一开始以为是代码问题，后来发现是环境变量、依赖版本或客户配置。

也适合想把排查过程写成诊断服务的人。诊断要有证据，不是把 Claude Code 的猜测复制给客户。

不适合谁

不适合高风险生产环境排查。涉及真实数据、付款、账号权限、安全事件时，需要正式授权和复核。

也不适合客户拒绝补充信息，却要求你承诺修复结果的任务。信息不足时，只能做有限诊断。

具体步骤

错误一：只看截图，不要错误原文。截图经常缺上下文，最好让客户提供可复制的脱敏日志或终端输出。

错误二：不问环境。同一个错误在本地、测试、预览、生产可能原因不同。环境不清，结论就不稳。

错误三：不问复现步骤。没有复现路径，你不知道问题是否仍然存在，也不知道修完如何验收。

错误四：盲跑命令。看到建议就执行安装、格式化、部署或迁移命令，可能把问题扩大。

错误五：把敏感日志发给工具。日志里可能有账号、token、内部域名和真实数据。先脱敏，再分析。

错误六：把诊断写成修复。你只是定位了可能原因，就不要写“已经修好”。要写“当前判断”和“下一步需要什么”。

修正模板

目前信息还不足以确认修复。我需要先拿到：
- 错误原文
- 复现步骤
- 当前环境
- 最近变更
- 是否涉及敏感权限
确认后我可以先做诊断，再判断是否适合小范围修复。

这段话能把客户从“帮我修一下”带回可执行的信息收集。

怎么让 Claude Code 更有用

不要只发一句“这个报错怎么修”。更好的输入是：项目类型、错误原文、复现步骤、已运行命令、环境限制、不能访问的内容。工具拿到的是结构化上下文，输出才更接近可执行诊断。

如果 Claude Code 一次给出很多可能原因，先让它按低风险和高概率排序。你优先验证只读信息和本地检查，不先碰生产权限。

交付时怎么避免误解

如果只是诊断，交付说明要写“本次未进入完整修复”。如果已经修复，要写清验证方式和未覆盖范围。客户看到边界，后续沟通会稳很多。

不要把“可能是某个原因”写成确定结论。证据不足时，就写成待验证假设，并列出需要客户提供的材料。

改写示例

不推荐写：“Claude Code 看了，应该是依赖问题。”这句话没有说明证据，也没有下一步。

更稳的写法是：“当前错误出现在本地 build 阶段，已确认脚本存在，依赖安装完成；错误仍指向缺少测试环境变量。下一步需要客户提供脱敏后的测试环境配置名称，暂未进入生产部署。”

这段话不夸张，但证据更清楚。客户能看懂你排除了什么，也知道下一步需要自己配合什么。

复盘怎么做

每次排查结束后，记下自己一开始漏问了什么。是漏问环境，还是漏问最近变更，还是没有要求错误原文？把漏项加入下一次客户问题模板。

排查能力不是多跑几个命令就能变强，它来自每次错误后的复盘。Claude Code 可以辅助总结，但模板要由你自己维护。

风险提醒

不要为了显得专业而堆很多命令。排查不是命令数量比赛，关键是每一步都能解释。

不要隐藏不确定性。对新手来说，能清楚说明不确定在哪里，本身就是可靠表现。

免责声明

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

CTA：排查前用 错误排查检查清单 过一遍；需要客户说明时，用 /tools/proposal-generator 起草后人工复核。