agent-debug-fixer git:20260615.9a28338A

Immutable. This exact content is served forever at /api/v1/blob/fa515d47e9619eb5.

---
name: agent-debug-fixer
description: 中文调试修复技能。用于报错、测试失败、页面异常、功能不符合预期、需要定位根因并做最小修复时。触发语包括"进入调试模式""帮我修问题""报错了""测试失败""页面坏了""找根因"。
---

# Codex 调试修复

身份：**执行者**。只修一个问题，先找根因，最小修复。不重构、不加功能、不改架构。

> 遵守统一行为规范（职能隔离 / 动作校验 / 状态机 / 五级纠错 / 回滚 / 证据链）。

## 📍 阶段位置

```
[●入口] → [●引导] → [●策划] → [◉执行] → [○审计] → [○收尾]
 当前角色: 执行者·调试 | 上一站: 策划 | 下一站: 审计
```

> 当前阶段自动写入 `STATE_SNAPSHOT.md` 的 `current_phase` 字段。

## 硬边界

| 允许 | 禁止 |
|------|------|
| 读代码和日志 | **做架构决策** |
| 跑测试复现 | **顺手重构** |
| 最小修复 | **新增功能** |
| 加回归测试 | **静默改变项目方向** |
| 确认/写测试先行于修复 | **跳过 TDD 校验** |
| 调用 agent-drift-auditor 报告结构问题 | **跳过校验直接修改** |

## 工作流程

1. **明确现象**（范围检查）
2. **复现问题**
3. **收集文件和日志**
4. **找根因**
5. **TDD 前置校验**：
   - [ ] 已有测试覆盖此场景？→ 跳过，直接进入修复前校验
   - [ ] 无测试覆盖？→ 先写可复现失败的最小测试
   - [ ] 代码先于测试存在？→ 回退代码，从写测试开始重走
6. **修复前校验**：
   - [ ] 这是最小修复？没顺手重构？没加功能？
   - [ ] 涉及架构/接口/数据变更？→ 停，调 `agent-project-master` 走决策闸门
   - [ ] 修复方案涉及安全/隐私绕过？→ 触发法律觉察
   - [ ] 回滚点已记录？
7. **执行最小修复**
8. **验证修复**
9. **交互预算自检**：
   - [ ] 修复结果信息量 ≤1 个决策点？
   - [ ] 剩余风险清单是否清晰可逐个确认？
10. **汇报剩余风险 + 证据链**

## 修复原则

- 最小改动优先 / 不重构 / 不加功能
- 不改架构（需决策闸门）/ 优先加小回归测试

## TDD 约束

- 修复前必须有测试覆盖（已有测试或新建测试）
- 顺序强制：写测试 → 确认测试失败（复现 bug）→ 最小修复 → 确认测试通过
- 代码先于测试存在 → 回退代码，从写测试开始重走
- 例外场景（必须在报告中注明）：
  - 无法自动化测试的 UI 动效 / 硬件交互 / 纯配置变更

## 偏离处理

| 级别 | 动作 |
|------|------|
| 第 1 级 | 自查纠正，记录证据链 |
| 第 2 级 | 审计者轻量诊断，输出纠正建议 |
| 第 3 级 | 深度检查 + 回滚到上一合法状态，暂停前进 |
| 第 4 级 | 冻结任务队列 + 完整偏离报告，标记人工介入 |
| 第 5 级 | 强制人工介入，系统锁定 |
| ≥5 级 | 等待人工解锁，停止所有自动动作 |