Bug 修复

测试先行的 Bug 修复流程，确保每个修复都有回归测试保护和完整记录。

语言规则

• 支持中英文提问
• 统一中文回复

触发条件

• 用户报告 Bug 或问题
• 用户提到"修复"、"bug"、"issue"、"崩溃"、"报错"
• 用户提供 Issue 编号或链接
• 测试执行失败（UT/IT/E2E）

核心理念

先证明 Bug 存在（失败测试），再修复代码，最后证明 Bug 已修复（测试通过）。
每个 Bug 都要记录，形成知识沉淀。

Bug 复杂度判断

复杂度	特征	流程
简单	单文件/单函数、原因明确	本 Skill 直接修复
复杂	多模块、需拆分步骤、原因不明	必须走 /devdocs-dev-tasks

工作流程

1. 理解 Bug + 评估复杂度
   │
   ├── 复杂 Bug → **必须** /devdocs-dev-tasks 拆分任务
   │              （用户明确选择"继续简单流程"时除外）
   │
   └── 简单 Bug → 继续
   │
   ▼
2. 定位代码
   │
   ▼
3. 编写失败测试（证明 Bug 存在）
   │
   ├── 测试通过 → ⚠️ Bug 未复现，重新确认
   └── 测试失败 → ✅ 继续
   │
   ▼
4. 修复代码
   │
   ▼
5. 运行测试
   │
   ├── 测试失败 → 返回步骤 4
   └── 测试通过 → ✅ 继续
   │
   ▼
6. 记录 Bug（追加到 05-bugfix-log.md）
   │
   ▼
7. 询问用户：是否提交？
   │
   └── 生成 fix() 提交信息

输出文件

Bug 修复日志：docs/devdocs/05-bugfix-log.md

Bug 编号规则

类型	前缀	格式	说明
Bug 记录	BUG	BUG-XXX	Bug 修复记录编号

编号延续现有文档中的最大编号。

Step 1: 理解 Bug

收集 Bug 信息：

信息	来源	必要性
Bug 描述	用户输入	必须
复现步骤	用户输入	建议
预期行为	用户输入	建议
实际行为	用户输入	必须
发现来源	测试编号/手动测试/用户反馈	必须
关联功能	F-XXX / AC-XXX	必须
Issue 编号	用户输入	可选

如信息不足，使用 AskUserQuestion 询问。

复杂度评估

使用 AskUserQuestion 确认：

根据 Bug 描述，评估复杂度：

[ ] 涉及多个模块/文件
[ ] 原因不明确，需要深入分析
[ ] 修复可能影响其他功能
[ ] 需要多个步骤完成

⚠️ 如以上任一命中，**必须**走 /devdocs-dev-tasks 拆分任务。
确定要跳过任务拆分，继续简单流程吗？[使用任务拆分(推荐)/继续简单流程]

Step 2: 定位代码

搜索策略：

1. 关键词搜索：根据 Bug 描述搜索相关代码
2. 错误信息搜索：搜索报错信息中的关键字
3. 测试定位：从失败的测试用例定位
4. 用户指定：用户直接提供文件路径

向用户确认定位结果。

Step 3: 编写失败测试

测试命名规范

should [预期行为] when [触发条件]

测试结构

/**
 * @verifies AC-XXX   // 关联的验收标准（必须，确保 trace 可追溯）
 * @verifies BUG-XXX  // Bug 编号（保留，用于 Bug 追踪）
 * @testcase UT-XXX
 */
describe('Bug fix: BUG-XXX <Bug 描述>', () => {
  it('should <预期行为> when <条件>', () => {
    // Arrange - 构造触发 Bug 的条件
    // Act - 执行操作
    // Assert - 验证预期行为
  });
});

验证测试有效性

运行测试，确认测试失败：

• 测试失败 ✅ → Bug 已复现，继续修复
• 测试通过 ⚠️ → Bug 未复现，需重新确认

Step 4: 修复代码

修复原则

• 最小改动：只修改必要的代码
• 不引入新功能：修复 Bug，不顺便重构
• 遵循现有风格：与周围代码保持一致

修复约束

参考 /code-quality 约束。

Step 5: 运行测试

# 运行新增的 Bug 修复测试
npm test -- --testNamePattern="Bug fix"

# 运行全部测试，确保没有引入回归
npm test

• 新测试通过 + 全部测试通过 ✅ → 修复完成
• 新测试失败 → 返回步骤 4 继续修复
• 其他测试失败 → 检查是否引入回归

Step 6: 记录 Bug

记录模板

追加到 docs/devdocs/05-bugfix-log.md：

## BUG-XXX: <Bug 标题>

| 属性 | 内容 |
|------|------|
| **发现来源** | UT-XXX / IT-XXX / E2E-XXX / 手动测试 / 用户反馈 |
| **关联功能** | F-XXX, AC-XXX |
| **Issue** | #123（如有）|
| **严重程度** | P0 / P1 / P2 |
| **修复日期** | YYYY-MM-DD |
| **状态** | ✅ 已修复 |

### 问题描述

<Bug 现象描述>

### 复现步骤

1. <步骤1>
2. <步骤2>
3. <观察到的错误>

### 根因分析

<为什么会出现这个问题，技术层面的原因>

### 解决方案

<如何修复的，修改了什么>

### 回归测试

- 新增测试：UT-XXX / IT-XXX
- 关联 commit：`<commit-hash>`

### 经验教训（可选）

<避免类似问题的建议，供团队参考>

---

记录要点

