第六章 价值百万的提示词架构

本章深入解析了 Claude Code 如何通过一套分段式组合架构（Sectioned Composition Architecture），在维持海量指令集的同时，实现极致的成本优化和缓存效率

1. 核心挑战：成本与灵活性的权衡

Claude Code 的系统提示词包含身份、规范、工具指南、环境信息等十余个段落，总量达数万 token。其架构设计必须解决三大工程挑战：

• 体积与成本：避免每次 API 调用都重传数万 token 导致的缓存成本。
• 变化频率不一：身份介绍是静态的，而环境信息和 MCP 指令是动态的。
• 多来源覆盖：需要处理用户自定义、Agent 模式、循环模式等多种提示词来源的优先级。

2.：分段记忆化 (Sectioned Memoization)

系统提示词被拆分为独立的段落（Section），通过 systemPromptSections.ts 进行生命周期管理：

• 记忆化段落 (systemPromptSection)：计算结果会被缓存到全局状态中，后续轮次直接复用，仅在 /clear 或 /compact 时重置,。
• 易变段落 (DANGEROUS_uncachedSystemPromptSection)：标记为“危险”，因为它们每轮都会重新计算并破坏缓存。这种设计通过 API 摩擦（要求必填 reason 参数）强制开发者权衡内容新鲜度与缓存效率,。

3. 静态与动态边界：缓存分治策略

系统提示词中存在一条显式的 SYSTEM_PROMPT_DYNAMIC_BOUNDARY（动态边界）：

• 静态区（边界前）：包含在所有用户、所有会话中完全相同的内容。系统利用 scope: 'global' 实现跨组织缓存共享，极大降低了 Anthropic API 后端的计算压力。
• 动态区（边界后）：包含所有依赖运行时状态的内容（如工具引导、内存文件、环境信息）。
• 设计约束：静态区严禁包含任何因会话而异的条件分支，否则会导致全局缓存哈希变体呈指数级增长（2^N），使命中率归零,。

4. splitSysPromptPrefix 的三条缓存路径

系统会根据运行时条件选择最优的 API 请求块构建路径：

• 路径 1：MCP 降级路径。当存在活跃的 MCP 工具时，由于工具 Schema 是用户级的，系统会自动降级到组织级（org）缓存。
• 路径 2：全局缓存+边界路径。这是最优路径，将提示词拆分为不可缓存的归因头、全局缓存的静态块以及不缓存的动态块。
• 路径 3：默认组织缓存路径。用于第三方提供者或未定义边界的情况。

5. 优先级合成链 (Priority Chain)

buildEffectiveSystemPrompt 负责按严格的优先级合成最终发送给模型的指令集：

• 优先级顺序：Override (覆盖) > Coordinator (协调器) > Agent (代理) > Custom (自定义参数) > Default (默认值)，最后再加上可选的 Append (追加) 段落,。
• 这种设计确保了在不同运行模式下，系统行为是可预测且线性可读的。

本章提炼了三项可复用的工程模式,：

1. 分段记忆化：通过工厂函数区分静态与易变内容。
2. 缓存边界分治：将会话变量赶到边界之后，保护全局缓存前缀。
3. 优先级链合成：使用清晰的三元链处理多来源提示词冲突。

总结而言：系统提示词架构的价值不在于功能实现，而在于成本效率。它通过精密的缓存层级设计，在每天数百万次 API 调用中节省了大量的处理开销，是生产级 AI Agent 的关键基础设施。