Claude Code 修 bug 的 prompt 怎么写

Claude Code 修 bug 的效果，很大程度取决于你给它的上下文。新手常犯的错误，是只写“帮我修一下这个报错”，却不提供复现路径、错误原文、运行环境和预期结果。工具只能根据有限信息猜测，最后可能改错文件、扩大范围，或者给出无法验证的方案。

好的 bug prompt 不追求花哨，而是让问题可以被复现、定位、修改和验证。你可以搭配 Claude Code 新手使用场景检查清单、Bug 修复交付说明模板 和 /tools/error-explainer 使用。

适合谁

适合正在用 Claude Code 排查前端、Node、Next.js、部署、环境变量或小型脚本错误的新手。你不一定能完全理解错误原因，但要能把错误出现的条件描述清楚。

也适合接小型排错单的人。客户给你的信息越零散，你越需要先整理成 prompt，而不是直接让工具改代码。

不适合谁

不适合把客户密钥、后台截图、真实订单、隐私数据和完整账号信息直接贴进 prompt 的任务。bug prompt 只需要必要上下文，敏感信息要脱敏或替换成占位符。

也不适合没有复现条件的复杂问题。如果没有错误原文、没有触发步骤、没有项目环境，Claude Code 只能猜。此时应先做诊断，不要承诺修复。

具体步骤

第一步，写出触发路径。比如“打开 /pricing 页面，点击提交按钮后出现 500”，比“页面坏了”有用得多。

第二步，保留错误原文。状态码、终端报错、浏览器控制台、构建日志都可以放入 prompt，但要先检查是否包含密钥、邮箱、后台链接或客户数据。

第三步，写清运行环境。本地、预览环境、线上生产、Node 版本、框架、部署平台、最近改动，都可能影响判断。

第四步，写清预期结果和实际结果。工具需要知道“应该发生什么”和“现在发生什么”，才能判断修改方向。

第五步，要求先分析再修改。可以让 Claude Code 先列出可能原因、相关文件、最小修改方案和验证命令，再决定是否执行。

可复制 prompt

请先不要直接大范围修改。请根据下面信息定位可能原因，并提出最小修改方案：

问题现象：
复现步骤：
错误原文：
运行环境：
预期结果：
实际结果：
我已经尝试过：

要求：
1. 先说明可能相关文件。
2. 只建议最小范围修改。
3. 不要修改无关文件。
4. 修改后列出需要运行的检查命令。
5. 交付说明要包含未覆盖范围。

风险提醒

不要让 prompt 变成客户资料 dump。你提供的上下文越多，不代表越安全。能用错误码说明的，就不要贴完整后台；能用测试数据复现的，就不要贴真实用户数据。

不要让工具直接决定上线。修复建议必须经过 diff、测试和人工判断。prompt 只是开始，不是交付。

交付前记录

修完后把 prompt、改动、测试和交付说明串起来。客户问起时，你能说明：原问题是什么，工具如何辅助定位，你人工确认了哪些文件，运行了什么检查，还有哪些内容未覆盖。

这份记录也能帮你复盘 prompt 是否写得足够好。如果工具频繁猜错，通常说明 prompt 缺少复现步骤、环境或预期结果。

如果工具没有修好

如果 Claude Code 没有一次修好，不要继续让它无限尝试。先判断失败原因：错误信息是否完整，复现步骤是否准确，相关文件是否找对，检查命令是否真实运行。很多时候问题不在模型，而在输入缺少关键条件。

可以把交付降级成诊断说明：已根据现有信息排查到可能方向，但由于缺少测试环境、客户权限或完整日志，暂未确认最终修复。这样的说明比硬写“已经修好”更安全，也更符合项目边界。

Prompt 迭代习惯

每次排错后，保存一版最终有效 prompt。下次遇到类似问题时，不要从零写起，而是复用结构：复现、错误、环境、预期、实际、限制、验证。结构稳定后，工具输出会更稳定。

免责声明

本文仅供学习和排错流程参考，不构成安全、法律、财务或平台合规建议。Claude Code 功能和项目规则可能变化，发布前需要人工复核。处理客户项目时，请遵守授权、脱敏、最小权限和人工验收原则。

CTA：遇到 bug 时，先用 /tools/error-explainer 整理错误，再把本文 prompt 模板复制到项目笔记；需要交付说明时去 /templates 补齐测试证据。