Claude Code Agent Teams多会话协作自动化实战

claude --version
# 确保输出 >= 2.1.154

graph TB
    subgraph "Agent Teams 架构"
        TM[Team Manager<br/>主会话] -->|创建任务| T1[Agent A<br/>前端开发]
        TM -->|创建任务| T2[Agent B<br/>后端开发]
        TM -->|创建任务| T3[Agent C<br/>测试验证]
        T1 -.->|邮箱消息| T2
        T2 -.->|邮箱消息| T3
        T3 -.->|邮箱消息| TM
    end

    subgraph "核心机制"
        MB[Peer-to-Peer Mailbox]
        TB[共享Task Board]
        TF[共享Tools/MCP]
    end

    T1 & T2 & T3 --> MB
    TM & T1 & T2 & T3 --> TB
    T1 & T2 & T3 --> TF

# 方法一：通过 /config 命令
claude
# 进入交互模式后输入 /config
# 选择 "Enable experimental features" → 勾选 "Agent Teams"

# 方法二：手动编辑 settings.json
# 全局配置路径: ~/.claude/settings.json
# 项目配置路径: .claude/settings.json

# 在 settings.json 中添加：

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "true"
  }
}

# 启动Claude Code后，检查是否看到Agent Teams相关提示
claude
# 如果启用成功，/agent-teams 命令将可用
# 或者在Team Manager会话中可以直接使用Team相关的指令

sequenceDiagram
    participant User
    participant Manager as Team Manager
    participant Alpha as Agent Alpha<br/>架构师
    participant Beta as Agent Beta<br/>实现者
    participant Gamma as Agent Gamma<br/>质检员

    User->>Manager: 启动团队 / 开始项目
    Manager->>Alpha: 分配架构设计任务
    Manager->>Beta: 等待架构完成
    Manager->>Gamma: 等待实现完成

    Alpha->>Alpha: 设计项目结构和API接口
    Alpha->>Manager: 架构设计完成
    Alpha->>Beta: 📬 发送架构文档

    Beta->>Beta: 基于架构实现代码
    Beta->>Manager: 实现完成
    Beta->>Gamma: 📬 发送代码审查请求

    Gamma->>Gamma: 审查代码 + 运行测试
    Gamma->>Manager: 审查报告
    Gamma-->>Beta: 📬 反馈修改建议

    Beta->>Beta: 修复问题
    Beta->>Manager: 最终版本完成
    Manager->>User: 项目交付

# Team Protocol

## Agent Roles

### Alpha - Architect
- Design project structure and API interfaces
- Define data models and schemas
- Create technical design documents
- Notify Beta when architecture is ready

### Beta - Implementer
- Wait for architecture from Alpha before coding
- Implement features based on Alpha's design
- Write unit tests for own code
- Request code review from Gamma

### Gamma - QA Inspector
- Review all code submissions
- Run test suites and report results
- Send feedback to Beta for fixes
- Final sign-off before delivery

## Communication Protocol
- Use TeammateTool to send messages between agents
- Tag messages with [URGENT] for blocking issues
- Report completion to Team Manager
- Daily summary at end of session

# 在项目目录下启动Claude Code
cd /path/to/your-project
claude

> 启动一个3人Agent Team来开发用户管理API服务：
> - Agent Alpha：负责项目架构设计和API接口定义
> - Agent Beta：负责代码实现
> - Agent Gamma：负责代码审查和测试
> 
> 请先让Alpha完成架构设计，然后Beta基于架构实现，最后Gamma审查。
> 所有Agent之间通过TeammateTool通信协调。

# start_team.py - 使用Claude Agent SDK启动团队
import asyncio
from claude_agent_sdk import ClaudeCode

