Git Worktree + AI Coding Agent 并行实战：任务拆分、冲突收敛与质量门禁

AI 开发方法论 , , , , ,

Git Worktree + AI Coding Agent 并行实战：任务拆分、冲突收敛与质量门禁

简介

基础篇介绍了如何为单个 AI Coding Agent 创建隔离 worktree。本文进入实战：当你同时使用 Claude Code、Codex、OpenCode、Hermes 子代理，或者让同一个工具处理多个子任务时，如何把任务拆开、并行执行、统一测试、最后安全合并。

适用场景：

  • OpenSpec 已经定义好一个较大的功能，需要前端、后端、测试、文档并行推进；
  • 想让 Claude Code 写实现，让 Codex 做审查或补测试；
  • 多个 bug 修复互不依赖，希望当天全部进入 PR；
  • 不希望 AI Agent 互相覆盖文件或在同一个目录抢锁。

前置要求

  • 已读基础篇：Git Worktree + AI Agent 基础与隔离工作流。
  • 项目主分支干净，且本地测试命令可运行。
  • 能清楚描述任务边界，例如”只改认证模块””只补 E2E 测试”。
  • 团队约定好分支命名，例如 agent/<topic>-<role> 或 feature/<topic>-<part>。

详细步骤

1. 先拆任务，再开 Agent

不要把”大而泛”的需求直接交给多个 Agent。先拆成文件边界尽量清晰的子任务：

子任务 推荐分支 主要目录 Agent 角色
后端接口 agent/order-api server/, tests/api/ 实现者
前端页面 agent/order-ui web/, tests/e2e/ 实现者
数据迁移 agent/order-db migrations/, schema/ 谨慎实现者
测试审查 agent/order-review tests/, 文档 审查者

好的拆分原则：

  1. 每个 Agent 有明确成功标准；
  2. 尽量减少多个 Agent 修改同一个文件；
  3. 数据库 schema、公共类型、路由表这类共享文件必须指定”唯一负责人”；
  4. 每个子任务都能独立运行局部测试。

2. 批量创建 worktree

从主仓库执行：

1
2
3
4
5
6
7
cd ~/projects/my-app
git switch main
git pull --ff-only

git worktree add -b agent/order-api ../my-app-wt-order-api main
git worktree add -b agent/order-ui ../my-app-wt-order-ui main
git worktree add -b agent/order-review ../my-app-wt-order-review main

查看当前 worktree：

1
git worktree list

3. 给每个 Agent 写”边界提示词”

后端 Agent 示例：

1
2
3
4
你在 my-app-wt-order-api worktree 中工作。
任务：实现订单查询 API。
边界：优先修改 server/orders、tests/api；不要修改 web/；如果必须改共享类型，先在总结中说明原因。
质量门禁：新增单元测试；运行 npm run test:api；提交前输出 git diff --stat。

前端 Agent 示例：

1
2
3
4
5
你在 my-app-wt-order-ui worktree 中工作。
任务：实现订单列表页面。
边界：优先修改 web/orders、tests/e2e；不要改 server/ 数据访问逻辑。
依赖：如果后端接口尚未完成，可先使用 mock 数据并标注 TODO。
质量门禁：运行 npm run lint 和 npm run test:e2e -- orders。

审查 Agent 示例：

1
2
3
你在 my-app-wt-order-review worktree 中工作。
任务：阅读 OpenSpec 与现有测试，列出验收用例，不直接改业务代码。
输出：新增或补充测试计划文档；指出 API/UI/DB 三类风险。

4. 并行运行，但串行合并

可以同时启动多个 Agent，但合并必须串行进行：

1
2
3
4
5
6
7
8
# 终端 A
cd ~/projects/my-app-wt-order-api && claude

# 终端 B
cd ~/projects/my-app-wt-order-ui && codex

# 终端 C
cd ~/projects/my-app-wt-order-review && opencode

每个 Agent 完成后，在自己的 worktree 中提交：

1
2
3
4
5
git status --short
git diff --stat
npm test
git add .
git commit -m "feat: implement order api"

然后回主工作区按依赖顺序合并。通常顺序是：公共类型/数据库 → 后端 → 前端 → 测试/文档。

1
2
3
4
5
6
7
8
cd ~/projects/my-app
git switch main
git pull --ff-only

git merge --no-ff agent/order-api
git merge --no-ff agent/order-ui
git merge --no-ff agent/order-review
npm test

