系统化调试方法论

调试 AI Agent 开发规范 最佳实践

🔍 调试方法论

系统化调试方法论 — 适用于 AI Agent 和开发者的通用调试规范。

从真实生产事故中提炼，结合 Nicole Tietz、Brendan Gregg、Julia Evans 等业界顶级工程师的方法论。

为什么需要这个？

AI Agent 在调试时容易陷入以下陷阱：

🚨 醉汉反模式 — 随机改代码直到问题消失
🚨 路灯反模式 — 只在熟悉的地方找，而不是问题真正在的地方
🚨 补丁链 — 每次报新错就修那个错，越改越乱
🚨 忽略用户 — 用户说"改了X就坏了"，却继续自己猜

这套方法论提供了一个强制性的调试流程，避免这些常见错误。

核心流程

阶段 1：停下来    → 动手前先搞清现状（进程、环境、启动命令）
阶段 2：想清楚    → 形成一个假设（优先查自己改了什么）
阶段 3：去验证    → 一次改一个，验证后再继续
阶段 4：检测问题  → 改了2次没好？全部回退，重新来

快速决策树

出现报错
  ├─ 刚才在改代码？ → 查看变更 diff → 有嫌疑就回退
  ├─ 服务起不来？   → 检查启动命令 + 环境变量
  ├─ 修完又报新错？ → 停下！（补丁链！）→ 全部回退 → 重回阶段1
  ├─ 用户反馈回归？ → 对比用户最后确认正常前后的变更
  └─ 偶发问题？     → 查日志 + 外部依赖 + 时序关系

作为 OpenClaw Skill 使用

将 SKILL.md 放入你的 skills 目录：

mkdir -p ~/.agents/skills/debug-methodology
cp SKILL.md ~/.agents/skills/debug-methodology/

重启 OpenClaw 后，所有 session 遇到调试场景会自动加载这套方法论。

完整规范

详见 SKILL.md — 包含：

4阶段调试流程（停下来 → 建立假设 → 验证 → 补丁链检测）
4大反模式警告（醉汉 / 路灯 / 货物崇拜 / 忽略用户）
环境检查清单（运行时 / 依赖 / 配置 / 进程管理器 / 日志 / 备份）
部署安全流程（拉取 → 备份 → 修改 → 测试 → 部署 → 验证）
快速决策树

起源

这套方法论源自一次真实的生产事故：

修复一个简单的超时问题（2步就能搞定），却因为重启服务时没用虚拟环境，走了10步弯路。事后复盘发现，如果一开始跑一句 ps -p <PID> -o command= 就能避免所有问题。

由此总结出这套通用调试规范，并结合业界最佳实践形成了完整的方法论。

安装

clawhub install debug-methodology

Wiki

更详细的案例分析和扩展内容请查看 Wiki。

🔗 AI 开发质量工具套件

技能	用途	安装命令
bug-audit	动态缺陷扫描，覆盖 200+ 常见陷阱	`clawhub install bug-audit`
codex-review	三层代码审查，含对抗性测试	`clawhub install codex-review`
debug-methodology（本仓库）	根因调试，防止补丁链蔓延	`clawhub install debug-methodology`
nodejs-project-arch	AI 友好架构，节省 70–93% token	`clawhub install nodejs-project-arch`
game-quality-gates	12 项通用游戏开发质量检查	`clawhub install game-quality-gates`

许可证

MIT

3.9 KiB Raw Blame History Unescape Escape