---

name: fix-bug description: 当处理缺陷、回归、失败测试、崩溃、错误输出、性能下降或不稳定行为（包括需要先补充复现或证据的情况）时使用。

修复缺陷

概述

基于证据定位根因，做最小且安全的修改并验证。仅在高风险/不可逆变更时确认。

建议角色

• 👨‍💻 高级开发者：定位根因并实施最小修复。
• 🧪 QA 工程师：设计复现步骤并验证回归。

何时使用

• 失败测试、回归、崩溃、错误输出、性能下降、不稳定行为
• 堆栈、错误日志、异常、超时、带复现步骤的用户报告
• 需要纠正既有行为，而非新增功能

不适用

• 新功能或大幅行为变更（用 develop-feature）
• 大范围重构或重新设计（切换到 refactor 流程）

必需子技能

• REQUIRED SUB-SKILL: verification-before-completion

核心模式

1. 观察：捕捉精确失败（日志/堆栈/失败测试）
2. 复现：最小复现或定向日志
3. 定位：沿输入 → 失败追踪，找出第一个错误假设
4. 修复：最小变更解决根因
5. 验证：重跑复现 + 相关回归检查

快速参考

实施要点

• 从证据出发，不凭猜测；引用检查过的文件/函数/行号。
• 缺少复现时先补证据（临时日志/失败测试）。
• 优先局部、可回滚变更；范围扩大或风险上升再询问。
• 解释为什么能修复根因（不是只说改了什么）。

高风险确认条件

• 破坏性或不可逆操作（数据删除、历史重写、破坏性迁移）
• 安全、鉴权变更或敏感数据处理
• 破坏 API、契约或兼容性风险

示例

症状： TypeError: Cannot read properties of undefined (reading 'id')
根因： 认证 token 过期时 user 可能为 undefined。
修复（最小保护）：

Copy// before
const userId = user.id;

// after
if (!user) return res.status(401).end();
const userId = user.id;

验证： 添加测试 “expired token returns 401” 并重跑失败端点。

常见错误

• 只补症状（try/catch）而不定位根因
• 没有复现或证据就猜测
• 为小 bug 做大范围重构
• 跳过验证或回归检查
• 通过禁用测试或加超时来“变绿”

借口 vs 事实

红旗 - 立刻停止

• “先加 try/catch”
• “先禁用测试”
• “无法复现就猜”
• “不如全量重构”
• “不验证就上线”
• “高风险变更未明确确认”