async def main():
    # 初始化Team Manager
    manager = ClaudeCode(
        prompt="""Create and manage an Agent Team with 3 agents:
        1. Alpha (Architect) - design API structure
        2. Beta (Implementer) - write code  
        3. Gamma (QA) - review and test

        Coordinate their work using TeammateTool.
        Project: User Management REST API with Express.js""",
        working_directory="/path/to/project",
        experimental_flags=["agent_teams"]
    )

    result = await manager.run()
    print(result)

asyncio.run(main())

# 在Claude Code交互模式中
# 按快捷键查看Agent面板（具体快捷键取决于版本）
# 或使用命令：
> /agents

# 输出示例：
# ┌─────────────────────────────────────┐
# │ Agent Team Status                    │
# ├──────────┬──────────┬───────────────┤
# │ Agent    │ Status   │ Current Task  │
# ├──────────┼──────────┼───────────────┤
# │ Alpha    │ ✅ Done  │ Architecture  │
# │ Beta     │ 🔄 Active│ Implementing  │
# │ Gamma    │ ⏳ Wait  │ Review Queue  │
# │ Manager  │ 🔄 Active│ Coordinating  │
# └──────────┴──────────┴───────────────┘

graph LR
    subgraph "会话生命周期 Hooks"
        A[SessionStart] --> B[UserPromptReceived]
        B --> C[PreToolUse]
        C --> D[工具执行]
        D --> E[PostToolUse]
        E --> F[AgentMessage<br/>发送给队友]
        F --> G[Stop]
    end

    subgraph "团队级别 Hooks"
        H[TeamAgentSpawn<br/>新Agent加入]
        I[TeamMessage<br/>团队消息]
        J[TaskUpdate<br/>任务状态变更]
    end

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "true"
  },
  "hooks": {
    "SessionStart": [
      {
        "matcher": "",
        "command": "echo 'Agent session started at $(date)' >> .claude/team-log.txt"
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "npx prettier --check $CLAUDE_FILE_PATH 2>/dev/null || echo 'Format check needed'"
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "npx eslint $CLAUDE_FILE_PATH --fix 2>/dev/null; echo 'Linted: '$CLAUDE_FILE_PATH"
      },
      {
        "matcher": "Bash",
        "command": "if echo $CLAUPE_OUTPUT | grep -q 'test failed'; then echo 'ALERT: Test failure detected'; fi"
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "command": "echo 'Agent stopped. Final status check.' >> .claude/team-log.txt"
      }
    ]
  }
}

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "url": "https://hooks.slack.com/services/YOUR/WEBHOOK/URL",
        "method": "POST",
        "headers": {
          "Content-Type": "application/json"
        },
        "body": {
          "text": "Agent ${CLAUDE_AGENT_ID} modified ${CLAUDE_FILE_PATH}"
        }
      }
    ]
  }
}

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write",
        "prompt": "Review the code change about to be written. If it introduces any SQL injection vulnerabilities or uses eval() with user input, block the operation by responding with 'BLOCK: security issue detected'. Otherwise respond with 'APPROVE'."
      }
    ]
  }
}

# Hook可用的关键环境变量：
$CLAUDE_SESSION_ID    # 当前会话ID
$CLAUDE_AGENT_ID      # 当前Agent标识
$CLAUDE_FILE_PATH     # 操作的文件路径（Write/Edit时）
$CLAUDE_TOOL_NAME     # 触发的工具名称

# stdin接收的JSON结构：
{
  "tool_name": "Write",
  "tool_input": {
    "file_path": "/src/api/users.js",
    "content": "..."
  },
  "session_id": "abc-123",
  "agent_id": "beta-implementer"
}

# 在Claude Code交互模式中：
# 每10分钟检查一次PR状态
> /loop 10m 请检查所有开放的Pull Request，为每个PR生成审查摘要

# 每小时运行测试套件
> /loop 1h 运行完整测试套件，报告失败用例数量和详情

# 工作日每天早上9点生成日报
> /schedule "0 9 * * 1-5" 生成昨日开发进度报告，包含各Agent的任务完成情况

