07 AI 编码与多 Agent 并行开发¶

这一章是整套流程的“施工阶段”。契约已经冻结，UI 已经确认，环境已经就绪。现在要让多个 Agent 像一支工程队一样，在互不干扰的边界内把功能实现出来，并且每一步都留下可验收的证据。

1. 开工前的检查¶

在启动第一个 Agent 之前，确认：

如果任何一项没完成，不要开工。 开工后再补契约，等于一边盖楼一边改图纸。

2. Git 策略：worktree + 功能分支¶

2.1 为什么用 worktree¶

一个工作目录只能同时处于一个分支。多个 Agent 并行时，如果都在同一个目录切换分支，会互相踩踏。git worktree 可以为每个分支创建独立目录，共享同一个 Git 仓库：

# 在仓库根目录
git worktree add ../worktrees/US-001 -b feat/US-001-login main
git worktree add ../worktrees/US-002 -b feat/US-002-create-project main
git worktree add ../worktrees/US-004 -b feat/US-004-create-task main

目录结构：

~/projects/teamtask/                 # 主工作区（main）
~/projects/teamtask-worktrees/
├── US-001/                          # feat/US-001-login
├── US-002/                          # feat/US-002-create-project
└── US-004/                          # feat/US-004-create-task

查看/清理：

git worktree list
git worktree remove ../worktrees/US-001
git branch -d feat/US-001-login

2.2 分支命名¶

feat/US-004-create-task
fix/US-004-duplicate-creation
chore/update-deps
docs/US-004-report

规则：

一个故事一个分支；
分支名包含 story_id；
修复分支包含原故事 ID；
不要在功能分支上改共享契约。

2.3 提交规范¶

feat(task): add create task endpoint

- add POST /api/v1/tasks
- validate project membership and assignee
- write audit log
- add unit and integration tests

Refs: US-004

类型：feat / fix / refactor / test / docs / chore / perf / ci。

每个提交都应该能编译通过。 Agent 不要提交“半成品 + 明天再修”。

3. Agent 角色与分工¶

3.1 角色表¶

Agent	职责	模型	并发
架构 Agent	维护共享文件、路由、迁移、契约变更	最强	串行
后端功能 Agent	一个或一组相关用户故事的后端实现	中/强	可并行
前端功能 Agent	页面/组件/接口联调	中/强	可并行
集成 Agent	合并、跑全量测试、修集成问题	强	串行
测试 Agent	E2E、截图、Word 报告	中	可并行（按故事）
审查 Agent	代码审查、安全审查、契约一致性	最强	可并行（只读）
发布 Agent	构建、部署、冒烟、回滚	中	串行

3.2 什么时候用子 Agent，什么时候开独立会话¶

场景	方式	原因
搜索代码、读日志	子 Agent	隔离脏上下文，主会话只收结论
一个功能从设计到实现	独立会话 + worktree	上下文独立，互不干扰
代码审查	子 Agent 或独立会话	只读，适合并行
修复一个小 bug	子 Agent	快速、低风险
跨模块重构	独立会话 + 串行	影响面大，不适合并行

