我怎么用 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：

1. 任务分解的质量决定 Agent Teams 的效果——花 30 分钟写一个清晰的任务分解文档，比直接丢一个模糊需求然后等 Agent 自己摸索，节省的成本可以是 10 倍。

2. 跨仓库协调的核心是共享文件，而非消息传递——Agent 之间的消息通信有信息损失的风险。关键数据（接口定义、数据格式、变更说明）写成文件，让所有 Teammate 直接读取。

3. Agent Teams 不是替代工程师，而是放大器——它擅长执行结构清晰的任务（重构、迁移、批量修改），但任务的定义、架构的决策、边界条件的判断，仍然需要人来做。最佳用法是人做设计和分解，Agent 做执行和验证。

你有没有试过用 Agent Teams 做多仓库项目？效果怎么样？欢迎分享你的经验。