一句话结论:把 Agent 推进 Issue 的路径收成固定清单——同步主干 → 正确 worktree/分支 → 最小改动 → 本地验证 → PR(Closes #N)→ 等 CI → squash merge → 删分支。 清单写进 AGENTS.md 或 skill,比每次口头叮嘱稳。
为什么 Agent 会在「快做完」时翻车
多 worktree、多 Agent 并行时,常见翻车不是「不会写代码」,而是:
- 改在了错误的树 / 旧分支
- 没跑项目约定的验证就开 PR
- PR 描述没有关联 Issue,合并后追踪断裂
- 顺手重构扩大 diff,CI 红了更难回滚
- 合并完不删分支,下一轮继续推脏状态
下面是一份环境无关的推进清单。命令用占位符,换成你仓库的真实脚本即可。
推进清单(Agent 每轮照做)
0. 对齐工作区
pwd
git rev-parse --show-toplevel
git branch --show-current
git status -sb
若使用 git worktree:确认路径和分支名与 Issue 一致,再回答「做完了吗」。细节见《worktree 里问 issue 做完了吗》。
1. 同步主干
git fetch origin
git checkout <main-branch>
git pull --ff-only origin <main-branch>
git checkout -b <type>/<issue-number>-<short-slug>
# 或:已有分支则 rebase/merge 按团队约定
2. 只做 Issue 范围
- 打开 Issue 正文,列出验收点(checkbox)
- 每个提交只服务这些点
- 禁止:无关格式化、升级依赖「顺便做」、重命名大范围文件
环境类失败(缺 CLI、错 Node、端口占用)应写进共享硬约束,见《AGENTS.md 环境硬约束》。
3. 本地验证(未绿不开 PR)
# 按项目替换
<YOUR_LINT_CMD>
<YOUR_TEST_CMD>
<YOUR_TYPECHECK_OR_BUILD_CMD>
验证输出摘要写进 PR body。失败则修,不「先 PR 再看 CI」。
4. 开 PR
git push -u origin HEAD
gh pr create --title "<type>: <摘要> (#<N>)" --body "$(cat <<'EOF'
## Summary
- <改动点 1>
- <改动点 2>
## Test plan
- [x] <YOUR_LINT_CMD>
- [x] <YOUR_TEST_CMD>
- [ ] CI
Closes #<N>
EOF
)"
Closes #<N>(或团队等价语法)让合并自动关 Issue,避免人工漏关。
5. 等 CI,处理评审
可用 Claude Code:/loop 10m 检查 PR #<号> 的 CI 与 review;红了就修并推;有评论就逐条处理;全绿且无阻塞评论时停下来等我确认合并。
6. 合并与清理
在人工确认后:
gh pr merge <号> --squash --delete-branch
git checkout <main-branch>
git pull --ff-only
需要时再删本地分支与 worktree。
最小 PR body 模板
## Summary
- …
## Test plan
- [ ] 单元/集成
- [ ] 手动验证步骤(如有 UI)
## Risk
- 低/中/高:…
Closes #<N>
失败模式速查
| 症状 | 原因 | 修复 |
|---|---|---|
| CI 与本地不一致 | 未装同版本依赖 / 锁文件未提交 | 对齐 toolchain;提交 lockfile |
| 合并冲突反复 | 长期不开主干同步 | 每日 rebase/merge main |
| Issue 仍开着 | PR 未写 Closes | 补关键词或手动关 |
| 「做完了」但功能缺 | 验收点未勾 | 对照 Issue checkbox |
| diff 爆炸 | 夹带格式化/生成物 | 拆 PR;生成物按规范提交或忽略 |
可选:写成 skill /loop 提示词
把第 0–5 步贴进 skill,用 /loop 15m 跑「接管当前 Issue 直到可合并」。停止条件必须写死:CI 绿 + 你要求的审查通过 + 等待人工 merge 指令。不要让 Agent 在未授权时强行 merge。
写在最后
Agent 的生产力差,经常差在合并礼仪而不是模型智商。清单越短越好记,记不住就放进仓库里让 Agent 每次自己读。
口径:流程为通用工程实践模板;gh 命令可换成 GitLab/其他 forge 等价物。未绑定任何私有仓库名称。
COMMENTS
读者评论