bugfix

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

<EXTREMELY-IMPORTANT> Every bugfix must follow a reproduce-diagnose-fix-verify loop.

Non-negotiable rules:

Do not write fix code before you have a reproducer or a clearly documented reason reproduction is impossible.
Fix the root cause, not the symptom.
Keep the change minimal and scoped to the bug.
Load the relevant framework reference before patching.
Load
```
references/bug-playbooks.md
```
after classifying the bug category.
Never weaken tests to make a fix pass.

</EXTREMELY-IMPORTANT>

<EXTREMELY-IMPORTANT> 每一次bug修复都必须遵循“重现-诊断-修复-验证”的循环。

不可协商的规则：

在没有重现用例或明确记录无法重现的原因之前，不要编写修复代码。
修复根本原因，而非表面症状。
保持变更最小化，仅针对当前bug。
在打补丁前加载相关的框架参考资料。
对bug分类后加载
```
references/bug-playbooks.md
```
。
绝不要为了让修复通过而弱化测试。

</EXTREMELY-IMPORTANT>

Bugfix

Bug修复

Inputs

输入

```
$request
```
: Optional bug description, failing scenario, or finding selector

```
$request
```
：可选的bug描述、失败场景或检测结果选择器

Goal

目标

Resolve confirmed defects with the smallest correct change, backed by reproduction, diagnosis, targeted implementation, and regression checks.

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

Step 0: Detect framework and load references

步骤0：检测框架并加载参考资料

Before diagnosing the bug, identify the language and framework from the buggy file's imports, the project's dependency files, and the file extension:

Signal	Framework	Reference File
`package.json` has `express`	Express.js	`references/expressjs.md`
`package.json` has `react` + JSX/TSX files	React	`references/react.md`
`package.json` has `react-native` or `expo`	React Native	`references/react-native.md`
`package.json` has `next`	Next.js	`references/nextjs.md`
`package.json` has `fastify`	Fastify	`references/fastify.md`
`package.json` has `hono`	Hono	`references/hono.md`
`package.json` has `@remix-run/react`	Remix	`references/remix.md`
`bun.lockb` or `bunfig.toml` present	Bun	`references/bun.md`
`composer.json` has `laravel/framework`	Laravel	`references/laravel.md`
`go.mod` present	Go	`references/golang.md`
`go.mod` has `github.com/gin-gonic/gin`	Go + Gin	`references/go-gin.md`
`go.mod` has `github.com/labstack/echo`	Go + Echo	`references/go-echo.md`
`go.mod` has `github.com/gofiber/fiber`	Go + Fiber	`references/go-fiber.md`
`.swift` files, `Package.swift`	Swift	`references/swift.md`
`Cargo.toml` present, `.rs` files	Rust	`references/rust.md`
`Cargo.toml` has `axum`	Rust + Axum	`references/rust-axum.md`
`Cargo.toml` has `actix-web`	Rust + Actix Web	`references/rust-actix.md`
`Cargo.toml` has `rocket`	Rust + Rocket	`references/rust-rocket.md`
`.ts` / `.js` files (no specific framework)	Node.js/TypeScript	`references/nodejs-typescript.md`

Reference loading rules:

Always load the base language reference (e.g.,
```
nodejs-typescript.md
```
for Node.js,
```
golang.md
```
for Go,
```
rust.md
```
for Rust).
Layer the framework-specific reference on top (e.g., read both
```
nodejs-typescript.md
```
and
```
expressjs.md
```
for Express; both
```
rust.md
```
and
```
rust-axum.md
```
for Axum).
React Native includes React -- read both
```
react.md
```
and
```
react-native.md
```
.
Next.js and Remix include React -- read both
```
react.md
```
and the framework file.
Go frameworks layer on Go -- read both
```
golang.md
```
and the framework file.
Rust frameworks layer on Rust -- read both
```
rust.md
```
and the framework file.
If the framework is unclear, fall back to the language-level reference.

Success criteria: The relevant language and framework references are loaded before diagnosis begins.

