❌ 不要一开始就构建复杂的代理系统
✅ 从简单的 Prompt 开始，优化评估后再增加复杂度
✅ 只有在简单方案不够时才添加多步骤代理系统

在 BrowseComp 评估中，三个因素解释了 95% 的性能方差：
- Token 使用量（80%）← 最重要！
- 工具调用次数
- 模型选择

结论：多代理架构通过分配工作到独立上下文窗口，
有效扩展 Token 使用量，突破单代理限制。

✅ 适合多代理：
- 任务可并行化
- 信息超过单上下文窗口
- 需要多种工具/视角

❌ 不适合多代理：
- 所有代理需共享相同上下文
- 代理间有大量依赖关系
- 大多数编码任务（并行化任务较少）

任务分解为固定步骤，每步处理上一步输出

适用场景：
- 任务可清晰分解为固定子任务
- 愿意用延迟换取更高准确性

示例：
输入 → LLM调用1 → 检查点 → LLM调用2 → 检查点 → 输出

分类输入，导向专门的处理流程

适用场景：
- 复杂任务有明确分类
- 不同类别需要不同处理

示例：
输入 → 分类器 → 路由到专门Prompt → 输出

多个 LLM 同时工作，结果聚合

两种变体：
- 分段：任务分成独立部分并行处理
- 投票：多个 LLM 尝试同一任务，取多数

适用场景：
- 子任务可并行化
- 需要多视角或多次尝试提高置信度

中央 LLM 动态分解任务，委托给 Worker LLM，综合结果

适用场景：
- 复杂任务无法预测子任务（如编程，文件数量和改动类型不确定）
- 需要灵活性而非预定义子任务

架构图：
┌─────────────────────────────────────────────────────┐
│                    Lead Agent                        │
│  (分析查询，制定策略，分配任务，综合结果)              │
└─────────────────┬───────────────────────────────────┘
                  │
    ┌─────────────┼─────────────┐
    ▼             ▼             ▼
┌────────┐   ┌────────┐   ┌────────┐
│Subagent│   │Subagent│   │Subagent│
│ (搜索) │   │ (编码) │   │ (测试) │
└────────┘   └────────┘   └────────┘
     │             │             │
     └─────────────┴─────────────┘
                   │
                   ▼
           Lead Agent 综合
                   │
                   ▼
             Reviewer 审查
                   │
                   ▼
               完成 ✓

- 代理使用约 4× Token（相比聊天）
- 多代理系统使用约 15× Token（相比聊天）
- 经济可行性要求任务价值足够高

一个 LLM 生成响应，另一个提供评估和反馈，循环迭代

这是 Claude Code 最推荐的模式！

适用场景：
- 有明确的评估标准
- 迭代改进有可衡量的价值
- LLM 响应可通过人类反馈改进

Token 使用量解释 80% 的性能方差

关键限制：
- 单次输出限制：25,000 tokens
- 评估最小样本：~20 个测试用例
- 中位数代理运行时间：~45 秒

## 输出优化

❌ 错误：返回全部数据
```json
{"data": [/* 1000 条记录 */]}

{
  "summary": "找到 1000 条记录",
  "page": 1,
  "per_page": 20,
  "items": [/* 20 条记录 */],
  "has_more": true
}

### 效率优化原则

```markdown
1. 分页获取大数据
2. 压缩输出返回摘要
3. 多次小搜索优于单次大搜索
4. 单次输出限制 25,000 tokens
5. 错误提示要明确具体

❌ 写了几行代码就标记完成
❌ 没有运行测试验证
❌ 没有人 review
❌ 遇到问题就跳过
❌ 会话结束进度丢失

TaskCreate 时必须包含：

TaskCreate(
  subject: "实现登录 API",
  description: `
    开发 POST /login 接口

    ## 完成标准（必须全部满足）
    - [ ] API 能响应 POST /login
    - [ ] 正确用户返回 JWT token
    - [ ] 错误密码返回 401
    - [ ] 单元测试通过

    ## 验证命令
    npm test
  `
)

