Back to Details

bug-fix-protocol

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Bug Fix Protocol

Bug修复流程

A bug fix is two fixes in one: fix the code, and fix the testing system that let the bug through. Skipping the second step means the same class of bug ships again.
The full protocol (philosophy, eight steps with examples, audit checklist, anti-patterns) lives in 
PROTOCOL.md
. Read it before applying.
修复Bug其实是一举两得的修复：既要修复代码，也要修复未能拦截该Bug的测试系统。跳过第二步意味着同类Bug会再次上线。
完整流程（理念、带示例的八步操作、审计清单、反模式）详见
PROTOCOL.md
。在应用前请先阅读该文档。

When to apply

适用场景

Use this protocol whenever a defect reaches production, staging, or a customer environment. Do not use it for bugs caught locally during normal development — those are part of the writing process, not testing-system failures.
当缺陷出现在生产环境、预发布环境或客户环境时，适用本流程。请勿将其用于正常开发过程中在本地发现的Bug——这类Bug属于代码编写过程的一部分，并非测试系统故障。

The eight steps (summary)

八步流程（摘要）

  1. Analyze and reproduce requirements. Understand exact actual vs expected behaviour; identify minimal repro path; ask the user before guessing on ambiguities.
  2. Write a failing test (red). Encode the bug as a test that fails for the right reason. No code change yet.
  3. Trace root cause. Walk the failing test back through the system. Stop at the smallest place that, if changed, makes the test pass.
  4. Apply the minimal fix. Smallest possible change. No drive-by refactors.
  5. Verify green locally. Failing test now passes; no other tests regressed.
  6. Run the full suite + lints + types. Catch indirect regressions.
  7. Document the fix. Commit message and PR description name the symptom, the root cause, and the fix in one sentence each.
  8. Audit the testing system (the most important step). Ask: which layer should have caught this, and why didn't it? Then change that layer so it would catch the next instance — new test type, new fixture, new lint rule, new property test, new contract assertion. A fix without step 8 is incomplete.
  1. 分析并复现需求。明确实际行为与预期行为的差异；找出最简复现路径；遇到模糊点时先询问用户，不要自行猜测。
  2. 编写失败测试（红阶段）。将Bug转化为测试用例，确保该测试因正确的原因失败。此时暂不修改代码。
  3. 追溯根本原因。通过系统回溯失败测试的执行路径。定位到最小的修改点，只要改动该点就能让测试通过。
  4. 实施最小化修复。采用尽可能小的改动。不要顺带进行重构。
  5. 本地验证测试通过（绿阶段）。之前失败的测试现在能通过；其他测试未出现回归问题。
  6. 运行完整测试套件+代码检查+类型校验。排查间接回归问题。
  7. 记录修复内容。提交信息和PR描述分别用一句话说明症状、根本原因和修复方案。
  8. 审计测试系统（最重要的步骤）。思考：哪一层本该拦截这个Bug，却没有做到？ 然后修改该层，确保能拦截下一次同类问题——比如新增测试类型、新的测试夹具、新的代码检查规则、新的属性测试、新的契约断言。未完成第8步的修复是不完整的。

Output expectations

输出要求

When applying the protocol, return:
  • The repro test (red, then green).
  • The minimal code fix.
  • A one-paragraph step-8 audit naming the missed coverage layer and the change made to close the gap.
If step 8 produces "we couldn't have caught this," investigate further — that answer is almost always wrong, and accepting it is how the testing system stagnates.
应用本流程时，需提交：
  • 复现测试用例（先失败，后成功）。
  • 最小化代码修复。
  • 一段关于第8步的审计内容，说明遗漏的覆盖层以及为填补缺口所做的改动。
如果第8步得出“我们本无法拦截这个Bug”的结论，请进一步调查——这个答案几乎都是错误的，接受它会导致测试系统停滞不前。

Reference

参考资料

Full text: 
PROTOCOL.md
.
完整文档：
PROTOCOL.md
。