# Cost & Token Budget Baseline

Agent Team 是吞 token 最快的协作形态——多个 teammate 各持独立上下文 × 长会话 × 多轮对话，单功能消耗很容易冲到几百万 token。本基线规定团队必须遵守的预算纪律与可验证的事后核账机制。

## 预算分级（默认值，项目可在 CLAUDE.md 覆盖）

| 任务规模 | 单次会话 token 上限（输入+输出合计） | 触发提示 | 触发硬停 |
|---|---|---|---|
| 小（单文件 / bugfix / 查询） | 100k | 80k | 150k |
| 中（功能开发 / 跨模块重构） | 500k | 400k | 800k |
| 大（完整 feature / 跨链路 PRD→UAT） | 2M | 1.6M | 3M |

> 这是**对话窗口**预算，不是 API 总账户预算。账户级预算由账单系统单独控制。

## 角色级纪律

- **product-lead**：每次拆任务前评估规模等级；规模超「中」必须在 PRD 顶部声明预估 token 与成本
- **tech-lead / 执行层**：发现自己即将超过单次「触发提示」阈值时主动 SendMessage product-lead 汇报进度并请示是否继续
- **任何 agent**：撞到「触发硬停」阈值时必须立即停下，不得自作主张续跑

## Cache 利用率（必须 ≥ 60%）

- 高 cache miss 是模板化文档过长 / agent 频繁切换造成的；连续两次会话 cache hit < 50% 应触发优化
- 优化路径：把不常变的内容下沉到 skill / `.claude/standards/`、避免在 CLAUDE.md 反复修改大段
- Sub-agent progress summaries 自 Claude Code 2.1.128 起走 prompt cache（`cache_creation` ~3× 减少），并在 idle subagent 上不再重复触发——Parallel Dispatch 多 teammate 场景的成本基线随之下移，看历史月度账单时若 sub-agent 占比突然下降无需调查
- 参考：[Anthropic Prompt Caching](https://docs.claude.com/en/docs/build-with-claude/prompt-caching)、[Reduce Token Usage](https://code.claude.com/docs/en/costs#reduce-token-usage)

## 模型降级路径（建议）

不是所有任务都需要 Opus。当 product-lead 判断任务足够明确、不涉及架构权衡时，鼓励 teammate 主动降级到 Sonnet 甚至 Haiku：

| 任务特征 | 推荐模型 |
|---|---|
| 架构决策 / 复杂权衡 / brainstorm | Opus |
| 标准 CRUD / 文档撰写 / 代码评审 | Sonnet |
| 文本提取 / 简单格式化 / 测试样板 | Haiku |

降级是工具，不是义务——若 Sonnet 多次产出不达预期，立即升回 Opus 不要硬撑。

## Agent 默认 Model 路由（基线）

下表是 14 个 agent 的默认 model 选型与理由。任意调整需在 PRD 顶部备注复核效果：

| Agent | Model | 选型理由 |
|---|---|---|
| product-lead | opus | 编排者，需求理解 + 多 agent 协调 + UAT 业务判断 |
| tech-lead | opus | 架构权衡 + ADR 撰写 + 版本查证决策 |
| ai-agent-dev | opus | LLM/prompt 设计风险高，guardrail 与 jailbreak 防御需深度推理 |
| backend-dev | sonnet | 标准 API/迁移/认证开发 |
| frontend-dev | sonnet | 标准 UI/状态/对接开发 |
| ml-engineer | sonnet | 推理服务接入 + Pipeline 编排（架构权衡升级到 tech-lead） |
| uiux-designer | sonnet | HTML 原型 + 视觉判断；haiku 视觉表达力不足 |
| qa-engineer | sonnet | 测试判断与失败诊断需推理深度 |
| code-reviewer | sonnet | 缺陷判断 + 安全审计，下沉 haiku 风险高 |
| miniapp-dev | sonnet | 与 frontend-dev 同档 |
| miniapp-qa-engineer | sonnet | 与 qa-engineer 同档 |
| miniapp-code-reviewer | **haiku** | 小程序审查规则结构化（参考 `.claude/standards/miniapp.md`），输出短报告，已由 code-reviewer 兜底深度判断 |
| content-writer | sonnet | 文案产出 + 单一来源核对，sonnet 表达力够；haiku 易把"全新"等敏感词写飞 |
| growth-analyst | sonnet | 实验设计 + 统计判断，需推理深度，不下沉 haiku |

**调整原则**：
- 同类型任务跨多 agent 时优先用 sonnet 保一致性
- 仅当任务**有明确规则可循且失误成本由其他角色兜底**时才考虑 haiku
- 升降级触发：连续 2 次产出不达预期升档；连续 5 次任务空跑（输入不足 1k token）降档

## 反模式

- ❌ "为了让 agent 想得更全面，把所有 standards 都贴进 prompt" → cache 失效，token 翻倍
- ❌ "让 teammate 之间互相校对每一步" → 多轮往返爆量
- ❌ "等 agent 自己撞硬停" → 浪费已消耗的 token 没产出

## 参考

- [Claude Code Costs](https://code.claude.com/docs/en/costs)
- [Agent Team Token Costs](https://code.claude.com/docs/en/costs#agent-team-token-costs)
- [Datadog Claude Code Monitoring](https://www.datadoghq.com/blog/claude-code-monitoring/)