团队成员:
- project-lead: 协调
- researcher: 调研
- coder: 编码
- reviewer: 审查 ← 必须！
- tester: 测试

Agent 完成工作
    ↓
不能直接标记 completed！
    ↓
必须发送消息给 reviewer 审查：
    SendMessage(
      type: "message",
      recipient: "reviewer",
      content: "任务 #X 请求审查..."
    )
    ↓
Reviewer 验证后回复：
    SendMessage(
      type: "message",
      recipient: "coder",
      content: "审查通过 ✅ / 不通过 ❌"
    )
    ↓
只有审查通过时才能 TaskUpdate(status: "completed")

## 自查清单

1. 我是否运行了相关测试？
2. 我是否验证了"完成标准"的每一项？
3. 我是否更新了相关文档？
4. 代码是否能正常编译/运行？
5. 是否有遗留的 TODO 或 FIXME？

**如果任何一项是"否"，不能标记完成！**

// .agent/progress.json
{
  "last_session": "2024-03-13T15:00:00",
  "completed": ["task-1", "task-2"],
  "in_progress": "task-3",
  "next_steps": ["完成 API 测试"],
  "notes": "登录逻辑已实现"
}

1. 读取 progress.json
2. 检查 TaskList
3. 找到 in_progress 的任务
4. 发送消息唤醒相关 Agent
5. 如果 Agent 已关闭，重新 spawn

团队成员:
- project-lead (team-lead): 协调进度、审阅代码
- researcher: 技术调研、方案设计
- coder-1: 前端开发
- coder-2: 后端开发
- reviewer: 代码审查 ← 必须
- tester: 测试验证

团队成员:
- project-lead: 统筹进度
- researcher: 资料收集、深度调研
- writer-1: 主要撰写
- writer-2: 辅助撰写
- editor: 审阅修订 ← 必须（相当于 reviewer）

团队成员:
- project-lead: 统筹方向
- researcher-1: 主要研究
- researcher-2: 辅助研究
- analyst: 数据分析
- reviewer: 结果验证 ← 必须

// 1. 创建团队
TeamCreate(
  team_name: "auth-system",
  description: "开发用户认证系统"
)

// 2. 创建任务（带完成标准）
TaskCreate(
  subject: "实现登录 API",
  description: `
    开发 POST /login 接口

    ## 完成标准
    - [ ] 返回 JWT token
    - [ ] 密码错误返回 401
    - [ ] 测试覆盖率 > 80%

    ## 验证命令
    npm test
    curl -X POST localhost:3000/login -d '{"user":"test","pass":"wrong"}'
  `,
  activeForm: "开发登录 API"
)

// 3. Spawn 团队成员
Agent(subagent_type: "general-purpose", name: "coder", team_name: "auth-system")
Agent(subagent_type: "general-purpose", name: "reviewer", team_name: "auth-system")
Agent(subagent_type: "general-purpose", name: "tester", team_name: "auth-system")

// 4. 分配任务
TaskUpdate(taskId: "1", owner: "coder")

┌─────────┐     ┌──────────┐     ┌─────────┐
│ Worker  │ ──→ │ Reviewer │ ──→ │ approve │ ──→ 完成
└─────────┘     └──────────┘     │ = true? │
     ↑               │           └─────────┘
     └───────────────┘
         approve = false (返回修改)

**禁止行为**：
- ❌ Worker 直接标记 completed
- ❌ 没有 Reviewer 就标记完成
- ❌ Reviewer 未通过就继续

**必须行为**：
- ✅ Worker 完成后发送 review 请求
- ✅ Reviewer 运行测试验证
- ✅ 只有 approve=true 才能 TaskUpdate(status: "completed")

## 审查清单

1. **功能验证**
   - [ ] 代码能否正常编译/运行？
   - [ ] 测试是否通过？
   - [ ] 完成标准是否全部满足？

2. **质量检查**
   - [ ] 代码风格是否一致？
   - [ ] 是否有 TODO/FIXME 遗留？
   - [ ] 是否遵循最佳实践？