5. 处理冲突：先理解，再选择

冲突常见于公共文件，例如 package.json、路由表、schema、类型定义。处理原则：

  1. 不要让 Agent 自动盲目解决核心冲突；
  2. 先用 git status 看冲突文件；
  3. 对公共文件优先人工审查；
  4. 解决一个冲突后立即运行相关测试；
  5. 合并完成后再让审查 Agent 做二次 review。

查看冲突：

1
2
git status
git diff --name-only --diff-filter=U

解决后继续：

1
2
3
git add <resolved-file>
git commit
npm test

6. 建立质量门禁

建议每个分支合并前至少满足：

  • git diff --stat 可解释，没有明显越界文件；
  • 新功能有测试或明确说明为什么暂时不能测；
  • 本地 lint/test 通过；
  • Agent 输出了变更摘要、风险点、验证命令；
  • 合并到 main 后再跑一次全量测试。

如果项目较大，可以写一个统一脚本：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
#!/usr/bin/env bash
set -euo pipefail

echo "== format check =="
npm run format:check

echo "== lint =="
npm run lint

echo "== unit tests =="
npm test

echo "== build =="
npm run build

保存为 scripts/quality-gate.sh 后：

1
2
chmod +x scripts/quality-gate.sh
./scripts/quality-gate.sh

代码示例

下面是一个简单的 Python 分配脚本，用任务名生成 worktree 创建命令。它不会直接执行命令，先打印出来供你审查。

1
2
3
4
5
6
7
8
9
10
11
12
13
from pathlib import Path

repo = Path.home() / "projects" / "my-app"
base = repo.parent
tasks = [
    ("order-api", "agent/order-api"),
    ("order-ui", "agent/order-ui"),
    ("order-review", "agent/order-review"),
]

for name, branch in tasks:
    worktree = base / f"my-app-wt-{name}"
    print(f"git worktree add -b {branch} {worktree} main")

输出示例：

1
2
3
git worktree add -b agent/order-api /home/you/projects/my-app-wt-order-api main
git worktree add -b agent/order-ui /home/you/projects/my-app-wt-order-ui main
git worktree add -b agent/order-review /home/you/projects/my-app-wt-order-review main

如果确认无误，再复制到主仓库执行。对生产项目，不建议让脚本默认自动创建和删除目录，避免误操作。

常见问题

1. 多个 Agent 都需要改同一个类型文件怎么办？

指定一个”公共契约负责人”。其他 Agent 只提出需要的字段，不直接改类型文件。先合并公共契约分支，再让其他 worktree rebase 或重新创建。

2. 并行开发时应该用 merge 还是 rebase？

本地短期分支都可以。新手建议用 merge --no-ff，历史更清楚，也方便知道每个 Agent 贡献了什么。如果团队强制线性历史，可在 PR 阶段 squash/rebase。

3. Agent 生成了大量无关格式化改动怎么办？

先不要合并。让 Agent 在该 worktree 中撤销无关文件，或人工用 git restore <file> 恢复。质量门禁中必须检查 git diff --stat。

4. worktree 中依赖安装很慢，是否每个目录都要装一遍？

语言不同策略不同。Node.js 可用 pnpm 共享 store；Python 可用 uv 或 pip 缓存；Go/Rust 通常有全局模块缓存。源码目录隔离和依赖缓存共享并不矛盾。

5. 如何让 OpenSpec 与 worktree 配合？

一个 spec change 对应一个总任务，再拆成多个 worktree。规格文件的修改最好由一个分支负责，其他实现分支引用该规格，不要并行改同一份 spec。

6. 什么时候不适合并行 Agent？

需求还不清楚、核心架构未定、测试完全缺失、共享文件会被大量修改时，不适合直接并行。先让一个 Agent 做调研和计划，再进入 worktree 并行阶段。

7. 合并后发现主分支坏了怎么办？

如果刚合并，可用 git revert -m 1 <merge-commit> 回滚某个 merge commit。更推荐在合并每个分支后立即运行全量测试，尽早定位是哪一个分支引入问题。

小结

AI Agent 并行开发的关键不是”同时启动越多越好”，而是任务边界、工作区隔离、质量门禁和串行收敛。git worktree 提供隔离，OpenSpec 提供需求边界，测试与人工审查负责最后的可信度。三者结合，才能把 AI 编程从一次性实验推进到可重复的工程流程。

CaoZHProgrammer

学习使我快乐。