---
title: "定位并修复 Bug"
description: "把\"先诊断、后动手、独立验证\"的排障流程打包成 skill，报 bug 时一句话触发"
---

> Documentation Index
> Fetch the complete documentation index at: https://konghayao.github.io/peri-cool/llms.txt
> Use this file to discover all available pages before exploring further.

# 定位并修复 Bug

排障有一套固定节奏：给足复现信息、先诊断后动手、复杂问题并行探路、修完独立验证。每次修 bug 都要走这套节奏，值得打包成一个 skill——构建一次，以后报 bug 一句话触发。

## 构建 fix-bugs skill

```text
帮我构建一个修复 bug 的 skill，命名 fix-bugs，
保存到 ~/.claude/skills/fix-bugs/。

流程要求：
1. 先收集复现信息：报错原文、操作步骤、相关文件；信息不足先问
2. 先诊断后动手：搜索调用链、读日志，定位根因后先说明，等我确认后再改
3. 涉及多文件的复杂 bug，先按疑点并行派探索子代理摸清范围
4. 修完派 verification 子代理独立验证：测试通过、无新增 warning、覆盖不下降
5. 同一 bug 连续两次没修好，建议 /clear 重来
```

生成的 `SKILL.md` 内容类似这样：

```markdown
---
name: fix-bugs
description: 修复 bug 时使用。用户报告报错、测试失败、异常行为时触发。
---

# 定位并修复 Bug

1. **复现信息**：确认报错原文、操作步骤、相关文件；信息不足先问
2. **先诊断后动手**：搜索调用链、读日志，定位根因后先说明，等用户确认再改，
   不拿到报错直接改
3. **复杂 bug 并行探路**：涉及多文件时，按疑点并行派探索子代理摸清范围再切入
4. **独立验证**：修完派 verification 子代理验证：测试全部通过、
   无新增 warning、相关模块覆盖不下降
5. **两次没修好就重来**：同一 bug 连续两次修复未果时，建议 /clear 开新会话，
   重新探索——旧上下文里的错误假说和试错片段只会继续干扰
```

## 流程在做什么

- **复现信息决定定位速度**：报错原文和操作步骤是最便宜的线索，缺了它们 Peri 只能猜
- **先诊断后动手**：拿到报错直接改，最容易修错地方。先找到根因，改动才有依据
- **两次修不好就重来**：修 bug 的上下文会被错误假说、过时的搜索结论污染，重开比硬撑快
- **独立验证**：改完自己说"好了"不可信，让不带修复过程的 verification 子代理跑一遍

## 使用

```text
用 fix-bugs 修一下 cargo test auth:: 的失败，报错原文：
<贴出报错原文>
复现步骤：先启动服务，再调用 POST /auth/compact
```

Peri 会按流程走：收集信息 → 诊断根因（先说明等你确认）→ 修复 → 独立验证。skill 的存放位置、自动加载机制和修改方式，见[探索陌生代码库](/peri-cool/docs/features/explore-codebase/)的说明。

## 进阶：系统化排查

难以定位的 bug 或性能回退，自定义 skill 的线性流程不够用时，用社区成熟的排查流程：

- **systematic-debugging**（superpowers）：复现 → 确定范围 → 提出假设 → 添加诊断 → 验证
- **diagnosing-bugs**（mattpocock/skills）：同款诊断循环，覆盖性能回退场景

获取方式：

```bash
npx skills add https://github.com/konghayao/peri --skill using-superpowers
npx skills add https://github.com/mattpocock/skills --skill diagnosing-bugs
```

用法示例：

```text
/systematic-debugging 排查定时任务每 2 分钟一个实例持续增长的问题
```

排查出根因后，接 `/verification-before-completion` 强制跑完构建、测试、lint 再宣布修复完成。完整的调试模式见 [Superpowers 工作流](/peri-cool/docs/features/superpowers/)。

## 下一步

- 修完确认行为 → [编写测试](/peri-cool/docs/features/write-tests/)
- 修复涉及大改动 → [安全重构](/peri-cool/docs/features/refactor-code/)

Source: https://konghayao.github.io/peri-cool/docs/features/fix-bugs/index.mdx