Claude Code 的系统提示词

Claude Code 的系统提示词不是一段硬编码大字符串，而是一套可分段、可缓存、可覆盖、可降级的控制面。

这一章要解决的是：系统提示词如何从多个来源生成，哪些内容被缓存，哪些内容必须每轮重算，静态规则和动态上下文如何分界，最后又如何变成 Anthropic API 的 TextBlockParam[]。

先看源码入口

读这一章要把“提示词内容”和“缓存协议”放在一起看。很多源码设计不是为了文案优雅，而是为了缓存稳定。

总流程图

这条链路里有三个边界：

• 段落边界：SystemPromptSection 管一个段落能否缓存。
• 静态/动态边界：SYSTEM_PROMPT_DYNAMIC_BOUNDARY 管全局可缓存前缀。
• 来源优先级边界：buildEffectiveSystemPrompt() 管谁覆盖谁。

段落注册表：系统提示词的最小单位不是字符串，而是 section

原文给出的 section 抽象：

type SystemPromptSection = {
  name: string;
  compute: ComputeFn;
  cacheBreak: boolean;
};

这个结构证明每个段落都有三件事：

创建段落有两条路径：

DANGEROUS_ 前缀是故意增加 API 摩擦：开发者必须写 reason，代码审查时就能追问“为什么不能缓存”。

resolveSystemPromptSections() 如何缓存

原文给出的核心函数：

export async function resolveSystemPromptSections(
  sections: SystemPromptSection[],
): Promise<(string | null)[]> {
  const cache = getSystemPromptSectionCache();
  return Promise.all(
    sections.map(async s => {
      if (!s.cacheBreak && cache.has(s.name)) {
        return cache.get(s.name) ?? null;
      }
      const value = await s.compute();
      setSystemPromptSectionCacheEntry(s.name, value);
      return value;
    }),
  );
}

这段代码证明四个行为：

缓存存放在 STATE.systemPromptSectionCache，不是普通模块变量。这样 /clear 和 /compact 可以统一清理。

清理函数：

export function clearSystemPromptSections(): void {
  clearSystemPromptSectionState();
  clearBetaHeaderLatches();
}

这段代码说明 /clear、/compact 不只是清聊天记录，也会让系统提示词段落重新计算，并重置 beta header 锁存器。

哪些段落必须每轮重算：mcp_instructions 是关键例子

原文指出源码中唯一典型的未缓存段落是 MCP 指令：

DANGEROUS_uncachedSystemPromptSection(
  'mcp_instructions',
  () =>
    isMcpInstructionsDeltaEnabled()
      ? null
      : getMcpInstructionsSection(mcpClients),
  'MCP servers connect/disconnect between turns',
);

这段代码证明 mcp_instructions 不缓存的原因很具体：MCP server 可能在两轮之间连接或断开。如果第 1 轮缓存了 server A 的指令，第 3 轮 server B 连接了，但缓存仍返回旧指令，模型就永远不知道 B。

对比另一个案例更能看出取舍：原文提到 token_budget 曾经是未缓存段落，因为它依赖当前 turn budget。但这样每次预算变化都会破坏约 20K token 的缓存。后来改写提示词，让“没有预算”时自然成为 no-op，于是可以降级为普通 systemPromptSection。

静态/动态边界：SYSTEM_PROMPT_DYNAMIC_BOUNDARY

系统提示词数组里有一个特殊标记：

export const SYSTEM_PROMPT_DYNAMIC_BOUNDARY =
  '__SYSTEM_PROMPT_DYNAMIC_BOUNDARY__';

这个字符串不是给模型看的，而是给下游 splitSysPromptPrefix() 看的带内信号。

在 getSystemPrompt() 返回数组里，它被放在静态段落和动态段落之间：

getSimpleIntroSection(...)
getSimpleSystemSection()
getSimpleDoingTasksSection()
getActionsSection()
getUsingYourToolsSection(...)
getSimpleToneAndStyleSection()
getOutputEfficiencySection()
SYSTEM_PROMPT_DYNAMIC_BOUNDARY
session_guidance
memory
env_info_simple
language
output_style
mcp_instructions
scratchpad
...

边界只在 shouldUseGlobalCacheScope() 为真时插入：

...(shouldUseGlobalCacheScope() ? [SYSTEM_PROMPT_DYNAMIC_BOUNDARY] : [])

原文还引用了 getSessionSpecificGuidanceSection 的源码注释：如果会话变量放在边界前，会让 Blake2b prefix hash 变体按 2^N 膨胀。

这就是系统提示词架构里最重要的缓存不变量：边界前不能混入会话状态。

splitSysPromptPrefix()：把逻辑数组切成缓存块

splitSysPromptPrefix() 把 systemPrompt: string[] 转成带 cacheScope 的块。它有三条路径。

路径 1：MCP 降级

触发条件是 shouldUseGlobalCacheScope() 为真，但 skipGlobalCacheForSystemPrompt 也为真。原文说明这个 flag 来自 claude.ts：只有 MCP 工具实际渲染进请求时才触发。

核心行为：