# 让Team Manager每天早上检查团队状态
# Cron表达式格式: 分 时 日 月 周（用户本地时区）

# 每工作日早上8:57检查项目健康度
CronCreate:
  cron: "57 8 * * 1-5"
  prompt: "检查项目CI状态、开放的Issue数量、代码覆盖率，生成晨报摘要"
  recurring: true
  durable: true    # 持久化到 .claude/scheduled_tasks.json

# 一次性提醒：下午3点提醒部署
CronCreate:
  cron: "0 15 11 6 *"    # 6月11日15:00
  prompt: "准备v2.0版本部署，检查所有Agent的任务完成状态"
  recurring: false

.claude/
├── scheduled_tasks.json    # 持久化调度任务
├── settings.json           # 项目配置 + Hooks
└── team-log.txt            # 团队运行日志

{
  "tasks": [
    {
      "id": "cron_abc123",
      "cron": "57 8 * * 1-5",
      "prompt": "检查项目CI状态...",
      "recurring": true,
      "created_at": "2026-06-11T08:57:00Z",
      "last_run": "2026-06-11T08:57:00Z"
    }
  ]
}

# Agent正在等待CI构建完成
# 不要短间隔轮询（浪费缓存），使用合理的等待间隔

ScheduleWakeup:
  delaySeconds: 270      # 4.5分钟，保持在5分钟缓存TTL内
  reason: "等待CI构建完成，270秒后检查状态"
  prompt: "检查CI构建状态，如果完成则通知Team Manager"

# 基本headless模式启动
claude -p "启动Agent Team完成以下任务：分析src/目录下的所有文件，识别代码异味，
为每个有问题的文件创建修复计划，然后分配给Agent Team执行修复"

# 带JSON输出的结构化模式
claude -p "分析项目依赖树，检查安全漏洞" \
  --output-format json \
  --max-turns 20

# 从文件读取prompt
cat team-mission.txt | claude -p -

# .github/workflows/agent-team-review.yml
name: Agent Team Code Review

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  agent-review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Claude Code
        run: |
          npm install -g @anthropic-ai/claude-code
          echo "${{ secrets.CLAUDE_API_KEY }}" | claude auth login --api-key

      - name: Enable Agent Teams
        run: |
          mkdir -p .claude
          cat > .claude/settings.json << 'EOF'
          {
            "env": {
              "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "true"
            },
            "hooks": {
              "PostToolUse": [{
                "matcher": "Write|Edit",
                "command": "npx prettier --write $CLAUDE_FILE_PATH 2>/dev/null"
              }]
            }
          }
          EOF

      - name: Run Agent Team Review
        env:
          CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS: "true"
        run: |
          claude -p "
          你是一个代码审查团队的Manager。请启动一个3人Agent Team：
          1. Security Reviewer - 检查安全漏洞
          2. Performance Reviewer - 检查性能问题
          3. Style Reviewer - 检查代码风格和最佳实践

          分析PR #${{ github.event.pull_request.number }}的所有变更文件。
          每个Agent独立审查后，汇总审查报告。
          " --output-format json > review-report.json

      - name: Post Review Comments
        if: always()
        run: |
          # 解析review-report.json并发布PR评论
          claude -p "将review-report.json中的审查结果整理为GitHub PR评论格式" \
            --output-format text | gh pr comment ${{ github.event.pull_request.number }} --body-file -

#!/bin/bash
# batch-process.sh - 批量文件处理管道

FILES=$(find ./src -name "*.ts" -type f)

# Phase 1: 分析所有文件
echo "$FILES" | while read file; do
  claude -p "分析文件 $file 的代码质量，输出JSON格式的分析结果" \
    --output-format json \
    --max-turns 5 >> analysis-results.jsonl
done

