我怎么用 Claude Code Agent Teams 做多仓库项目
开场
上个月我用 Claude Code Agent Teams 做了一个涉及 3 个仓库的重构项目：一个 Python 后端、一个 TypeScript 前端、一个共享的 protobuf 定义库。按传统方式需要一个工程师一周的工作量，Agent Teams 用 4 小时完成了，API 成本 $47。这篇文章详细拆解 Agent Teams 的工作机制，以及我怎么在实际项目中用它做多仓库协调。
问题背景
多仓库项目的核心难题是协调：改了 protobuf 定义，前后端代码都要同步更新。改了 API 接口，所有调用方都要适配。传统做法是一个人跨仓库切换，人肉保持一致性。这个过程枯燥、容易出错、极度消耗注意力。
Agent Teams 提供了另一种思路：让多个 Claude Code 实例各自负责一个仓库（或一个模块），通过 Lead-Teammate 模式协调工作。
Claude Code Agent Teams 目前是实验性功能，默认关闭。但从我的实际使用来看，它在结构清晰的多仓库项目中已经非常可用。
核心架构
Agent Teams 工作模型
┌──────────────┐
│ Lead Agent │
│ (协调者) │
└──────┬───────┘
│
┌────────────┼────────────┐
│ │ │
┌──────▼──────┐┌────▼────┐┌─────▼─────┐
│ Teammate A ││ B ││ C │
│ (后端仓库) ││(前端) ││(Proto) │
└─────────────┘└─────────┘└───────────┘
│ │ │
┌──────▼──────┐┌────▼────┐┌─────▼─────┐
│ backend/ ││frontend/││ protos/ │
│ repo ││ repo ││ repo │
└─────────────┘└─────────┘└───────────┘
Lead Agent：负责任务分解、进度追踪、结果汇总。它不直接写代码，而是把任务分配给 Teammate。
Teammate Agent：每个 Teammate 独立运行在自己的 context window 里，可以读写文件、运行命令、执行测试。Teammate 之间可以互相发消息。
Task System：团队共享一个任务列表，支持依赖关系追踪。当一个 blocking task 完成后，依赖它的下游任务自动解锁。
开启方式
// settings.json 或环境变量
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}
}
实现细节
Step 1: 规划任务结构
在启动 Agent Teams 之前，你需要给 Lead Agent 一个清晰的任务说明。这是最关键的步骤——任务描述的质量直接决定了整个团队的执行效果。
我给 Lead Agent 的初始 prompt：
项目：将用户认证系统从 session-based 迁移到 JWT-based。
涉及仓库：
1. protos/ - 共享的 protobuf 定义（需要新增 JWT token 相关 message）
2. backend/ - Python FastAPI 后端（需要实现 JWT 签发和验证）
3. frontend/ - TypeScript React 前端（需要替换 cookie 认证为 Bearer token）
约束：
- protos 变更必须先完成，后端和前端依赖它
- 后端变更完成后，前端才能开始集成测试
- 所有仓库的现有测试必须继续通过
- 不要修改数据库 schema
请分解任务并分配给团队成员。
Lead Agent 会自动把这些任务分解成更小的子任务，并设置依赖关系。
Step 2: Teammate 配置
每个 Teammate 需要在对应仓库的 CLAUDE.md 中提供充分的上下文：
# backend/ 仓库的 CLAUDE.md
## 技术栈
- Python 3.12, FastAPI, SQLAlchemy
- 测试: pytest
- 认证: 当前是 session-based (见 auth/session.py)
## 关键文件
- auth/session.py - 当前认证逻辑
- auth/middleware.py - 认证中间件
- tests/test_auth.py - 认证测试
## 运行命令
- 测试: pytest tests/
- 类型检查: mypy src/
- 服务启动: uvicorn main:app --reload
Step 3: 实际执行过程
我观察到 Lead Agent 的实际任务分配：
Phase 1（Teammate C 独立工作）：
Task 1: [C - Proto] 新增 JWTToken message 和 AuthResponse message
Task 2: [C - Proto] 生成 Python 和 TypeScript 代码并提交
Phase 2（Teammate A、B 并行，依赖 Phase 1）：
Task 3: [A - Backend] 实现 JWT 签发逻辑 (jwt_issuer.py)
Task 4: [A - Backend] 实现 JWT 验证中间件
Task 5: [A - Backend] 更新现有 API endpoint 使用新认证
Task 6: [B - Frontend] 实现 token 存储和刷新逻辑
Task 7: [B - Frontend] 替换 axios 请求拦截器
Phase 3（依赖 Phase 2）：
Task 8: [A - Backend] 运行全量测试并修复失败
Task 9: [B - Frontend] 运行 E2E 测试并修复失败
Task 10: [Lead] 汇总所有变更，验证跨仓库一致性
Step 4: 跨仓库协调的关键——消息机制
Agent Teams 的消息系统是协调多仓库工作的核心。当 Teammate C 完成了 protobuf 定义后，它会通知 Lead：
[Teammate C → Lead]:
Proto 定义已更新。新增了以下 message:
- JWTToken (fields: access_token, refresh_token, expires_at)
- AuthResponse (fields: user_id, token, permissions)
生成的代码路径:
- Python: generated/auth_pb2.py
- TypeScript: generated/auth.ts
Lead 收到后，把相关信息转发给 Teammate A 和 B，它们基于这些信息开始各自的工作。
Step 5: 实际代码示例
Teammate A 在后端仓库生成的 JWT 验证中间件：
# auth/jwt_handler.py
import jwt
from datetime import datetime, timedelta, timezone
from fastapi import HTTPException, Security
from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
security = HTTPBearer()
JWT_SECRET = "..." # 实际从环境变量读取
JWT_ALGORITHM = "HS256"
ACCESS_TOKEN_EXPIRE_MINUTES = 30
def create_access_token(user_id: str, permissions: list[str]) -> str:
"""签发 JWT token"""
payload = {
"sub": user_id,
"permissions": permissions,
"exp": datetime.now(timezone.utc) + timedelta(minutes=ACCESS_TOKEN_EXPIRE_MINUTES),
"iat": datetime.now(timezone.utc)
}
return jwt.encode(payload, JWT_SECRET, algorithm=JWT_ALGORITHM)
async def verify_token(
credentials: HTTPAuthorizationCredentials = Security(security)
) -> dict:
"""验证 JWT token 的 FastAPI 依赖"""
try:
payload = jwt.decode(
credentials.credentials,
JWT_SECRET,
algorithms=[JWT_ALGORITHM]
)
if payload["exp"] < datetime.now(timezone.utc).timestamp():
raise HTTPException(status_code=401, detail="Token 已过期")
return payload
except jwt.InvalidTokenError:
raise HTTPException(status_code=401, detail="无效的 Token")
实战经验
生产数据
| 指标 | 数值 |
|---|---|
| 总耗时 | 3 小时 52 分 |
| API 成本 | $47（Sonnet 4.5 为主） |
| Lead 消耗 token | ~85,000 input / ~22,000 output |
| 每个 Teammate 消耗 | ~120,000 input / ~45,000 output |
| 生成/修改文件数 | 34 个 |
| 测试通过率 | 最终 100%（中间有 3 轮修复） |
| 人工干预次数 | 2 次（一次修正依赖版本，一次调整 token 过期策略） |
对比人工：一个熟悉这三个仓库的工程师估计需要 5-7 天完成同样的工作。成本 $47 vs 一周工程师薪资。
踩过的坑
坑 1：任务分解太粗会导致 Teammate 迷失。 最初我只给了一个大任务 "迁移后端认证到 JWT"，Teammate A 花了大量 token 在探索代码上，反复读取不相关的文件。改成精确的子任务后（"修改 auth/middleware.py，替换 session 验证为 JWT 验证"），效率提升了 3 倍。
坑 2：多仓库 worktree 管理。 Agent Teams 默认在当前目录工作。处理多仓库时，我需要提前把三个仓库 clone 到同一个父目录下，并在 Lead 的 prompt 里明确说明路径结构。
坑 3：Teammate 之间的消息可能延迟。 Teammate C 完成后发消息给 Lead，Lead 再转发给 A 和 B。这个链路有时候会出现信息丢失（Lead 没有把关键细节转发）。解决方案：要求 Teammate 把关键输出写入共享文件（比如 shared/proto_changes.md），其他 Teammate 直接读取文件。
适用范围
适合 Agent Teams 的场景：
- 涉及 2-5 个仓库的协调变更
- 任务可以清晰分解为独立子任务
- 有明确的依赖关系（A 先做完，B 才能开始）
不适合的场景：
- 单仓库内的工作——直接用一个 Claude Code 实例更高效
- 高度耦合的代码变更——如果每个 Teammate 的修改互相影响，协调成本会超过收益
- 需要频繁人工决策的工作——Agent Teams 适合执行，不适合需要大量判断的设计工作
总结
三条核心 takeaway：
-
任务分解的质量决定 Agent Teams 的效果——花 30 分钟写一个清晰的任务分解文档，比直接丢一个模糊需求然后等 Agent 自己摸索，节省的成本可以是 10 倍。
-
跨仓库协调的核心是共享文件，而非消息传递——Agent 之间的消息通信有信息损失的风险。关键数据（接口定义、数据格式、变更说明）写成文件，让所有 Teammate 直接读取。
-
Agent Teams 不是替代工程师，而是放大器——它擅长执行结构清晰的任务（重构、迁移、批量修改），但任务的定义、架构的决策、边界条件的判断，仍然需要人来做。最佳用法是人做设计和分解，Agent 做执行和验证。
你有没有试过用 Agent Teams 做多仓库项目？效果怎么样？欢迎分享你的经验。