在诊断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`

参考资料加载规则：

始终加载基础语言参考资料（例如，Node.js对应
```
nodejs-typescript.md
```
，Go对应
```
golang.md
```
，Rust对应
```
rust.md
```
）。
在基础参考之上加载特定框架的参考资料（例如，Express需同时阅读
```
nodejs-typescript.md
```
和
```
expressjs.md
```
；Axum需同时阅读
```
rust.md
```
和
```
rust-axum.md
```
）。
React Native包含React——需同时阅读
```
react.md
```
和
```
react-native.md
```
。
Next.js和Remix包含React——需同时阅读
```
react.md
```
和对应框架的文件。
Go框架基于Go——需同时阅读
```
golang.md
```
和对应框架的文件。
Rust框架基于Rust——需同时阅读
```
rust.md
```
和对应框架的文件。
如果框架不明确，回退到语言级别的参考资料。

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

Step 1: Parse and select the bug

步骤1：解析并选择bug

Accept any of these inputs:

verified
```
/find-bugs
```
findings
user bug reports
failing tests
runtime crashes or build failures encountered during work

Extract:

symptom
trigger
expected behavior
likely file or subsystem
severity if provided
whether the task is a single bug or a batch

For

/find-bugs

output:

extract only the findings the user asked to fix
sort by severity and dependency
group findings that touch the same file or function

If the request does not describe a confirmed bug, stop and clarify instead of patching blindly.

Success criteria: The bug scope is explicit enough to reproduce and fix.

接受以下任意输入：

已验证的
```
/find-bugs
```
检测结果
用户提交的bug报告
失败的测试
工作中遇到的运行时崩溃或构建失败

提取信息：

症状
触发条件
预期行为
可能涉及的文件或子系统
若提供则提取严重程度
任务是单个bug还是批量bug

对于

/find-bugs

输出：

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

如果请求未描述已确认的bug，请停止操作并澄清，不要盲目打补丁。

成功标准：bug范围足够明确，可进行重现和修复。

Step 2: Reproduce the bug first

步骤2：先重现bug

Create or locate the smallest relevant test close to the affected code.

Required loop:

write a failing test for the exact bug scenario
run only that reproducer
confirm it fails for the expected reason
add closely related edge-case tests only if they directly protect the fix

If you cannot reproduce:

check environment assumptions
check exact triggering input
check whether the code has already changed since the report
check whether the bug is intermittent or concurrency-related
if it still cannot be reproduced, stop and report what you tried

Success criteria: You have a failing reproducer, or a precise explanation of why reproduction is blocked.

创建或定位与受影响代码最相关的最小测试用例。

必需的循环：

针对确切的bug场景编写一个失败的测试
仅运行该重现用例
确认它因预期原因失败
仅当边缘用例直接保护修复时，才添加相关的边缘用例测试

如果无法重现：

检查环境假设
检查确切的触发输入
检查自报告以来代码是否已变更
检查bug是否是间歇性的或与并发相关
如果仍无法重现，请停止操作并报告已尝试的步骤

成功标准：拥有一个失败的重现用例，或对无法重现的原因有精确解释。

Step 3: Diagnose the root cause

步骤3：诊断根本原因

Read the full local context:

the affected function or module
direct callers
direct dependencies
nearby tests
relevant type definitions or contracts

Then:

trace data flow from entry point to failure point
identify the first broken assumption in the chain
map the blast radius:
- callers
- importers
- dependent tests
- public APIs or contracts affected
classify the bug category

Bug categories:

Injection
XSS
Auth/AuthZ
Null safety
Race condition
Boundary / off-by-one
Async / Promise
Type safety
Resource leak
Logic / business rule

After classification, read

references/bug-playbooks.md

and use the matching section.

Success criteria: You can state the root cause in one sentence and name the correct fix playbook.

阅读完整的本地上下文：

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

然后：

跟踪从入口点到失败点的数据流
识别链中第一个被打破的假设
影响范围分析：
- 调用者
- 导入者
- 依赖的测试
- 受影响的公共API或契约
对bug进行分类

bug类别：

注入（Injection）
XSS
认证/授权（Auth/AuthZ）
空值安全（Null safety）
竞态条件（Race condition）
边界/差一错误（Boundary / off-by-one）
异步/Promise
类型安全（Type safety）
资源泄漏（Resource leak）
逻辑/业务规则（Logic / business rule）

分类完成后，阅读

references/bug-playbooks.md

并使用匹配的章节。

成功标准：可以用一句话说明根本原因，并指出正确的修复操作手册。

Step 4: Plan the minimal fix

步骤4：规划最小化修复

Design the smallest change that fixes the root cause.

Check before editing:

which files must change
which callers or dependents are affected
whether a public API or type changes
whether the fix needs defense-in-depth
whether the fix should be split by dependency order in a batch

For significant fixes, present a short plan before patching:

bug
root cause
category / playbook
blast radius
reproducer
intended files to change

Success criteria: The planned change is clearly smaller than a refactor and directly tied to the root cause.

设计能够修复根本原因的最小变更。

编辑前检查：

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

对于重大修复，在打补丁前提交简短计划：

bug描述
根本原因
类别/操作手册
影响范围
重现用例
计划变更的文件

成功标准：计划的变更明显小于重构，且直接关联根本原因。

Step 5: Implement the fix

步骤5：实施修复

Implementation rules:

patch the smallest surface that resolves the bug
follow the category playbook from
```
references/bug-playbooks.md
```
follow the loaded framework reference
do not mix in cleanup, style fixes, or feature work
do not blindly copy the
```
/find-bugs
```
suggestion without checking the code

After each logical edit:

run the reproducer
confirm movement toward green
finish the dependency chain if the fix changes callers or contracts

Success criteria: The reproducer turns from failing to passing for the right reason.

实施规则：

仅修补解决bug所需的最小范围
遵循
```
references/bug-playbooks.md
```
中的类别操作手册
遵循已加载的框架参考资料
不要混入清理、样式修复或功能开发
不要盲目复制
```
/find-bugs
```
的建议而不检查代码

每次逻辑编辑后：

运行重现用例
确认修复进展
如果修复变更了调用者或契约，完成依赖链的调整

成功标准：重现用例因正确的原因从失败转为通过。

Step 6: Verify against regressions

步骤6：验证回归情况

After the reproducer is green:

run the affected test scope
run broader tests if the blast radius crosses module or package boundaries
run type checking or equivalent static verification
run the category-specific verification checklist from
```
references/bug-playbooks.md
```
check for debug artifacts and accidental cleanup changes

If the fix causes unrelated failures, stop and re-diagnose before expanding scope.

Success criteria: The fix is green locally, category-specific checks pass, and no obvious regressions were introduced.

重现用例通过后：

运行受影响的测试范围
如果影响范围跨模块或包边界，运行更广泛的测试
运行类型检查或等效的静态验证
运行
```
references/bug-playbooks.md
```
中的类别特定验证清单
检查是否有调试 artifacts 和意外的清理变更

如果修复导致无关的失败，请停止操作并重新诊断，不要扩大范围。

成功标准：修复在本地通过测试，类别特定检查通过，且未引入明显的回归问题。

Step 7: Handle multi-bug batches carefully

步骤7：谨慎处理多bug批量修复

For multiple findings:

group by file, function, and dependency
fix dependent findings in order
fix independent findings by severity
run verification after each group, not only at the end
if one fix resolves another finding, say so explicitly instead of pretending both required separate patches

Success criteria: Batch work remains reviewable and regressions are caught early.

对于多个检测结果：

按文件、函数和依赖关系分组
按依赖顺序修复相关的检测结果
按严重程度修复独立的检测结果
每组修复后进行验证，而非仅在最后验证
如果一个修复解决了另一个检测结果，请明确说明，不要假装两者都需要单独补丁

成功标准：批量工作保持可审查性，且能尽早发现回归问题。

Step 8: Report the result

步骤8：报告结果

For each bug fixed, report:

root cause
category / playbook used
files changed
reproducer test
verification completed
any remaining risk or deferred follow-up

Include a summary with:

bugs fixed
tests added or updated
files modified
whether broader verification passed

If a bug was not fixed, say exactly why:

could not reproduce
insufficient information
root cause is upstream
fix requires architectural change beyond bugfix scope

Success criteria: Another engineer can understand what was fixed, why it was fixed that way, and how it was verified.

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

根本原因
使用的类别/操作手册
变更的文件
重现测试用例
完成的验证工作
任何剩余风险或延迟的后续工作

包含以下摘要：

已修复的bug数量
添加或更新的测试
修改的文件
更广泛的验证是否通过

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

无法重现
信息不足
根本原因来自上游
修复需要超出bug修复范围的架构变更

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

Guardrails

约束规则

Do not fix without a reproducer unless you explicitly document why reproduction is impossible.
Do not fix the symptom if the root cause is still present.
Do not weaken or skip tests.
Do not mix refactors with bugfixes.
Do not convert bugfix work into feature work.
Do not leave broad TODOs instead of finishing the actual fix.

除非明确记录无法重现的原因，否则不要在没有重现用例的情况下修复bug。
如果根本原因仍然存在，不要仅修复表面症状。
不要弱化或跳过测试。
不要将重构与bug修复混在一起。
不要将bug修复工作转为功能开发。
不要留下宽泛的TODO，而不完成实际修复。

When To Load References

何时加载参考资料

Framework references: load the relevant language and framework docs in Step 0.
```
references/bug-playbooks.md
```
: load after classifying the bug in Step 3.

框架参考资料：在步骤0中加载相关的语言和框架文档。
```
references/bug-playbooks.md
```
：在步骤3对bug分类后加载。

Output Contract

输出约定

Keep the response focused on execution and proof:

what bug is being fixed
what reproduced it
what root cause was found
what changed
how the fix was verified

保持响应聚焦于执行和证明：

正在修复的bug是什么
如何重现它
发现的根本原因是什么
做了哪些变更
如何验证修复