bugfix

每个 Bug 修复都必须遵循复现—诊断—修复—验证流程。

不可妥协的规则：

1. 在有复现步骤或明确记录无法复现的原因之前，不得编写修复代码。
2. 修复根因，而不是表面症状。
3. 更改应尽可能小，并且仅限于该 Bug。
4. 修改前先加载相关框架参考文档。
5. 对 Bug 分类后，加载 references/bug-playbooks.md。
6. 绝不得弱化测试来让修复通过。

Bug 修复

输入

• $request：可选的 Bug 描述、失败场景或问题选择器

目标

通过复现、诊断、针对性实现和回归检查，以最小且正确的更改解决已确认的缺陷。

步骤 0：检测框架并加载参考文档

诊断 Bug 前，根据问题文件中的导入语句、项目依赖文件和文件扩展名，识别语言和框架：

信号	框架	参考文件
package.json 包含 express	Express.js	references/expressjs.md
package.json 包含 react 和 JSX/TSX 文件	React	references/react.md
package.json 包含 react-native 或 expo	React Native	references/react-native.md
package.json 包含 next	Next.js	references/nextjs.md
package.json 包含 fastify	Fastify	references/fastify.md
package.json 包含 hono	Hono	references/hono.md
package.json 包含 @remix-run/react	Remix	references/remix.md
存在 bun.lockb 或 bunfig.toml	Bun	references/bun.md
composer.json 包含 laravel/framework	Laravel	references/laravel.md
存在 go.mod	Go	references/golang.md
go.mod 包含 github.com/gin-gonic/gin	Go + Gin	references/go-gin.md
go.mod 包含 github.com/labstack/echo	Go + Echo	references/go-echo.md
go.mod 包含 github.com/gofiber/fiber	Go + Fiber	references/go-fiber.md
存在 .swift 文件或 Package.swift	Swift	references/swift.md
存在 Cargo.toml 和 .rs 文件	Rust	references/rust.md
Cargo.toml 包含 axum	Rust + Axum	references/rust-axum.md
Cargo.toml 包含 actix-web	Rust + Actix Web	references/rust-actix.md
Cargo.toml 包含 rocket	Rust + Rocket	references/rust-rocket.md
存在 .ts/.js 文件（未指定具体框架）	Node.js/TypeScript	references/nodejs-typescript.md

参考文档加载规则：

1. 始终加载基础语言参考文档（例如，Node.js 使用 nodejs-typescript.md，Go 使用 golang.md，Rust 使用 rust.md）。
2. 在基础文档之上叠加框架专属参考文档（例如，Express 同时读取 nodejs-typescript.md 和 expressjs.md；Axum 同时读取 rust.md 和 rust-axum.md）。
3. React Native 包含 React——同时读取 react.md 和 react-native.md。
4. Next.js 和 Remix 包含 React——同时读取 react.md 和对应的框架文件。
5. Go 框架叠加在 Go 之上——同时读取 golang.md 和对应的框架文件。
6. Rust 框架叠加在 Rust 之上——同时读取 rust.md 和对应的框架文件。
7. 如果无法确定框架，则回退到语言级参考文档。

成功标准：开始诊断前，已加载相关的语言和框架参考文档。

步骤 1：解析并选择缺陷

接受以下任意输入：

• 已验证的 /find-bugs 发现结果
• 用户提交的缺陷报告
• 失败的测试
• 工作期间遇到的运行时崩溃或构建失败

提取：

• 症状
• 触发条件
• 预期行为
• 可能涉及的文件或子系统
• 严重程度（如果有提供）
• 任务是单个缺陷还是一批缺陷

对于 /find-bugs 的输出：

• 仅提取用户要求修复的发现结果
• 按严重程度和依赖关系排序
• 将涉及同一文件或函数的发现结果分组

如果请求未描述已确认的缺陷，请停止并澄清，而不是盲目修补。

成功标准：缺陷范围明确到足以复现和修复。

步骤 2：先复现缺陷

在受影响代码附近创建或找到最小相关测试。

必需流程：

1. 针对确切的缺陷场景编写失败测试
2. 仅运行该复现测试
3. 确认测试因预期原因失败
4. 仅在能够直接保护修复的情况下，添加密切相关的边界情况测试

如果无法复现：

• 检查环境假设
• 检查确切的触发输入
• 检查自收到报告后代码是否已发生变化
• 检查缺陷是否为间歇性问题或与并发有关
• 如果仍无法复现，请停止并报告尝试过的步骤