字段	说明	必填
发现来源	哪个测试/谁发现的	必须
关联功能	涉及哪个功能点（F-XXX / AC-XXX）	必须
根因分析	技术层面的原因	必须
解决方案	如何修复的	必须
回归测试	新增的测试编号	必须

Step 7: 提交

提交前检查

• 新增的测试通过
• 全部测试通过
• Bug 已记录到 05-bugfix-log.md
• 代码符合规范

提交信息格式

遵循 /commit-convention：

fix(<scope>): <简述问题>

- 根因：<问题原因>
- 修复：<解决方案>
- 测试：<新增测试编号>

BUG-XXX
Fixes #<issue-number>

示例：

fix(auth): handle empty username in login

- 根因：login() 未校验空用户名，直接查询数据库导致异常
- 修复：添加用户名非空校验，返回明确错误信息
- 测试：UT-025

BUG-003
Fixes #123

与测试用例的闭环

测试执行（UT/IT/E2E）
    │
    ├── 通过 → 正常
    │
    └── 失败 → 触发 /devdocs-bugfix
                    │
                    ├── 记录 BUG-XXX（关联测试编号）
                    │
                    ├── 修复代码
                    │
                    ├── 新增回归测试（更新测试编号）
                    │
                    └── /devdocs-sync 更新追溯矩阵

编排规范（子 Agent 调度）

复杂 Bug 路径下，devdocs-bugfix 调用子技能时必须通过 Task tool 启动子 Agent：

场景	被调度技能	调度方式
复杂 Bug 拆分	/devdocs-dev-tasks	Task tool 子 Agent
复杂 Bug 开发	/devdocs-dev-workflow	Task tool 子 Agent
文档同步	/devdocs-sync	Task tool 子 Agent

调度原则

1. 上下文隔离：每个子 Agent 自行读取所需文档，bugfix 编排层不传递全文
2. 摘要传递：只接收子 Agent 返回的 YAML 摘要，据此决定下一步
3. 异常回退：子 Agent 返回 status: failed + blockers 时，展示阻塞项询问用户
4. 不自行排障：编排层不读取子技能的完整输出文档来尝试修复

简单 Bug 因流程短（单文件修复），直接在 bugfix 上下文内执行，不启动子 Agent。

Skill 协作

场景	协作 Skill	说明
复杂 Bug 拆分	/devdocs-dev-tasks	多步骤 Bug 走任务拆分
回归测试设计	/devdocs-test-cases	补充回归测试到测试文档
需求缺失	/devdocs-requirements	Bug 暴露需求问题时调用
测试编写	/testing-guide	测试代码质量约束
代码修改	/code-quality	修复代码质量约束
文件操作	/git-safety	使用 git mv/rm
提交信息	/commit-convention	提交规范
文档同步	/devdocs-sync	修复后更新追溯矩阵

约束

流程约束

• 必须先编写失败测试，再修复代码
• 测试必须先失败，证明 Bug 存在
• 修复后测试必须通过
• 不得跳过测试直接提交
• 复杂 Bug 走 dev-tasks + dev-workflow 时必须通过 Task tool 启动子 Agent
• 简单 Bug 直接在 bugfix 上下文内执行

记录约束

• 每个 Bug 必须记录到 05-bugfix-log.md
• 必须记录发现来源
• 必须记录根因分析
• 必须记录解决方案
• 必须关联回归测试编号

追溯同步约束

• 修复完成后必须执行 /devdocs-sync
• 新增的回归测试必须登记到 03-test-*.md 追溯矩阵
• 如不执行 trace，Bug 修复将成为"旁路"，测试无法追溯

测试约束

• 测试名称描述 Bug 场景
• 测试覆盖 Bug 的触发条件
• 测试必须添加 @verifies AC-XXX 标注（关联的验收标准，确保 trace 可追溯）
• 测试必须添加 @verifies BUG-XXX 标注（Bug 编号）
• 禁止弱断言（参考 /testing-guide）

提交约束

• 提交信息使用 fix(<scope>): 前缀
• 提交信息包含 BUG-XXX 编号
• 关联 Issue 编号（如有）

子 Agent 摘要格式

当本 Skill 作为子 Agent 运行时，返回以下结构化摘要：

skill: devdocs-bugfix
bug_id: BUG-XXX
complexity: simple | complex
status: fixed | not_reproduced | in_progress
related: { feature: F-XXX, ac: AC-XXX }
test_added: [UT-025]
commit_hash: "abc1234"
output_file: docs/devdocs/05-bugfix-log.md

特殊情况

Bug 无法复现

⚠️ 测试通过，Bug 未能复现。

可能原因：
1. 复现条件不完整
2. Bug 已在其他提交中修复
3. 环境差异导致无法复现

建议：
- 确认复现步骤是否完整
- 检查最近的相关提交
- 与报告者确认环境信息

复杂 Bug

如 Bug 涉及多个模块或原因不明：

⚠️ 检测到复杂 Bug，**必须**使用任务拆分：

1. 使用 /devdocs-dev-tasks 拆分为多个子任务
2. 每个子任务独立修复和测试
3. 最后集成验证

确定要跳过任务拆分吗？[使用任务拆分(推荐)/继续简单流程]

默认必须走任务拆分，仅当用户明确选择"继续简单流程"时才允许跳过。

Bug 暴露设计缺陷

如 Bug 暴露了设计问题：

1. 先用最小改动修复当前 Bug
2. 记录设计缺陷到"经验教训"
3. 创建改进建议（可选 /devdocs-insights）
4. 使用 /refactor 进行系统性改进