# Phase Gated Debugging

> 调试任何 bug 时使用。强制执行 5 阶段协议，在确认根因之前禁止编辑代码，防止过早尝试修复。

- Skill: `kscz0000/phase-gated-debugging` (Agent Skill)
- Install (CLI): `npx skillmds@latest add kscz0000/phase-gated-debugging`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kscz0000/phase-gated-debugging/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: kscz0000 (https://skillmd.com/u/kscz0000)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/kscz0000/phase-gated-debugging

---


# 阶段门控调试

## 概述

AI 编码智能体看到错误就立刻改代码。它们猜测修复方案，猜错后越改越乱。本技能强制执行严格的 5 阶段协议——在根因被识别和确认之前，**禁止**编辑源代码。

基于 [claude-debug](https://github.com/krabat-l/claude-debug)（完整插件，带 PreToolUse 钩子强制执行）。

## 适用场景

在以下情况下使用本技能：

- bug 反复"修复"却始终未解决根本问题
- 需要放慢智能体节奏，强制其在编辑代码前进行规范化调试
- 故障是间歇性的、回归性的、性能相关的，或难以定位
- 希望在应用任何修复之前有明确的用户确认检查点

## 协议流程

### 阶段 1：复现
运行失败的命令/测试。捕获确切错误。运行 2-3 次确认一致性。
- **不要**阅读源代码
- **不要**假设推测
- **不要**编辑任何文件

### 阶段 2：隔离
阅读代码。添加标记为 `// DEBUG` 的诊断日志。带诊断重新运行。二分搜索缩小范围。
- 仅允许 `// DEBUG` 标记的日志
- **不要**修复 bug，即使你已经看到问题

### 阶段 3：根因
在隔离位置分析"为什么"。使用"5 个为什么"技术。移除调试日志。

声明："这是我的根因分析：[解释]。你同意吗，还是需要我进一步调查？"

**等待用户确认。没有确认不得继续。**

### 阶段 4：修复
移除所有 `// DEBUG` 行。针对已确认的根因进行最小化修改。
- 仅编辑与根因相关的文件
- **不要**重构无关代码

### 阶段 5：验证
运行原始失败测试——必须通过。运行相关测试。对于间歇性 bug，运行 5 次以上。
如果验证失败：根因判断错误，回到阶段 2。

## Bug 类型策略

| 类型 | 技术 |
|------|------|
| 崩溃/Panic | 反向追踪堆栈——追溯坏值到其源头 |
| 输出错误 | 二分搜索——记录中点，每次迭代将搜索空间减半 |
| 间歇性 | 对比成功与失败运行的日志——找出排序差异 |
| 回归 | `git bisect`——找到问题提交 |
| 性能 | 在阶段边界计时——找到瓶颈 |

## 核心规则

1. 阶段 1-3 **绝不**编辑源代码（阶段 2 的 `// DEBUG` 除外）
2. 阶段 3 之后**绝不**跳过用户确认直接继续
3. 调查之前**必须**先复现
4. 修复之后**必须**验证

## 限制
- 仅当任务明确匹配上述范围时才使用本技能。
- 不要将输出视为环境特定验证、测试或专家评审的替代品。
- 如果缺少所需输入、权限、安全边界或成功标准，请停下来请求澄清。