# Phase 2: 基于分析结果批量修复
claude -p "
读取 analysis-results.jsonl 中的所有分析结果。
启动Agent Team并行修复所有标记为'high-priority'的问题。
每个Agent负责一个模块目录。
" --max-turns 50

# Phase 3: 验证修复
claude -p "运行完整测试套件，确认所有修复没有引入新问题" \
  --output-format json > verification-report.json

# Team Manager发送广播
TeammateTool:
  action: broadcast
  message: "注意：API接口规范已更新，请查看最新版CLAUDE.md"

# Beta直接联系Gamma
TeammateTool:
  target: gamma-qa
  message: "[REVIEW REQUEST] 用户注册模块已完成，请审查 src/users/register.ts"

# Alpha创建任务并分配
TaskCreate:
  subject: "实现用户认证中间件"
  description: "基于JWT的认证中间件，需支持token刷新"
  assignee: beta-implementer
  priority: high

# Beta认领任务
TaskUpdate:
  taskId: "task_001"
  status: in_progress
  owner: beta-implementer

graph TB
    subgraph "容错层次"
        L1["Level 1: Hook拦截<br/>PreToolUse阻止危险操作"]
        L2["Level 2: Agent自愈<br/>遇到错误自动重试/调整"]
        L3["Level 3: Manager监控<br/>检测Agent超时/失败"]
        L4["Level 4: 人工介入<br/>Manager请求用户指导"]
    end

    L1 --> L2 --> L3 --> L4

## Error Handling Protocol

- 每个Agent单任务最大执行时间：30分钟
- 遇到测试失败：自动重试1次，仍失败则通知Gamma
- 遇到依赖冲突：通知Manager协调
- Agent连续3次失败：Manager介入或请求人工帮助
- 代码冲突：优先保留最新变更，通知原作者Review

# 为每个Agent创建独立Worktree
# 在CLAUDE.md中声明：

## Worktree Strategy

Each agent MUST work in its own worktree:
- Alpha: .claude/worktrees/architecture/
- Beta: .claude/worktrees/implementation/
- Gamma: .claude/worktrees/testing/

When an agent finishes, it commits to its branch.
The Manager merges branches after review.

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "",
        "command": "git worktree add .claude/worktrees/$CLAUDE_AGENT_ID -b agent/$CLAUDE_AGENT_ID 2>/dev/null || true"
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "command": "cd .claude/worktrees/$CLAUDE_AGENT_ID && git add -A && git commit -m 'Agent $CLAUDE_AGENT_ID completed tasks' --allow-empty 2>/dev/null || true"
      }
    ]
  }
}

.claude/
├── settings.json           # Hooks + 环境变量
├── scheduled_tasks.json    # 持久化调度
├── CLAUDE.md               # 团队协议
└── team-log.txt            # 运行日志

# Code Health Patrol Team

## Team Structure
- **Patrol Manager**: 协调所有巡检任务，处理Critical告警
- **Dep Scout**: 依赖安全检查专家，运行 npm audit / pip audit
- **Tech Debt Analyst**: 技术债务分析师，检查代码复杂度和覆盖率
- **PR Reviewer**: 自动PR审查，检查代码风格、安全、性能

## Alert Levels
- CRITICAL: 安全漏洞(CVE)、生产中断 → 立即通知Manager
- WARNING: 技术债务增加、覆盖率下降 → 记录到报告
- INFO: 依赖更新可用、小优化建议 → 每日汇总