for (const prompt of systemPrompt) {
  if (!prompt) continue;
  if (prompt === SYSTEM_PROMPT_DYNAMIC_BOUNDARY) continue;
  if (prompt.startsWith('x-anthropic-billing-header')) {
    attributionHeader = prompt;
  } else if (CLI_SYSPROMPT_PREFIXES.has(prompt)) {
    systemPromptPrefix = prompt;
  } else {
    rest.push(prompt);
  }
}

这段代码证明 boundary 在降级路径里被跳过，剩余内容合并为 org 级缓存块。原因是 MCP 工具 schema 本身是用户级动态内容，即使系统提示词能全局缓存，整体请求也已有大块不可全局缓存内容，继续维护全局系统缓存收益变小。

路径 2：全局缓存 + 边界

这是无 MCP 降级时的高收益路径：

const boundaryIndex = systemPrompt.findIndex(
  s => s === SYSTEM_PROMPT_DYNAMIC_BOUNDARY,
);
if (boundaryIndex !== -1) {
  for (let i = 0; i < systemPrompt.length; i++) {
    const block = systemPrompt[i];
    if (!block || block === SYSTEM_PROMPT_DYNAMIC_BOUNDARY) continue;
    if (block.startsWith('x-anthropic-billing-header')) {
      attributionHeader = block;
    } else if (CLI_SYSPROMPT_PREFIXES.has(block)) {
      systemPromptPrefix = block;
    } else if (i < boundaryIndex) {
      staticBlocks.push(block);
    } else {
      dynamicBlocks.push(block);
    }
  }
}

这段代码证明边界前后被分成不同块：

路径 3：默认 org 缓存

如果不启用全局缓存，或找不到边界标记，函数会把非特殊内容合成一个 org 级缓存块。

这条路径是保守兜底：没有边界，就不要假装知道哪里能全局缓存。

buildSystemPromptBlocks()：cacheScope 变成 API cache_control

splitSysPromptPrefix() 的结果还要经过 buildSystemPromptBlocks()：

export function buildSystemPromptBlocks(
  systemPrompt: SystemPrompt,
  enablePromptCaching: boolean,
  options?: { skipGlobalCacheForSystemPrompt?: boolean; querySource?: QuerySource },
): TextBlockParam[] {
  return splitSysPromptPrefix(systemPrompt, {
    skipGlobalCacheForSystemPrompt: options?.skipGlobalCacheForSystemPrompt,
  }).map(block => ({
    type: 'text' as const,
    text: block.text,
    ...(enablePromptCaching && block.cacheScope !== null && {
      cache_control: getCacheControl({
        scope: block.cacheScope,
        querySource: options?.querySource,
      }),
    }),
  }));
}

这段代码证明：缓存不是注释或内部标记，而是最终进入 API 请求的 cache_control。cacheScope !== null 的块才获得 cache_control；动态块或计费头这类 null 块不缓存。

行为链路是：

SYSTEM_PROMPT_DYNAMIC_BOUNDARY
-> splitSysPromptPrefix()
-> SystemPromptBlock.cacheScope
-> buildSystemPromptBlocks()
-> TextBlockParam.cache_control
-> API 后端按 global / org 缓存

getSystemPrompt()：默认系统提示词如何构建

getSystemPrompt() 接收工具列表、模型、额外工作目录、MCP clients，返回 string[]。

它有三条快速路径：

标准路径里的动态段落包括：

唯一需要每轮重算的是 mcp_instructions。这让动态区大部分内容仍然可在会话内记忆化，减少重复 I/O 和计算。

buildEffectiveSystemPrompt()：多来源优先级

默认提示词还不是最终提示词。实际 API 调用前，还要合成多个来源。

优先级链：

overrideSystemPrompt
> coordinatorSystemPrompt
> agentSystemPrompt
> customSystemPrompt
> defaultSystemPrompt
+ appendSystemPrompt

最高优先级是 override：

if (overrideSystemPrompt) {
  return asSystemPrompt([overrideSystemPrompt]);
}

这段代码证明 override 是完整替换：一旦存在，其他来源包括 appendSystemPrompt 都被忽略。

没有 override 和 coordinator 时，核心合成逻辑：

return asSystemPrompt([
  ...(agentSystemPrompt
    ? [agentSystemPrompt]
    : customSystemPrompt
      ? [customSystemPrompt]
      : defaultSystemPrompt),
  ...(appendSystemPrompt ? [appendSystemPrompt] : []),
]);

这段代码证明：

状态和数据结构

设计取舍

读源码抓手

1. 先看 systemPromptSections.ts，确认 section 的 name / compute / cacheBreak。
2. 再看 resolveSystemPromptSections()，理解段落缓存如何命中和写入。
3. 找 DANGEROUS_uncachedSystemPromptSection 的调用点，重点读 mcp_instructions 的 reason。
4. 进入 constants/prompts.ts，找到 SYSTEM_PROMPT_DYNAMIC_BOUNDARY 在返回数组中的位置。
5. 读 splitSysPromptPrefix() 三条路径，确认 global/org/null cacheScope 如何产生。
6. 看 buildSystemPromptBlocks()，把 cacheScope 和 API cache_control 对上。
7. 最后读 buildEffectiveSystemPrompt()，确认 override、coordinator、agent、custom、default、append 谁覆盖谁。