一句话结论:把 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 等价物。未绑定任何私有仓库名称。