v2.1.229 里一项容易被忽略但实际价值很高的改进——工作流扇出（fan-out）时错峰执行同前缀的兄弟 Agent，让后续 Agent 命中提示缓存而不是重新支付处理成本。本文详解这项优化背后的原理和实战调优方法。
问题背景：并行扇出为什么会有缓存浪费
典型场景：一个工作流同时启动多个子 Agent，
它们的提示词共享相同的前缀部分
（比如相同的系统指令、相同的项目背景说明）
如果这些 Agent 几乎在同一时刻并发发起请求，
提示缓存来不及"写入完成再被读取"，
导致多个并发请求都各自重新处理了这段本可以复用的前缀
提示缓存的工作原理是"先写入、后读取"——如果多个请求几乎同时到达，缓存写入还没完成，后面的请求就没法命中缓存，只能各自重新处理一遍相同的前缀内容，这在成本上是一种浪费。
解决方案：错峰执行
Improved workflow fan-outs to stagger same-prefix sibling agents so
subsequent agents read the cached prompt prefix instead of re-paying
it
官方给出的方案很直接——让共享相同前缀的兄弟 Agent 不要同时发起，而是错开一点时间。这样第一个 Agent 的请求完成缓存写入后，后续 Agent 的请求就能命中这个已经写好的缓存，不需要重新支付前缀处理的成本。
配置项
# 设为 0 可以禁用这个错峰机制，恢复原本的并发行为
export CLAUDE_CODE_WORKFLOW_PREFIX_STAGGER_MS=0默认情况下这个优化是启用的，如果你有特殊场景需要所有并行 Agent 严格同时发起（比如对时间敏感度要求高于成本考量的场景），可以通过这个环境变量关闭。
什么场景能从这项优化中受益最多
场景一：大规模代码库并行审查
多个子 Agent 分别审查不同模块，但共享同一套代码审查
标准和项目背景说明作为提示前缀
→ 错峰执行能让后续 Agent 大幅降低前缀处理成本
场景二：批量文档生成
为多个功能模块并行生成文档，提示词中共享相同的
文档风格规范和模板说明
→ 同样能从缓存复用中受益
场景三：多语言/多格式内容批量翻译或转换
提示词中的规则说明部分固定，仅输入内容不同
→ 前缀命中缓存的收益会随并行任务数量增加而放大
反过来，如果你的并行 Agent 之间提示词几乎没有共享前缀（每个任务的上下文都完全独立），这项优化就没有太大意义，这种场景下可以放心保持默认行为或直接禁用。
结合前文的 Prompt Caching 调优一起看
这项工作流层面的优化，和更底层的 cacheRetention、contextPruning 等提示缓存配置项是相辅相成的关系——底层配置决定"缓存能保留多久、上下文修剪策略是什么"，而这项工作流优化解决的是"如何让并发请求真正吃到已经写好的缓存"这个更细粒度的时序问题。两者组合起来，才能把大规模并行任务的 Token 成本控制到位。
实战建议
1. 评估你的并行工作流中，各个子 Agent 的提示词前缀
共享程度有多高，共享度越高，这项优化的收益越明显
2. 除非有明确的实时性要求，否则建议保持默认的错峰行为，
不需要主动禁用
3. 大规模扇出任务（比如几十上百个并行子任务）尤其值得
关注这项优化带来的成本变化，可以通过对比开启/关闭前后
的 Token 消耗来量化实际收益
4. 结合缓存保留策略（cacheRetention）一起调优，
确保前面写入的缓存在后续 Agent 读取时还没有过期
总结
这项看似不起眼的"错峰执行"优化，解决的是并行任务场景下一个容易被忽视的成本陷阱——多个几乎同时发起的相似请求会互相"抢跑"缓存写入的时机，导致本可以复用的前缀被重复处理。对于依赖大量并行 Agent 完成批量任务的用户，理解并善用这个机制，能在不改变任务逻辑的前提下直接压低 Token 成本。
来源：Claude Code Changelog v2.1.229 — Claude Code 官方文档，Anthropic