fix-bug

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Fix Bug Workflow

Bug修复工作流

Follow this exact sequence. No plan needed — go straight to debugging.

严格遵循以下步骤序列。无需制定计划——直接进入调试环节。

1. Sync main

1. 同步主分支

git checkout main && git pull

git checkout main && git pull

2. Systematic Debugging

2. 系统化调试

DO NOT guess fixes — find root cause first
Phase 1: Read errors, reproduce, check recent changes (
```
git log --oneline -10
```
), gather evidence
Phase 2: Find working examples in the codebase, compare
Phase 3: Form a single hypothesis, test minimally
Phase 4: Implement fix with test

切勿猜测修复方案——先找到根本原因
阶段1：阅读错误信息、复现Bug、查看最近变更（
```
git log --oneline -10
```
）、收集证据
阶段2：在代码库中寻找可运行的示例，进行对比
阶段3：形成单一假设，进行最小化测试
阶段4：编写测试并实现修复

3. Create worktree and branch

3. 创建工作树与分支

git worktree add .claude/worktrees/fix-<name> -b fix/<bug-description>
cd .claude/worktrees/fix-<name>

All work happens in the worktree — main stays clean.

git worktree add .claude/worktrees/fix-<name> -b fix/<bug-description>
cd .claude/worktrees/fix-<name>

所有工作都在工作树中完成——主分支保持干净。

4. TDD Fix

4. TDD模式修复

Write a failing test that reproduces the bug FIRST
Then implement the fix
The test must pass after the fix
Run full test suite to check for regressions

首先编写一个能复现Bug的失败测试
然后实现修复方案
修复完成后测试必须通过
运行完整测试套件以检查是否存在回归问题

5. Verify

5. 验证

Run full test suite
Verify the original bug is fixed
Check no regressions

运行完整测试套件
验证原始Bug已修复
检查是否存在回归问题

6. Code Review

6. 代码审查

Self-review via
```
git diff main...HEAD
```
Or dispatch a code-review subagent if available
Fix all issues found before proceeding

通过
```
git diff main...HEAD
```
进行自我审查
若有可用的代码审查子Agent，可调用其协助
在继续下一步前修复所有发现的问题

7. Create PR

7. 创建PR

Commit with message explaining the root cause
Push branch and create PR via
```
gh pr create
```
Wait for CI/CD checks to complete:
```
gh pr checks <number> --watch
```
If checks fail, fix the issues and push again — do not notify the user until all checks are green
Once all checks pass, return the PR URL and ask the user to review
DO NOT merge — wait for explicit approval

提交时附带说明根本原因的提交信息
推送分支并通过
```
gh pr create
```
创建PR
等待CI/CD检查完成：
```
gh pr checks <number> --watch
```
若检查失败，修复问题后重新推送——在所有检查通过前不要通知用户
所有检查通过后，返回PR链接并请求用户审查
切勿合并——等待明确的批准

8. Merge (only when approved)

8. 合并（仅在获得批准后）

```
gh pr merge <number> --merge
```

Clean up worktree:

cd <project-root> && git worktree remove .claude/worktrees/fix-<name>

git checkout main && git pull && git branch -d fix/<bug-description>

```
gh pr merge <number> --merge
```

清理工作树：

cd <project-root> && git worktree remove .claude/worktrees/fix-<name>

git checkout main && git pull && git branch -d fix/<bug-description>

Rules

规则

Never merge without explicit approval
Never push directly to main
Always write a regression test — the bug must never come back
No plan needed — bugs are urgent, go straight to debugging
If 3+ fix attempts fail, stop and question the architecture
No dead code, no silent excepts, no string literals for constants

未经明确批准绝不合并
绝不直接推送到主分支
始终编写回归测试——确保Bug不再重现
无需制定计划——Bug修复紧急，直接进入调试
若3次以上修复尝试失败，停止操作并质疑架构合理性
禁止冗余代码、静默异常、使用字符串字面量作为常量

Quality Checklist

质量检查清单

Before every PR, answer each item and present as a markdown table:

#	Check	Answer
1	What changed — what was fixed and how	[brief]
2	Root cause fix — does this fix the root cause, or just the symptom?	[yes/no + evidence]
3	Single source of truth — no duplicate data paths or redundant caches introduced?	[yes/no + evidence]
4	Test regression — do all existing tests pass?	[pass count / fail count]
5	Reuse — did you reuse existing patterns/functions, or reinvent something?	[yes/no + evidence]

If any answer is unsatisfactory, fix it before creating the PR
Be honest — don't beautify answers

在创建每个PR前，逐一回答以下问题并以Markdown表格形式呈现：

#	检查项	回答
1	变更内容——修复了什么问题以及修复方式	[简要说明]
2	根本原因修复——此修复针对的是根本原因还是仅解决了表面症状？	[是/否 + 证据]
3	单一数据源——是否引入了重复的数据路径或冗余缓存？	[是/否 + 证据]
4	测试回归——所有现有测试是否通过？	[通过数量 / 失败数量]
5	复用性——是否复用了现有模式/函数，还是重新实现了功能？	[是/否 + 证据]

若任何回答不达标，在创建PR前进行修复
务必诚实——不要美化回答