3. **安全审查**
   - [ ] 是否有安全风险？
   - [ ] 敏感信息是否泄露？

当我认为任务完成时：

1. 先运行测试：npm test
2. 检查完成标准的每一项
3. 如果测试失败 → 修复 → 重新测试
4. 如果测试通过 → 发送 review 请求：

SendMessage(
  type: "message",
  recipient: "reviewer",
  content: """
  任务 #1 请求审查

  完成标准检查：
  - [x] 返回 JWT token
  - [x] 密码错误返回 401
  - [x] 测试覆盖率 85%

  验证命令：
  - npm test
  - npm run coverage

  文件变更：
  - src/auth/login.ts
  - tests/auth.test.ts
  """
)

5. 等待 reviewer 回复
6. 如果被拒绝 → 修复 → 重新请求审查
7. 如果通过 → TaskUpdate(status: "completed")

收到 review 请求后：

1. 读取相关文件
2. 运行测试：npm test
3. 检查代码质量
4. 回复：

如果通过：
SendMessage(
  type: "message",
  recipient: "coder",
  content: "审查通过 ✅\n\n所有测试通过，代码质量良好。\n\n你可以标记任务完成了。"
)

如果不通过：
SendMessage(
  type: "message",
  recipient: "coder",
  content: "审查不通过 ❌\n\n问题：\n1. 测试用例缺少边界情况\n2. 缺少错误处理\n\n请修复后重新提交审查。"
)

project/
├── .agent/
│   ├── progress.json        # 进度追踪
│   ├── feature_list.json    # 功能列表
│   └── session.log          # 会话日志
├── research/                # 研究资料
├── drafts/                  # 草稿/开发中
├── review/                  # 审阅中
└── completed/               # 已完成

{项目目录}/.agent/progress.json
{项目目录}/.agent/feature_list.json

~/.claude/teams/{project-hash}/config.json

# 1. 读取进度
cat .agent/progress.json

# 2. 读取任务列表
TaskList

# 3. 检查团队状态
Read ~/.claude/teams/{team-name}/config.json

# 4. 选择下一个任务
# 优先选择：pending + 无 owner + 无 blockedBy

# 新会话开始

1. 读取 ~/.claude/teams/auth-system/progress.json
   → in_progress: "task-3"
   → next_steps: ["完成 API 测试"]

2. 检查 TaskList
   → task-3 status: in_progress, owner: coder

3. 检查 team config
   → coder: 已关闭

4. 重新 spawn coder
   Agent(subagent_type: "general-purpose", name: "coder", team_name: "auth-system")

5. 发送恢复消息
   SendMessage(
     recipient: "coder",
     content: "继续工作：task-3\n\n下一步：完成 API 测试\n\n上次进度：登录逻辑已实现"
   )

cd {项目目录}
git init
git add .
git commit -m "初始化项目"

任务开始 → git commit -m "开始: {任务名}"
任务完成 → git commit -m "完成: {任务名}"
重要修改 → git commit -m "更新: {修改描述}"
会话结束 → git commit -m "进度: 保存会话进度"

早期代理开发中，变化有巨大影响：
- 一个提示调整可能从 30% 提升到 80%
- 只需要约 20 个测试用例
- 不要等到有几百个测试用例才开始

最佳实践：小规模测试立即开始，而非延迟

使用 LLM 评估输出的标准：
- 事实准确性（声明是否匹配来源？）
- 引用准确性（引用来源是否匹配声明？）
- 完整性（是否覆盖所有请求方面？）
- 来源质量（是否使用主要来源？）
- 工具效率（工具使用是否合理？）

推荐：单个 LLM 调用输出 0.0-1.0 分数和通过/失败

- 代理可能运行很长时间
- 小错误可能导致代理探索完全不同的轨迹
- 需要能够从错误发生点恢复
- 让代理知道工具失败并让其适应

代理是非确定性的，相同提示可能产生不同结果

解决方案：
- 完整的生产追踪
- 监控代理决策模式
- 不监控对话内容（保护隐私）