成功标准：你有一个失败的复现测试，或对无法复现的原因有准确说明。

步骤 3：诊断根本原因

阅读完整的本地上下文：

• 受影响的函数或模块
• 直接调用方
• 直接依赖项
• 附近的测试
• 相关类型定义或契约

然后：

1. 从入口点到故障点追踪数据流
2. 找出链路中第一个被破坏的假设
3. 梳理影响范围：
   • 调用方
   • 导入方
   • 依赖的测试
   • 受影响的公共 API 或契约
4. 对缺陷类别进行分类

缺陷类别：

• 注入
• XSS
• 身份验证 / 授权
• 空值安全
• 竞态条件
• 边界 / 差一错误
• 异步 / Promise
• 类型安全
• 资源泄漏
• 逻辑 / 业务规则

分类后，阅读 references/bug-playbooks.md 并使用匹配的章节。

成功标准：你能用一句话说明根本原因，并指出正确的修复指南。

步骤 4：规划最小修复

设计能够修复根本原因的最小改动。

编辑前检查：

• 必须更改哪些文件
• 哪些调用方或依赖项会受到影响
• 公共 API 或类型是否会发生变化
• 修复是否需要纵深防御
• 批量修复是否应按依赖顺序拆分

对于重要修复，先提供简短计划，再进行修补：

• 缺陷
• 根本原因
• 类别 / 修复指南
• 影响范围
• 复现测试
• 计划更改的文件

成功标准：计划中的改动明显小于重构，并且与根本原因直接相关。

步骤 5：实施修复

实施规则：

• 只修改解决缺陷所需的最小范围
• 遵循 references/bug-playbooks.md 中对应类别的修复指南
• 遵循已加载的框架参考资料
• 不要混入清理、样式修复或功能开发
• 不要不经检查代码就盲目照搬 /find-bugs 的建议

每次完成一个逻辑改动后：

1. 运行复现测试
2. 确认测试正在向通过状态推进
3. 如果修复更改了调用方或契约，完成整个依赖链上的修改

成功标准：复现测试因正确的原因从失败变为通过。

步骤 6：验证是否引入回归

复现测试通过后：

1. 运行受影响范围内的测试
2. 如果影响范围跨越模块或包边界，则运行更广泛的测试
3. 运行类型检查或同等的静态验证
4. 运行 references/bug-playbooks.md 中针对该类别的验证清单
5. 检查是否有调试残留和意外的清理改动

如果修复导致无关失败，请停止并重新诊断，再考虑扩大范围。

成功标准：修复在本地通过，类别专属检查全部通过，并且没有引入明显的回归。

第 7 步：谨慎处理多个 Bug 的批次

对于多个问题：

• 按文件、函数和依赖关系分组
• 按顺序修复相互依赖的问题
• 按严重程度修复相互独立的问题
• 每组修复后都运行验证，不要只在最后验证
• 如果一个修复解决了另一个问题，请明确说明，不要假装两个问题都需要单独修补

成功标准：批次工作便于审查，并能及早发现回归问题。

第 8 步：报告结果

对于每个已修复的 Bug，请报告：

• 根本原因
• 类别／采用的操作手册
• 更改的文件
• 复现测试
• 已完成的验证
• 任何剩余风险或延期跟进事项

请附上摘要，包括：

• 已修复的 Bug
• 新增或更新的测试
• 修改的文件
• 更广泛的验证是否通过

如果某个 Bug 未修复，请明确说明原因：

• 无法复现
• 信息不足
• 根本原因来自上游
• 修复需要进行超出 Bug 修复范围的架构更改

成功标准：其他工程师能够理解修复了什么、为何采用这种修复方式，以及如何验证。

防护措施

• 除非明确记录无法复现的原因，否则不要在没有复现步骤的情况下进行修复。
• 如果根本原因仍然存在，不要只修复表面症状。
• 不要削弱或跳过测试。
• 不要将重构与 Bug 修复混在一起。
• 不要将 Bug 修复工作转变为功能开发。
• 不要留下宽泛的 TODO 来代替完成实际修复。

何时加载参考资料

• 框架参考资料： 在第 0 步加载相关语言和框架文档。
• references/bug-playbooks.md： 在第 3 步完成 Bug 分类后加载。

输出约定

回复应聚焦于执行过程和证明：

1. 正在修复的 Bug
2. 复现该问题的方法
3. 找到的根本原因
4. 所做的更改
5. 验证修复的方法