| name | branch-polish |
| description | 代码审视清理——扫描变更中的遗留调试代码、废弃注释、无 backlog 引用的 TODO 等,一次确认后批量修改,跑通全量测试。 |
branch-polish — 代码审视与清理
扫描当前分支或工作区变更中的可清理项,一次性列出全部建议,用户确认后批量修改,最后跑全量测试。
分支类型不限(feature/hotfix/release/master 均可),也不限定是否在 worktree 中。
输入
/branch-polish # 自动判断模式
/branch-polish <ref> # 指定 commit 范围(如 HEAD~5、main)
步骤
阶段一:判断变更来源
git status --short → 有输出:Dirty 模式,扫 git diff HEAD。
- 无输出 → 当前分支 ≠ master:
- 无输出 → 当前分支 = master:
- 用户必须指定范围(
/branch-polish <ref>),否则停止并提示"当前在 master 分支且工作区干净,请指定变更范围,如 /branch-polish HEAD~5"。
不创建新 worktree,不创建新分支。在当前工作目录原地操作。
阶段二:扫描
Dirty 模式扫 git diff HEAD,Commit 模式逐 commit git show <hash>。按以下维度收集清理项:
- 遗留调试代码:
print、临时 logger.debug、breakpoint() / pdb.set_trace()
- 被注释掉的旧代码块
- 多余/重复的 import
- 过时或与代码现状不一致的注释
- 冗余变量或中间赋值
- 硬编码临时值(magic number、临时端口号等)
- TODO/待办类注释:逐行判断是否为"写了 TODO 但没 backlog 引用"的待办项。TODO 注释必须引用有效的 backlog ID(格式
B-YYMMDD-xxxxxx,如 B-260601-ef9e5a),引用写在 TODO 旁边:
- 规范写法:
# TODO(B-260601-ef9e5a): 此处需集成用户自定义 API Key 路由
- 无 backlog 引用 → 清理项,建议"添加 backlog 引用或移除此 TODO"
- 有 backlog 引用 → 可保留,标注"有 backlog 引用"
- 类型标注缺失或不一致
- 命名不当(
tmp、foo、拼写错误等)
- 中间版本 schema/迁移:迭代多次的 schema 或迁移脚本,只保留起点到终点的单次迁移(Commit 模式才能识别;Dirty 模式下 agent 自行判断)
阶段三:确认
一次性列出全部清理项:
【清理 1】src/plugins/DicePP/shell/session.py:42
类型: 遗留调试代码
内容: print(f"DEBUG: lease acquired: {path}")
→ 建议: 删除
【清理 2】src/plugins/DicePP/shell/session.py:78-84
类型: 注释掉的旧代码块
内容: # old_lock = os.link(tempfile, lockfile)
→ 建议: 删除注释掉的代码
【清理 3】src/.../some_file.py:15
类型: TODO 缺少 backlog 引用
内容: # TODO: 以后改成异步
→ 建议: 添加 backlog 引用(如 B-YYMMDD-xxxxxx)或移除此 TODO
---
共发现 N 条清理项。回复"全部处理"/"处理 1,3,5"/"跳过"。
交互:
- "全部处理" → 进入阶段四,执行所有建议
- "处理 x,y,z" → 只执行选中的
- "跳过 x" → 跳过某项,其余全部处理
- "跳过全部" → 退出
阶段四:执行
一次性应用所有确认的清理改动,直接编辑代码。
Dirty 模式:改动直接覆盖到工作区已有变更中,不操作 git。
Commit 模式:
- 展示 diff 摘要
- 按 git-commit-brief 规范拟一条 commit message:
建议 commit:
chore(<scope>): 清理 <简述清理内容>
- 用户确认后
git add + git commit。用户可修改 message 后再确认。
阶段五:全量测试
调用 auto-test-run 运行完整测试套件。测试失败则排查是否由清理改动引入,修复后重跑。
Dirty 模式收尾:
代码清理完成。
模式: 工作区清理
处理: K 处 / 跳过: J 处
全量测试: ✓ 通过
清理改动已应用到工作区,请 review 后提交。
Commit 模式收尾:
代码清理完成。
模式: commit 扫描
分支: <当前分支>
处理: K 处 / 跳过: J 处
全量测试: ✓ 通过
如需整理清理产生的 commit,运行 /branch-tidy。
约束
- 阶段三一次性展示全部建议,用户确认后方可修改代码
- 不创建新 worktree 或分支
- commit message 遵守 git-commit-brief 规范