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: 定位代码
搜索策略：
- 关键词搜索：根据 Bug 描述搜索相关代码
- 错误信息搜索：搜索报错信息中的关键字
- 测试定位：从失败的测试用例定位
- 用户指定：用户直接提供文件路径
向用户确认定位结果。
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 |
调度原则
- 上下文隔离：每个子 Agent 自行读取所需文档，bugfix 编排层不传递全文
- 摘要传递：只接收子 Agent 返回的 YAML 摘要，据此决定下一步
- 异常回退：子 Agent 返回
status: failed+blockers时，展示阻塞项询问用户 - 不自行排障：编排层不读取子技能的完整输出文档来尝试修复
简单 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 进行系统性改进