Claude Code 的自定义子 Agent 定义在 .claude/agents/*.md。示例见本章附录和附录 B。

3.3 自定义子 Agent 示例¶

---
name: backend-feature
description: 按用户故事实现后端功能，包含单元测试和集成测试。用于 Go 后端功能开发。
tools: Read, Write, Edit, Bash, Grep, Glob
model: sonnet
---

你是本项目（TeamTask）的后端功能工程师。

工作前必须阅读：
- `CLAUDE.md`
- `docs/01-design/api/openapi.yaml` 中对应 operation
- `docs/01-design/db/schema.sql` 中对应表
- `docs/01-design/feature-implementation.md` 中对应故事
- `docs/01-design/file-ownership.md`

硬性约束：
1. 只修改分配给你的文件；共享文件（router.go、main.go、migrations）不要动。
2. 先写测试，再实现；测试必须能失败，再让它通过。
3. 所有错误使用统一错误码。
4. 所有权限在后端校验。
5. 完成后运行 `go test -race ./...`、`go vet ./...`、`golangci-lint run`。
6. 按 `模板/feature-report.md` 生成报告。
7. 不要为了让测试通过而删除/跳过测试。
8. 遇到契约不一致，停止并输出问题，不要自行改契约。

4. 任务分解与并行矩阵¶

4.1 垂直切片优先¶

推荐按 用户故事垂直切片 分配，而不是按技术层：

好的拆法：
  Agent A：US-001 登录（后端 API + 前端页面 + 测试）
  Agent B：US-004 创建任务（后端 API + 前端弹窗 + 测试）

不好的拆法：
  Agent A：所有后端
  Agent B：所有前端
  Agent C：所有测试

垂直切片的好处：

每个 Agent 交付一个完整可验收的功能；
减少跨 Agent 的接口等待；
问题定位更清晰；
可以独立跑 E2E。

但垂直切片要求 契约已冻结，否则前后端仍然会对不上。

4.2 并行矩阵¶

先画出依赖和文件冲突：

故事	依赖	后端文件	前端文件	DB 表	可并行
US-001 登录	—	auth/**	LoginView	users	与 US-002 并行
US-002 创建项目	US-001	project/**	ProjectListView	projects, project_members	与 US-001 并行（依赖用户表）
US-003 邀请成员	US-002	member/**	MemberListView	project_members, invitations	与 US-004 并行
US-004 创建任务	US-002, US-003	task/**	CreateTaskModal	tasks, audit_logs	与 US-003 并行
US-005 看板	US-004	task/**（同一模块）	ProjectBoardView	tasks	不要与 US-004 并行（同文件）

结论：

第 1 批：US-001、US-002（需先建 users/projects 表）
第 2 批：US-003、US-004（不同模块）
第 3 批：US-005（依赖 US-004 的 TaskResponse 和 task 模块文件）

4.3 并行度建议¶

第一次：2 个 Agent。
熟练后：3-4 个 Agent。
超过 5 个：协调成本急剧上升，除非模块非常独立。

并行度不是越高越好。 合并冲突、上下文切换、审查负担都会抵消收益。

5. Agent 任务书¶

每个 Agent 开工前，给它一份明确的任务书。模板见模板/agent-brief.md。

5.1 任务书结构¶

# Agent 任务书：US-004 创建任务

## 角色
你是后端功能工程师，负责 US-004 的后端实现。

## 目标
实现 POST /api/v1/tasks，满足验收标准，并通过单元/集成测试。

## 必读
- CLAUDE.md
- docs/01-design/api/openapi.yaml#createTask
- docs/01-design/db/schema.sql#tasks
- docs/01-design/feature-implementation.md#us-004
- docs/01-design/file-ownership.md

## 文件所有权
你可以修改：
- backend/internal/usecase/task/**
- backend/internal/adapter/http/task_handler.go
- backend/internal/adapter/postgres/repo/task_repo.go
- 对应的 _test.go

禁止修改：
- backend/internal/adapter/http/router.go
- backend/cmd/api/main.go
- backend/migrations/**
- backend/api/openapi.yaml
- 其他 Agent 的模块

## 契约
- 请求/响应：见 OpenAPI createTask
- 错误码：VALIDATION_ERROR / FORBIDDEN / PROJECT_NOT_FOUND / PROJECT_ARCHIVED / ASSIGNEE_NOT_IN_PROJECT
- 幂等：Idempotency-Key，24 小时
- 事务：插入任务 + 审计日志在同一事务

## 验收标准
（复制 US-004 的 AC-1 ~ AC-4）

## 测试要求
- 单元测试覆盖：标题校验、负责人校验、权限、日期校验、错误码
- 集成测试覆盖：插入成功、审计写入、幂等、项目归档
- 运行 `go test -race ./internal/usecase/task/... ./internal/adapter/postgres/repo/...`

## 完成定义
- 代码编译通过
- 单元/集成测试全绿
- `go vet` / `golangci-lint` 通过
- 生成 docs/03-dev/reports/US-004-创建任务.md
- 用脚本更新 CSV：status=integ_done
- 提交 Git，分支 feat/US-004-create-task

## 停止条件
- 契约与实现冲突 → 停止，输出 CR
- 需要改共享文件 → 停止，输出变更请求
- 测试无法通过且原因不明 → 停止，附日志
- 发现需求缺失 → 停止，列出问题

5.2 任务书的三个关键¶

边界：能改什么、不能改什么。
证据：怎么证明完成（测试、报告、CSV）。
停止条件：什么时候不要硬撑，要求助。

没有停止条件的 Agent，会为了“完成”而擅自改契约、删测试、绕过权限。

6. 单个 Agent 的执行循环¶

6.1 标准循环（TDD）¶

1. 读契约和实现细节
   ↓
2. 写一个会失败的测试
   ↓
3. 运行测试，确认它失败（红）
   ↓
4. 写最小实现让测试通过（绿）
   ↓
5. 重构，保持测试通过
   ↓
6. 补边界测试
   ↓
7. 跑 lint / vet / race
   ↓
8. 跑集成测试
   ↓
9. 生成功能报告
   ↓
10. 更新 CSV
   ↓
11. 提交 Git

6.2 为什么强调“先让测试失败”¶

AI 很容易写出“永远通过”的测试：

func TestCreateTask(t *testing.T) {
    // 没有断言，或者断言恒真
}

要求先看到红色，可以证明测试确实在测东西。审查 Agent 也要检查这一点。

6.3 测试质量检查¶

测试是否断言了行为，而不只是“没报错”？
是否覆盖了错误码？
是否覆盖了权限？
是否覆盖了边界（空、超长、非法枚举）？
是否使用了真实数据库（集成测试）？
是否有并发测试？
是否删除了测试来让 CI 变绿？

6.4 功能报告¶

每个故事完成后，生成一份独立报告，不要多个功能混在一个文件里：

# US-004 创建任务 - 实现报告

## 基本信息
- 故事：US-004
- 分支：feat/US-004-create-task
- Agent：backend-agent-3
- 完成时间：2026-10-30T18:20:00+08:00
- 状态：integ_done

## 改动文件
| 文件 | 说明 |
|---|---|
| internal/usecase/task/create.go | 创建任务业务逻辑 |
| internal/adapter/http/task_handler.go | POST /tasks handler |
| internal/adapter/postgres/repo/task_repo.go | 插入/查询 |
| internal/usecase/task/create_test.go | 单元测试 |

## 实现要点
- 权限：校验项目成员和负责人成员
- 事务：任务 + 审计日志
- 幂等：Idempotency-Key
- 错误码：见 feature-implementation.md

## 测试结果
- 单元测试：12 passed
- 集成测试：5 passed
- race：通过
- lint：通过

## 已知限制
- 通知为异步 outbox，worker 尚未实现
- 截止日期按 UTC 存储，前端负责时区

## 验收标准覆盖
| AC | 测试 | 结果 |
|---|---|---|
| AC-1 正常创建 | TestCreateTask_Success | pass |
| AC-2 空标题 | TestCreateTask_EmptyTitle | pass |
| AC-3 无权限 | TestCreateTask_Forbidden | pass |
| AC-4 日期非法 | TestCreateTask_InvalidDueDate | pass |

## 证据
- 测试日志：CI run #123
- 提交：abc1234
- E2E：docs/04-qa/manifests/US-004.json（待 QA Agent）

6.5 CSV 更新¶

不要让 Agent 手改 CSV。用脚本：

python3 scripts/update_story_status.py \
  --file docs/00-discovery/user-story.csv \
  --story US-004 \
  --status integ_done \
  --owner backend-agent-3 \
  --branch feat/US-004-create-task \
  --report docs/03-dev/reports/US-004-创建任务.md \
  --unit-test-status pass \
  --integ-test-status pass

脚本会：

校验状态机；
更新 last_updated；
保持 CSV 引号和编码正确；
拒绝非法状态跳转（例如从 ready 直接跳到 deployed_prod）。

7. 共享文件与迁移¶

7.1 共享文件清单¶

以下文件默认只由架构 Agent 修改：

backend/cmd/api/main.go
backend/internal/adapter/http/router.go
backend/internal/config/**
backend/api/openapi.yaml
backend/migrations/**
frontend/src/router/index.ts
frontend/src/api/client.ts
frontend/package.json
docker-compose*.yml
.github/workflows/**

7.2 变更请求流程¶

功能 Agent 需要新增路由
  → 不直接改 router.go
  → 写 docs/01-design/change-requests/CR-001.md
  → 架构 Agent 审核
  → 架构 Agent 修改 router.go + openapi.yaml
  → 提交并通知所有 Agent 拉取
  → 功能 Agent 继续

7.3 迁移串行化¶

迁移文件由架构 Agent 统一编号；
功能 Agent 需要新表/新列时，先提 CR；
迁移合并顺序按编号；
合并后立即在所有 worktree 中执行 make migrate-up；
禁止两个 Agent 同时生成同一编号的迁移。

8. 合并与集成¶

8.1 合并顺序¶

1. 共享基础（main/router/config/migrations）
2. 认证模块（US-001）
3. 项目/成员模块（US-002, US-003）
4. 任务模块（US-004, US-005）
5. 前端（按页面依赖）
6. 测试修复

8.2 合并前检查¶

8.3 冲突处理¶

不要让 Agent 自动“解决”冲突。 正确流程：

停止自动合并；
架构 Agent 判断冲突原因；
共享文件由架构 Agent 解决；
功能文件由对应 Agent 解决；
解决后重跑全量测试；
记录冲突和解决方案。

8.4 集成 Agent 的任务¶

你是集成工程师。请把以下分支按顺序合并到 integration 分支：
feat/US-001-login, feat/US-002-create-project, feat/US-003-invite-member, feat/US-004-create-task

要求：
1. 每次合并后运行 `make test` 和 `make lint`。
2. 冲突时停止，输出冲突文件和原因，不要盲目选择 ours/theirs。
3. 合并完成后运行全量测试和 `go test -race ./...`。
4. 更新 CSV 状态。
5. 生成集成报告 docs/03-dev/reports/integration-<date>.md。
6. 如果测试失败，定位到具体故事，通知对应 Agent，不要自己改业务逻辑。

9. 代码审查 Agent¶

9.1 审查清单¶

契约一致性

请求/响应字段与 OpenAPI 一致
错误码与统一错误模型一致
分页/排序/过滤符合规范
时间格式 UTC

业务正确性

权限校验在后端
对象级权限（不是只校验登录）
事务边界正确
幂等
并发安全（乐观锁/唯一约束）
边界条件（空、超长、非法枚举）

代码质量

测试质量

安全

9.2 审查提示词¶

你是资深代码审查员。请审查以下变更：
- git diff main...feat/US-004-create-task
- 对应故事：docs/00-discovery/user-story-details.md#us-004
- 契约：docs/01-design/api/openapi.yaml#createTask
- 实现细节：docs/01-design/feature-implementation.md#us-004

请按以下维度审查：
1. 契约一致性
2. 权限与安全
3. 事务/并发/幂等
4. 错误处理
5. 测试质量
6. 可观测性
7. 代码可维护性
8. 是否有未授权文件改动

输出：
- P0（必须修）：会导致数据错误/安全漏洞/线上故障
- P1（应该修）：明显缺陷/契约不一致/测试不足
- P2（建议）：可维护性/风格
每条给出文件、行号、问题、修复建议。
不要直接改代码。

9.3 审查 Agent 的权限¶

审查 Agent 应该只读，不能改代码。否则它会“顺手”修掉问题，绕过你的判断。

10. 上下文与成本控制¶

10.1 一个会话只做一个故事¶

❌ 一个会话做 US-001~US-005
✅ 一个会话做 US-004，完成后 /clear，再开 US-005

10.2 精确引用¶

❌ “帮我看看任务模块”
✅ “@docs/01-design/feature-implementation.md#us-004 实现 POST /tasks，
     只改 backend/internal/usecase/task/ 和 task_handler.go”

10.3 用搜索代替通读¶

先 rg "CreateTask" backend/ frontend/
再读命中的文件的相关行
不要一上来读整个仓库

10.4 用子 Agent 做脏活¶

搜索：让子 Agent 找文件，返回路径和摘要。
日志分析：让子 Agent 读 CI 日志，返回失败原因。
依赖分析：让子 Agent 查引用关系。

主会话只接收结论，保护上下文。

10.5 控制输出大小¶

测试输出只保留失败摘要：go test ./... 2>&1 | tail -50
日志用 rg 过滤：rg "ERROR|panic" logs/
不要把几千行 JSON 贴进对话。

10.6 什么时候重开会话¶

上下文超过一半；
AI 开始重复之前的错误；
话题从功能 A 跳到功能 B；
你发现它在“猜”而不是“读文件”。

重开后，让它先读 CLAUDE.md 和相关契约，再继续。

11. 常见故障与恢复¶

故障 1：Agent 改了不该改的文件¶

症状：diff 里出现 router.go、main.go、其他模块。

处理：

git checkout -- <file> 还原未授权改动；
检查是否因为任务书边界不清；
补充文件所有权或变更请求流程；
让 Agent 重新只改授权文件。

故障 2：测试一直不过，Agent 开始删测试¶

症状：测试文件被删除/跳过/断言被注释。

处理：

立即停止；
还原测试文件；
让 Agent 输出失败日志和假设；
人判断是测试错还是实现错；
修复后重新跑。

规则：禁止通过删除测试来让 CI 变绿。

故障 3：两个 Agent 改同一文件¶

症状：合并冲突，或者一方的改动消失。

处理：

停止合并；
确认文件所有权；
由架构 Agent 合并；
重跑全量测试；
更新所有权清单，避免再次发生。

故障 4：Agent 说“完成”，但功能不能用¶

症状：单测过了，E2E 失败。

处理：

按 DoD 检查缺失项；
让 Agent 用 Chrome MCP 走一遍；
补集成/E2E 测试；
不要把“单测通过”当成完成。

故障 5：上下文太长，AI 变糊涂¶

症状：重复问同样的问题、忘记契约、开始猜。

处理：

/clear 或开新会话；
让它先读 CLAUDE.md + 契约 + 当前故事；
用更小的任务重新开始；
把已完成部分写成摘要文件。

故障 6：Agent 擅自改契约¶

症状：OpenAPI/schema 出现未授权改动。

处理：

还原契约文件；
要求走 CR 流程；
审查是否因为契约本身有缺口；
补契约后再继续。

故障 7：并行 Agent 互相等待¶

症状：前端等后端接口，后端等前端字段。

处理：

契约已冻结的话，双方可以基于 mock 并行；
后端提供 mock server（OpenAPI 生成）；
前端用 MSW/本地 mock；
集成阶段再切真实接口。

12. 一个完整例子：US-004 的并行执行¶

12.1 准备¶

cd ~/projects/teamtask
git checkout main && git pull
git worktree add ../teamtask-worktrees/US-004 -b feat/US-004-create-task main
cd ../teamtask-worktrees/US-004

12.2 启动后端 Agent¶

tmux new -s US-004
claude

输入任务书（见模板/agent-brief.md），然后：

请开始。先阅读契约和实现细节，列出你的实现计划（不超过 10 步），
等我确认后再写代码。

确认计划后：

按计划执行。先写测试，再实现。每完成一个步骤，报告一次测试结果。
不要修改未授权文件。遇到契约问题立即停止。

12.3 启动前端 Agent（另一个 worktree）¶

git worktree add ../teamtask-worktrees/US-004-fe -b feat/US-004-create-task-ui main
cd ../teamtask-worktrees/US-004-fe
claude

前端任务书要点：

只改 frontend/src/components/task/CreateTaskModal.vue 和 ProjectBoardView.vue；
API 类型从 openapi-typescript 生成；
先用 mock 数据，接口就绪后切换；
处理 loading/error/成功；
写 Vitest 测试；
截图证据。

12.4 集成¶

cd ~/projects/teamtask
git checkout -b integration
git merge --no-ff feat/US-004-create-task
git merge --no-ff feat/US-004-create-task-ui
make test
make lint

12.5 E2E¶

./scripts/start-chrome-debug.sh
make dev

测试 Agent 用 Chrome MCP 执行 US-004 的 E2E，生成 manifest 和截图，再生成 Word 报告。

12.6 更新状态¶

python3 scripts/update_story_status.py \
  --file docs/00-discovery/user-story.csv \
  --story US-004 \
  --status qa_pass \
  --report docs/03-dev/reports/US-004-创建任务.md \
  --e2e-manifest docs/04-qa/manifests/US-004.json

13. 多 Agent 的“作战室”布局¶

13.1 tmux 布局¶

┌──────────────────────────┬──────────────────────────┐
│ pane 0: 架构/集成        │ pane 1: 后端 Agent A     │
│ 主仓库                   │ worktree US-001          │
├──────────────────────────┼──────────────────────────┤
│ pane 2: 后端 Agent B     │ pane 3: 前端 Agent       │
│ worktree US-002          │ worktree US-004-ui       │
└──────────────────────────┴──────────────────────────┘

13.2 看板¶

用一个简单的 docs/03-dev/board.md 或 CSV 视图：

TODO        DEV         UNIT_DONE    INTEG_DONE   QA_PASS
US-005      US-004      US-003       US-002       US-001
            US-006

13.3 每日同步¶

每天花 10 分钟：

看 CSV 状态；
看 CI；
看阻塞项；
调整并行度；
更新文件所有权（如果有变更）。

14. 成本与速度的现实预期¶

任务	AI 时间	人的时间
一个中等后端故事（含测试）	30-90 分钟	15-30 分钟审查
一个前端页面（含状态）	30-60 分钟	15-30 分钟视觉验收
一次 E2E + Word 报告	10-30 分钟	20-40 分钟走查
一次合并 + 全量测试	10-30 分钟	10 分钟处理冲突
一次部署 + 冒烟	10-20 分钟	10 分钟确认

真正的瓶颈通常不是 AI 写代码，而是：

等契约确认；
等环境/权限；
人没时间走查；
合并冲突；
E2E 登录/验证码；
生产发布审批。

优化这些环节，比让 AI 写得更快更有价值。

15. 本章交付清单¶

下一章：08 质量保证与 Word 验收报告 —— 用 Chrome MCP 做端到端验证，把每一步变成可核查的证据。