# 系统化调试方法论

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

# 🔍 调试方法论

[![ClawHub](https://img.shields.io/badge/ClawHub-debug--methodology-blue?style=flat-square)](https://clawhub.com)
[![License: MIT](https://img.shields.io/badge/License-MIT-green?style=flat-square)](LICENSE)
[![OpenClaw Skill](https://img.shields.io/badge/OpenClaw-Agent_Skill-orange?style=flat-square)](https://github.com/openclaw/openclaw)

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

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

## 为什么需要这个？

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

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

## 核心流程

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

## 快速决策树

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

## 作为 OpenClaw Skill 使用

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

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

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

## 完整规范

详见 [SKILL.md](SKILL.md) — 包含：

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

## 起源

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

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

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

## 安装

```bash
clawhub install debug-methodology
```

## Wiki

更详细的案例分析和扩展内容请查看 [Wiki](../../wiki)。

## 🔗 AI 开发质量工具套件

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

## 许可证

MIT