Claude Code 自动化排查流程规范

📖 Claude Code 自动化排查流程规范

本规范旨在利用 Claude Code 的自主推理与工具调用能力（Agentic Loop），实现对中间件 SDK（如 IoT 配网/绑定）复杂链路故障的秒级诊断。

🛠️ 第一步：知识库建设 (经验沉淀)

研发同学在排查完一个新 Bug 后，必须将逻辑沉淀到项目根目录下的 .claude/troubleshooting/（或自定义目录）中。

1. 编写状态机地图 (必选)

创建一个 iot_provision_binding_SOP.md，定义功能的"里程碑"：

Markdown

复制代码

# 状态机里程碑定义
- 阶段 1 [配网]: 关键字 `[WIFI-RECEIVE]`, `[WIFI-CONN]`
- 阶段 2 [连云]: 关键字 `[MQTT-CONN]`, `[ONLINE]`
- 阶段 *   将过去排查出的疑难杂症（如：特殊路由器兼容性、Token 提前失效等）直接总结成简短的 Markdown3 [绑定]: 关键字 `[BIND-REQ]`, `[BIND-RESP]`

# 判定逻辑
- 必须按 1->2->3 。

---

## 阶段二：环境就绪 (Workspace Setup)

无需编写任何排查代码，只需将证据准备好：

*顺序检查。
- 若前一阶段未完成，后一阶段的报错均为"次生灾害"，忽略。

2. 编写专家锦囊 (可选)

记录高频坑位。例如 auth_tips.md:

注意：如果返回 40015，优先检查手机端与设备的时间偏移，而非代码 Bug。

🚀 第二步：环境准备

确保你的开发环境下已安装并认证 Claude Code：

安装： npm install -g @anthropic-ai/claude-code
认证： claude auth login
日志准备： 将 GB 级的原始日志文件放置在本地目录（例如 ./logs/target.log）。

🎯 第三步：下达"侦探型"指令

在终端进入项目根目录，运行 claude 启动交互界面，然后输入以下 "黄金提示词"：

💡 黄金提示词模板：

我现在遇到了一个【配网绑定失败】的故障，请作为 SDK 专家进行自主诊断。

1. 资料来源：

参考 ./.claude/troubleshooting/ 下的所有 SOP 和经验文档。

原始日志位于 ./logs/target.log (该文件较大，请使用 grep 或 sed 工具按需流式检索)。

2. 排查策略：【里程碑断点定位法】

不要盲目全量读取日志。

请先根据 SOP 定义的三个阶段，依次检索里程碑关键字。

锁定"断裂阶段"后，提取该阶段前后的上下文（TraceID/线程名）进行深度分析。

如果思路 A 没找到证据，请【换思路重试】。

3. 成功标准：

必须在当前目录生成一个 diagnosis_report.html。

报告需包含：断裂阶段、证据日志片段、根本原因分析、以及给出的修复 Patch 或技术支持建议。

现在开始排查，完成后告诉我。

🔍 第四步：观察 Claude Code 的自主行为

此时，你会看到 Claude Code 自动执行以下循环，无需你干预：

读取文件： 它会先读你的 SOP.md。
调用终端工具： 它会自己拼接命令，如 grep -E "WIFI-CONN|MQTT-CONN|BIND-RESP" ./logs/target.log。
反思与重试： 如果没搜到，它会想："是不是日志格式变了？"然后它会用 head 读几行日志看看格式，再重新搜。
生成交付物： 最终它会调用文件写入工具，把分析好的 HTML 报告写到本地。

📈 进阶：如何持续优化？

当研发大牛发现 AI 漏掉了某个特殊 case 时：

不要去改代码。
只需要 在 iot_provision_binding_SOP.md 里加一行：* 注意：若出现 [ERROR] -105，代表天线干扰，提示用户远离微波炉。
下次排查，AI 自动就变聪明了。

💡 提示： 这种方式的本质是：研发同学编写"规则"，AI 负责"体力活（翻日志）"和"初级推理"。 真正的研发大牛只需要审核最后那个 report.html 即可。