Hi，大家好，欢迎来到维元码簿。
本文属于 《Claude Code 源码 Deep Dive》 系列，专注于上下文工程中的 System Prompt 板块。如果你想了解整个系列，可以先看系列开篇 | Claude Code 源码架构概览：51万行代码的模块地图。
本文聚焦一件事：模型的"人设"是怎么被塑造出来的------System Prompt 的每一个零件怎么组装，又怎么被缓存策略保护。
读完全文，你将能回答这几个问题：
- Claude Code 专业沉稳的"人设"是谁写的？ 没有一个人定义了它，那它是怎么被塑造出来的？
- System Prompt 为什么是一段数组而不是一个大字符串？ 这个看似随意的决定，背后藏着什么工程考量？
- 为什么有些模块每次调用都重新计算，有些算一次就够了？ "会话内一旦确定，不再变化"------这句话背后的缓存哲学是什么？
前情提要：模型收到了什么
本文的定位是上下文工程 ------拆解模型每次调用时 Claude Code 到底组装了什么。那最自然的起点，就是找到那个组装的终点：实际发给 Anthropic API 的请求参数。
paramsFromContext()（src/services/api/claude.ts）返回发给 API 的完整参数。拆开看，真正变成 token 喂给模型的有三个字段：
| 字段 | 作用 | 预估占比 |
|---|---|---|
system |
告诉模型"你是谁、怎么做事"的指令集 | ~30% |
messages |
对话历史：用户输入、模型回复、工具调用结果 | ~60% |
tools |
工具 Schema：告诉模型可以调用哪些工具 | ~10% |
把三个板块合在一起，模型看到的上下文全景如下：
三个板块各是什么：
- System Prompt （
system，~30%）：模型的"身份设定与环境感知"，由 7 个静态模块 + 11+ 个动态模块组装成string[]。静态区所有用户共享，可命中全局缓存；动态区因会话变化。总入口getSystemPrompt()，但可能被优先级链替换。 - Messages （
messages，~60%）：对话与隐藏注入，承载用户输入、工具结果、附件展开等全部对话信息。 - Tools （
tools，~10%）：30+ 内置工具 + MCP 外部工具的 JSON Schema。
本文只拆解第一个板块------System Prompt。 Messages 和 Tools 分别在姊妹篇中展开。
System Prompt 的骨架------7 静态 + 11+ 动态
全景图告诉我们 System Prompt 大约占模型上下文的 30%。但 30% 背后的工程量，远比数字显示的更精密。System Prompt 不是一段写死的文本，而是一个动态组装的指令集------根据用户类型、运行模式、工具配置、MCP 连接状态实时拼装。
总入口是 getSystemPrompt()（src/constants/prompts.ts），返回 string[]------数组而非大字符串，目的是让后续缓存切分逻辑按元素粒度标记边界。
如上图所示，中间的 SYSTEM_PROMPT_DYNAMIC_BOUNDARY 把 prompt 分为静态区和动态区。静态区对所有用户完全相同，可用 scope: 'global' 跨组织缓存；动态区因会话而异，只能用 scope: 'org' 或逐 turn 重算。团队在设计 prompt 时就把缓存作为一等公民：每个新 section 都必须回答"放在边界之前还是之后？"。
静态区------7 个不变的模块
静态区的内容对所有用户完全相同------你可以和地球另一端的用户共享同一份 KV cache，只要字节一致。这 7 个模块构成了 Claude Code 的"人格基础"。
| 模块 | 核心原文 | 工程洞察 |
|---|---|---|
| Intro / 身份声明 | You must NEVER generate or guess URLs |
"安全壳"设计------编程场景中模型编造 URL 可导致访问恶意网站 |
| System / 系统行为 | Your conversation is not limited by the context window |
告诉模型有自动压缩兜底，不会因"怕用完 token"而拒绝复杂任务 |
| Doing Tasks / 任务执行 | Don't speculate. Three lines of similar code are fine |
最长的静态模块。"不过度设计"贯穿始终 |
| Actions / 行动准则 | Consider the reversibility and blast radius of actions |
如果只读一个模块就读这个。可逆操作自由执行，不可逆必须确认 |
| Using Tools / 工具使用 | Prefer dedicated tools over Bash |
Bash 最不透明，用户难以审查 |
| Tone & Style / 语气 | 不用 emoji、代码引用用 file:line |
解决了真实 UX 问题 |
| Output Efficiency | Go straight to the point. Don't be unnecessarily terse |
外部版偏简洁，内部版偏可理解 |
几个值得展开的设计亮点：
Doing Tasks 的"不过度设计"。四条规则每条背后都有模型曾犯过的真实错误：加了一个没人要求的特性、为三行相似代码抽了个 helper、在系统边界外加了不必要的 validation。团队选择在 prompt 层面显式禁止这些行为，而不是靠模型"自觉"------这是 prompt 工程的务实态度。
Actions 的"可逆性分级"。Claude Code 对 AI 安全的理解不是限制能力，而是让 AI 在高风险场景下主动慢下来。更有意思的是"授权范围匹配"：用户批准一次 git push 不等于在所有上下文都批准，这防止了模型把单次授权泛化为永久权限。
Output Efficiency 的"简洁 vs 可理解"博弈 。原文 What's most important is the reader understanding your output without mental overhead or follow-ups, not how terse you are------外部版偏简洁，内部版偏可理解，因为内部用户更频繁使用，追问成本更高。
一个更深的问题：这些行为约束为什么不写进代码，而是写在 prompt 里？ 答案是灵活性和可迭代性。代码约束是刚性的------一旦写死 禁止删除未跟踪文件，在所有场景下都生效。但 prompt 约束是软性的，模型可以根据上下文灵活判断。比如"可逆操作自由执行"------什么是可逆的，需要模型根据场景判断（创建文件可逆，push 到 shared branch 不可逆）。这种判断力用代码实现极其困难，但在 prompt 里只需一句话。
更重要的是，prompt 可以快速迭代。Claude Code 团队发现模型在某个场景下行为不理想时，最快的修复方式往往是在 prompt 里加一条规则------比改代码、发布、等用户更新快得多。7 个静态模块中的很多规则，就是这样在真实用户反馈中逐步积累的。
动态区------11+ 个条件模块
如果说静态区是"所有员工共享的基本守则"，那动态区就是"针对每个岗位的个性化指引"。
| 模块 | 重要级 | 核心职责 |
|---|---|---|
| session_guidance | P0 | 基于工具集生成使用策略（Agent / Explore / Skill / Verification） |
| memory | P0 | 加载 ~/.claude/memory/*.md，跨会话持久知识 |
| mcp_instructions | P0 | MCP Server 使用说明 |
| env_info_simple | P1 | 环境信息（CWD / 平台 / Shell / 模型名 / 知识截止日期） |
| output_style | P1 | 自定义输出风格 |
| frc | P1 | 告知模型旧工具结果可能被清除 |
| summarize_tool_results | P1 | 提醒模型处理工具结果时记录重要信息 |
| language | P2 | 用户语言偏好 |
| scratchpad | P2 | per-session 临时文件目录指引 |
| token_budget | P2 | 用户指定 token 目标时激活 |
| ant_model_override | P2 | 内部 ant 用户额外指令覆盖 |
session_guidance 是动态区最复杂的模块。内容取决于"这个会话有哪些工具可用"------AgentTool 使用策略、Explore agent 调用时机、Skill 调用指南。因为涉及具体工具列表，不能放静态区，但 memoized 后会话内只算一次。
mcp_instructions 最为特殊------它是目前唯一可能每 turn 重算的模块（MCP Server 可能随时连接/断开）。但后来引入 mcp_instructions_delta 后，MCP 状态稳定时不注入任何内容，缓存完全命中。这是从"破坏缓存"到"保护缓存"的典型演进。
Section 缓存框架：memoized vs uncached
动态区的每个模块都用统一的缓存框架包装。来自 src/constants/systemPromptSections.ts（仅 69 行）：
| 方法 | 缓存策略 | 何时重算 | 对缓存的影响 |
|---|---|---|---|
systemPromptSection() |
计算一次，缓存到 /clear 或 /compact |
会话重置时 | 不影响缓存 |
DANGEROUS_uncachedSystemPromptSection() |
每 turn 重算 | 每次 API 调用前 | 可能破坏 prompt cache |
绝大多数模块走 systemPromptSection() 路径------通过 session 级闭包缓存结果，整个会话只计算一次。只有 MCP 指令等少数场景走 DANGEROUS_uncached 路径。
缓存策略的演进也有故事：token_budget 曾是 DANGEROUS_uncached（每次 budget 翻转触发重算），后来改为 memoized------因为措辞用了条件句，没有 budget 激活时就是 no-op。这一改节省了约 20K tokens/次的缓存断裂。
整个 Section 缓存框架的核心思想只有一句话：尽量不重算，万不得已才重算。
优先级链：System Prompt 的完整决策树
前面看到的 getSystemPrompt() 返回的是"默认"System Prompt。但实际运行中，它只是决策树的一个叶子节点。外层的 buildEffectiveSystemPrompt() 决定了最终使用哪个 prompt：
| 分支 | 行为 | 频率 |
|---|---|---|
| Override | 直接返回 overrideSystemPrompt，跳过所有默认逻辑 |
极低，内部测试用 |
| Coordinator | 用协调者 prompt 替换默认，用于多 Agent 编排 | 极低，实验功能 |
| Agent + Proactive | Default 追加 Agent prompt，保留基础行为指引 | 低 |
| Agent / Custom | Agent/Custom 替换 Default，完全接管 | 低 |
| Default（标准模式） | 使用 7+11 模块 | 绝大多数用户 |
两个关键设计点：
- Proactive 是追加，标准 Agent 是替换：Proactive 模式下 Agent prompt 追加到 Default 之后，因为自主代理仍需要基础行为指引。标准模式下 Agent 完全接管，用自己的指令体系替代默认的。
- appendSystemPrompt 总是追加（Override 除外），确保额外内容不遗漏。
这对用户意味着什么？ 绝大多数用户（Default 模式）看到的 Claude Code 是标准版------专业、简洁、不主动加戏。但如果你配置了自定义 Agent prompt，Claude Code 会完全变成你定义的样子------一个代码审查 Agent、一个测试编写 Agent、一个 DevOps Agent。同一个产品，不同的灵魂。
更有趣的是 Proactive 模式。在这个模式下，Agent prompt 追加到 Default 之后而不是替换------这意味着 Agent 保留了 Claude Code 的基础行为（不乱删文件、不用 Bash 能用 Read 就用 Read），同时叠加了领域特定的指令。就像一个有良好职业素养的员工，在基础守则之上接收了项目组的具体指引。这种"追加而非替换"的设计，是工程务实主义的体现。
缓存切分：能共享就共享，不能共享就降级
System Prompt 的缓存切分由 splitSysPromptPrefix()（src/utils/api.ts）处理。它的设计目标很明确：尽可能让静态区命中最高级别的缓存共享，同时避免不同用户的动态内容互相干扰。
SYSTEM_PROMPT_DYNAMIC_BOUNDARY 是一个特殊字符串，不在模型的"人格指令"中------模型看到的是一个被替换后的分隔。它的真正作用是在 splitSysPromptPrefix() 中作为缓存切分锚点：
- 边界标记之前的所有元素（静态区）合并为一个 TextBlock，scope 为
global - 边界标记之后的所有元素（动态区）合并为另一个 TextBlock，scope 为
org - 两个 TextBlock 分开发送，API 的 KV cache 就能按不同 scope 缓存
三种场景的设计思路：能共享就共享，不能共享就降级。
场景 1：有 MCP 工具时------全部降级为 org。 不同用户配置的 MCP 工具不同，工具 Schema 会影响 System Prompt 的内容。此时全局缓存不可用，所有内容降级为组织级缓存。
场景 2：无 MCP 工具 + 有 boundary marker------静态区命中 global。 这是最优场景。7 个静态模块对所有用户完全相同，可以跨组织、跨用户共享缓存。
场景 3：第三方 API 提供商------回退到 org。 Bedrock、Vertex 等平台可能不支持全局缓存，统一用组织级。
这三种场景体现了"缓存策略应该是条件性的，而不是一刀切的"工程原则。
用户感知不到缓存的存在------直到它断裂。 缓存断裂的直接后果是：这一轮的响应变慢（因为要重新处理整个前缀），API 费用突增（重新处理意味着更多的 input tokens）。Claude Code 内置了"缓存断裂检测"（promptCacheBreakDetection.ts，651 行），它在每次 API 调用前后对比状态：调用前追踪 12 个维度的变更（system prompt 变了？工具 Schema 变了？模型换了？），调用后检查 cache_read_input_tokens 是否骤降。如果断裂了，系统会自动记录事件并归因到具体原因------"MCP 工具新增了 3 个"或"Beta header 从 5min TTL 切到了 1h TTL"。这个检测系统本身也是一个工程细节：不是出了问题才排查，而是主动监控、自动归因。
SystemContext：追加在 System Prompt 尾部
System Prompt 的主体是模块化组装的指令集，但还有一类信息不适合放在指令里------环境状态。当前 Git 分支、是否有未提交变更、工作目录结构......这些信息每轮都可能变化，但语义上更像是"身份背景"而非"对话内容"。
Claude Code 的做法是把这类信息作为 SystemContext 追加在 System Prompt 尾部。放 System Prompt 而非 Messages，是因为它的语义是"你当前所处的环境"，不是用户说的话。
与之对应的是 UserContext，它注入到 Messages[0] 的位置。两者都叫"Context"，但设计意图完全不同：SystemContext 是环境状态（身份层面），UserContext 是项目知识（对话层面）------详见姊妹篇[消息管道与隐藏注入](./02-Claude Code深度拆解-上下文里有什么-消息上下文管理.md)。
本章小结
System Prompt 看起来只是一段文本，但背后的工程体系非常精密：
- 静态区 7 模块：对所有用户相同，共享 global KV cache------你今天调用的缓存，可能复用了另一个用户 10 分钟前计算的结果
- 动态区 11+ 模块：通过 Section 缓存框架管理，会话内只算一次
- 优先级链：Override > Coordinator > Agent(proactive追加) > Custom > Default------同一个 Claude Code，在不同场景下展现的是不同面貌
- 缓存边界 ：静态区和动态区用
DYNAMIC_BOUNDARY分隔，三层 scope（global/org/ephemeral）按条件降级 - SystemContext：环境状态追加在尾部，与 UserContext（注入 Messages）形成互补
没有一个人定义了 Claude Code 的人设。 18 个模块按优先级链拼装，你在不同场景下看到的 Claude Code，其实是同一套骨架在不同模块组合下的不同面貌。
系列导航：
本文属于 《Claude Code 源码 Deep Dive》 系列中「上下文组成与缓存」命题的子篇章，专注于 System Prompt 的组装与缓存。
本文是完整版《Claude Code 源码深度解析：拆解上下文的组成与缓存》的子命题之一。如果你想了解上下文编排的全景（System Prompt + Messages + Tools + 缓存工程），推荐阅读完整版。
姊妹篇（可独立阅读）：
- Claude Code 深度拆解：上下文里有什么------消息上下文管理
- Claude Code 深度拆解：上下文里有什么------工具能力声明
- Claude Code 源码深度解析：拆解上下文的组成与缓存
如果这篇文章对你有帮助，欢迎点赞收藏 支持一下。有任何想法或疑问，欢迎评论区留言讨论 👋