## Notification
- CRITICAL: 发送到 #ops-alerts Slack频道
- Daily Summary: 发送到 #dev-standup 频道

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "true"
  },
  "hooks": {
    "SessionStart": [
      {
        "matcher": "",
        "command": "echo '[$(date -Iseconds)] Agent session started' >> .claude/team-log.txt"
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "prompt": "If the bash command involves 'rm -rf' or 'DROP TABLE' or force-pushing to main, respond with 'BLOCK: dangerous operation prevented'. Otherwise respond 'APPROVE'."
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Bash",
        "command": "if echo \"$CLAUDE_OUTPUT\" | grep -qi 'critical\\|vulnerability\\|CVE'; then echo 'SECURITY_ALERT' >> .claude/team-log.txt; fi"
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "command": "echo '[$(date -Iseconds)] Agent session ended' >> .claude/team-log.txt"
      }
    ]
  },
  "permissions": {
    "allow": [
      "Bash(npm audit*)",
      "Bash(npm outdated*)",
      "Bash(npx eslint*)",
      "Bash(git log*)",
      "Bash(git diff*)"
    ]
  }
}

# 方式一：交互式启动（开发/调试用）
claude
# > 启动Code Health Patrol Team。Dep Scout检查依赖安全，
# > Tech Debt Analyst分析代码复杂度，PR Reviewer等待新PR。
# > 发现CRITICAL问题立即通知。

# 方式二：Headless模式（生产运行）
nohup claude -p "
启动Code Health Patrol Team进行日常巡检。
Dep Scout执行完整依赖安全扫描。
Tech Debt Analyst检查过去24小时新增代码的复杂度。
汇总报告输出到 .claude/daily-report.md。
" --output-format json >> .claude/patrol-output.jsonl 2>&1 &

# 方式三：定时调度（推荐）
# 在Claude Code会话中设置cron：
# /loop 8h 执行日常代码健康巡检

# 检查团队日志
cat .claude/team-log.txt
# 预期输出：
# [2026-06-11T08:57:00+08:00] Agent session started
# [2026-06-11T08:57:12+08:00] Agent session started  
# [2026-06-11T08:58:30+08:00] SECURITY_ALERT
# [2026-06-11T09:12:45+08:00] Agent session ended

# 查看日常报告
cat .claude/daily-report.md

# 确认环境变量已设置
cat .claude/settings.json | grep AGENT_TEAMS
# 确认版本 >= 2.1.154
claude --version
# 尝试重启Claude Code

# 限制最大turns
claude -p "..." --max-turns 15

# 使用Haiku模型处理简单任务
claude -p "运行npm audit并汇报结果" --model haiku

# 精简prompt，减少context
claude -p "Quick security scan" --max-turns 5

// 在Hook中自动续期
{
  "hooks": {
    "Stop": [{
      "matcher": "",
      "command": "echo 'Recreating scheduled task...' && claude -p '/schedule \"57 8 * * 1-5\" 日常巡检' --max-turns 1"
    }]
  }
}

graph TB
    subgraph "Claude Code Agent Teams 自动化体系"
        direction TB

        subgraph "调度层"
            CRON["/loop<br/>CronCreate"]
            WAKE["ScheduleWakeup<br/>动态节奏"]
        end

        subgraph "编排层"
            MGR["Team Manager<br/>主会话"]
            TM["TeammateTool<br/>P2P通信"]
            TB["Shared Task Board<br/>任务看板"]
        end

        subgraph "执行层"
            A1["Agent A<br/>Worktree隔离"]
            A2["Agent B<br/>Worktree隔离"]
            A3["Agent C<br/>Worktree隔离"]
        end

        subgraph "自动化层"
            H1["PreToolUse<br/>安全拦截"]
            H2["PostToolUse<br/>自动格式化"]
            H3["SessionStart<br/>环境初始化"]
            H4["Stop<br/>结果汇报"]
        end

        subgraph "集成层"
            CI["GitHub Actions<br/>CI/CD"]
            SL["Slack/Discord<br/>通知"]
            LOG["Team Log<br/>审计追踪"]
        end

        CRON --> MGR
        WAKE --> MGR
        MGR --> TM
        MGR --> TB
        TM --> A1 & A2 & A3
        TB --> A1 & A2 & A3
        A1 & A2 & A3 --> H1 & H2 & H3 & H4
        H2 --> CI
        H4 --> SL
        H3 --> LOG
    end