System Prompt 三层组装与 CLAUDE.md 四级覆盖——上下文管理的最后一公里《Claude Code 架构解密》精读笔记 · 第12篇覆盖章节第7章后半7.5-7.8, p.184-198主题系统 Prompt 组装管线、CLAUDE.md 覆盖链、上下文管理设计模式导语Prompt 不是一段文本而是一条管线上一篇文章我们拆解了 Claude Code 面对上下文窗口极限的四层压缩策略——从零成本的 API 原生压缩到 LLM 驱动的 Full Compact。但压缩只是对话历史这端的问题上下文管理还有另一端每次 API 调用时注入的系统 Prompt。你可能会想系统 Prompt 不就是一段固定的文本吗有什么好讲的在 Claude Code 的架构中系统 Prompt 远不止一段文本——它是一条三层组装管线精确映射 API 缓存粒度它的第三层是一个四级覆盖链从企业到个人层层叠加当多层指令冲突时仲裁者不是代码而是 LLM 本身。这不是Prompt Engineering这是Prompt Architecture。一、架构定位三层管线在上下文管理中的位置┌─────────────────────────────────────────────────────────┐ │ 上下文管理全景 │ ├─────────────────────────────────────────────────────────┤ │ │ │ ┌──────────────┐ ┌──────────────┐ ┌───────────┐ │ │ │ 7.2-7.4 │ │ 7.5 │ │ 7.6 │ │ │ │ 四层压缩策略 │ │ System Prompt│ │ CLAUDE.md │ │ │ │ (对话历史端) │ │ 三层组装管线 │ │ 四级覆盖链 │ │ │ │ │ │ (行为指令端) │ │ (用户定制) │ │ │ └──────────────┘ └──────────────┘ └───────────┘ │ │ ↓ ↓ ↓ │ │ ┌──────────────────────────────────────────────────┐ │ │ │ 7.7 设计模式提炼 │ │ │ │ 后台Agent记忆 | 内容引用分离 | 缓存感知分层 | │ │ │ │ 覆盖链配置 │ │ │ └──────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────┘三层管线解决的核心问题如何在保持缓存命中率的同时注入会话级动态内容和用户级定制指令二、核心点拆解2.1 三层组装管线——缓存优化驱动的分层架构buildEffectiveSystemPrompt()是组装管线的入口接收默认 Prompt 数组和用户指令层输出品牌类型SystemPrompt。三层划分不是随意的而是精确映射 Anthropic API 的缓存粒度层级变更频率缓存策略对应 API 行为静态层几乎不变版本更新才变cacheScope: global跨组织缓存Prompt Cache 前缀命中动态层会话内稳定会话级缓存少数每轮重算同会话内缓存命中用户指令层按用户/项目不同无缓存完全个性化每次全量传输第 1 层静态内容——不变的行为准则静态层是整个 Prompt 的基岩由 7 个有序章节组成序号内容概要架构意图身份与安全身份定义 网络安全指令划定身份边界和安全底线系统环境工具执行、输出格式、自动压缩说明告知模型自身运行环境的约束任务执行编码风格、用户协助原则控制代码质量和交互行为风险操作破坏性操作确认要求安全架构的 Prompt 层工具选择优先使用专用工具而非 Bash避免Bash 万能化退化格式规范输出风格UX 一致性输出效率简洁性要求降低 Token 消耗每个章节标注cacheScope: global意味着对所有用户完全相同。当 Anthropic 的 Prompt Cache 命中时这部分的 Token 计算成本为零。Prompt 层安全 vs 代码层安全——一个值得深入的设计决策代码层安全权限系统、沙箱、命令黑名单是硬性约束——即使模型想执行rm -rf /代码也会拦截Prompt 层安全是软性引导——让模型不想执行危险操作减少权限弹窗的频率两者构成纵深防御。Prompt 中的破坏性操作列举与 BashTool 中的硬性黑名单形成互补——软 硬双层设计降低了权限弹窗频率改善了用户体验。静态分隔标记第 1 层和第 2 层之间用SYSTEM_PROMPT_DYNAMIC_BOUNDARY分隔。这个标记被 API 调用层的splitSysPromptPrefix函数使用将 Prompt 分割为 cacheable prefix 和 non-cacheable suffix直接映射到cache_control字段。第 2 层动态章节——注册表与缓存策略动态章节层是三层管线中最精巧的设计。它采用注册表模式——每个章节通过工厂函数注册运行时按名称解析typeSystemPromptSection{name:stringcacheBreak:boolean// 是否每轮重算}两个工厂函数的区别仅在于cacheBreak字段工厂函数cacheBreak适用场景systemPromptSection(name, compute)false会话内稳定的内容如技能列表、MCP 指令DANGEROUS_uncachedSystemPromptSection(name, compute, reason)true每轮都可能变化的内容如当前时间DANGEROUS_ 前缀的治理智慧——这不是危言耸听而是一个刻意的架构治理模式承认成本DANGEROUS_ 前缀让代码审查者立即意识到这个章节会破坏缓存文档化理由_reason参数虽然运行时不使用但强制在代码中留下为什么需要每轮重算的理由这是 Claude Code 中反复出现的设计哲学通过 API 设计使错误的事情难以做到。如果一个章节不需要每轮重算没有开发者会主动选用带 DANGEROUS_ 前缀的函数——从而保护了 Prompt Cache 的命中率。并行解析流程所有动态章节通过Promise.all并行计算前提是各章节之间没有数据依赖——环境信息、技能列表、MCP 指令都是独立获取的。“约束产生效率”正是因为章节间无依赖的设计约束才使得并行解析成为可能。缓存失效的四个触发点触发场景原因/clear 命令用户主动重置会话/compact 命令压缩后 Prompt 需要反映新状态进入/退出 WorktreeCWD 变化导致环境信息过时会话恢复恢复时需重建完整状态一个细节清理缓存时会同步调用clearBetaHeaderLatches()——确保功能开关在新上下文中重新评估避免 Prompt 内容和 API 请求头之间的不一致。这种关联失效体现了系统一致性的严谨追求。动态章节清单章节缓存策略内容示例会话指导会话内缓存按会话类型注入的特定行为指导记忆会话内缓存memdir 加载的自动记忆文件环境信息会话内缓存CWD、Git 状态、平台、Shell、模型语言会话内缓存用户语言偏好输出样式会话内缓存输出风格配置MCP 指令会话内缓存MCP 服务器注入的行为指令暂存区会话内缓存暂存目录使用说明Token 预算会话内缓存Token 预算说明FeatureGate 控制第 3 层用户指令层CLAUDE.md第三层是整个管线中最贴近用户的部分核心载体是 CLAUDE.md 文件——一种 Markdown 格式的配置文件用户通过自然语言为 Agent 设定行为准则。详见下文 2.2 节。2.2 CLAUDE.md 四级覆盖链——从企业到个人的配置层叠为什么需要多级配置一个场景一家企业有 100 名开发者在使用 Claude Code。企业安全团队希望所有人的 Agent 都遵守不得将代码推送到公共仓库的规则每个开发者又有自己的编码风格偏好某个项目组有特定的代码规范而某个开发者正在本地实验新的 lint 规则不希望影响团队。四级加载层级优先级低→高/etc/claude-code/CLAUDE.md ← Managed企业级管理员设定 ~/.claude/CLAUDE.md ← User个人全局偏好 repo/CLAUDE.md ← Project项目级规范 repo/.claude/CLAUDE.md ← Project隐藏目录等效 repo/.claude/rules/*.md ← Project Rules条件规则 repo/CLAUDE.local.md ← Local本地私有不入 Git这是经典的**覆盖链Override Chain**设计模式与 CSS 的层叠规则异曲同工。层级存储位置版本控制典型内容Managed/etc/claude-code/由 MDM 工具分发企业安全策略、合规要求User~/.claude/不入版本控制个人编码风格、语言偏好Project项目根目录入 Git团队共享项目代码规范、架构约定Local项目根目录.gitignore 排除本地实验性配置条件规则——上下文感知的指令注入在.claude/rules/目录下每个 Markdown 文件可以通过 YAML Frontmatter 声明自己适用的文件模式paths:-src/components/**/*.tsx-src/hooks/**/*.tsReact 组件必须使用函数组件不使用 class 组件。 所有 hooks 必须以 use 前缀命名。 状态管理优先使用 useReducer 而非 useState复杂场景。条件规则的必要性前端规范和后端代码完全不同。如果所有规则无条件注入 Prompt会产生两个问题窗口浪费不相关的规则占用了宝贵的上下文窗口空间遵循度下降模型面对大量不相关指令时对关键指令的遵循度会降低条件规则让 Prompt 只包含与当前任务相关的指令——这与 7.2 节按需保留压缩思想一脉相承。include 引用机制与安全防护记忆文件支持path语法引用其他文件实现配置的模块化组织# 项目级 CLAUDE.md ./coding-standards.md ./api-conventions.md ~/personal-preferences.md引用机制引入了潜在安全风险——循环引用和路径遍历。Claude Code 为此设计了三层防护循环引用防护processedPathsSet 追踪已处理路径同一文件不会被处理两次深度限制MAX_INCLUDE_DEPTH 5防止深层嵌套导致的栈溢出符号链接处理safeResolvePath先解析符号链接到真实路径同时在 processedPaths 中记录原始路径和解析后路径——防止通过符号链接绕过循环检测内容处理管线从磁盘文件到最终注入 Prompt 的内容经过一条完整的处理管线读取文件 → 检查扩展名白名单(100种) → 解析 YAML Frontmatter → 剥离 HTML 注释(marked Lexer) → 提取 include 路径 → 对 AutoMem/TeamMem 应用截断(40000字符) → 递归处理 include 引用两个值得关注的细节剥离 HTML 注释使用 marked Lexer 而非简单的正则替换因为 HTML 注释可能出现在代码块内应保留或正文中应剥离截断信任边界MAX_MEMORY_CHARACTER_COUNT 40000只应用于自动记忆AutoMem和团队记忆TeamMem不限制用户手动编写的 CLAUDE.md。用户手写内容假定经过深思熟虑而自动生成内容可能无限膨胀覆盖语义与冲突仲裁——全部注入模型仲裁如果 Managed 层说禁止使用 eval()“而 Project 层说在测试代码中允许使用 eval()”最终谁生效Claude Code 的回答是全部注入由模型仲裁。四级配置文件的内容全部被注入 Prompt以标注来源层级的方式并列呈现。模型会看到两条矛盾的指令并根据上下文当前正在编辑的是测试文件还是生产代码做出判断。为什么不在代码层做硬性优先级覆盖两个原因自然语言规则难以机器比较——禁止使用 eval()和在测试中允许 eval()不是简单的键值对无法用程序判断它们是否冲突LLM 的上下文理解能力恰好适合处理模糊的优先级仲裁——它可以根据当前文件类型、操作意图综合判断当然软仲裁也有风险——Claude Code 的应对是在注入时标注层级来源通过描述性标注影响模型对冲突指令的优先级判断。这是 Prompt 工程的一个精妙应用通过描述性标注影响模型对冲突指令的优先级判断。2.3 六级优先级仲裁器三层管线组装完毕后还需要面对 SDK 嵌入方、Agent 定义、用户参数等多方指令冲突。buildEffectiveSystemPrompt中实现了一个六级优先级仲裁器级别典型场景设计意图OverrideSDK 嵌入/自动化完全控制模型行为忽略所有默认规则Coordinator多 Agent 协调模式协调器需要与执行者不同的行为模式Agent (proactive)自主 Agent 模式保留默认安全规则在其上叠加 Agent 指令Agent (normal)普通 Agent 任务Agent 完全定义自己的行为CustomCLI --system-prompt开发者实验用Default Append正常交互标准行为 用户追加指令关键安全决策Proactive 模式下Agent Prompt 是追加而非替换默认 Prompt。为什么默认 Prompt 包含安全准则如破坏性操作确认要求如果替换了Agent 可能在没有用户确认的情况下执行破坏性操作。延迟加载与条件编译通过feature()require()实现条件加载——feature()在构建时由 Bun bundler 评估如果条件为 false 则整个 require 被消除dead code elimination。这避免了加载未启用功能的代码减小 bundle 体积同时解决了某些模块间的循环依赖问题。2.4 上下文窗口约束——Prompt 的物理极限系统 Prompt 不是可以无限增长的——它受上下文窗口大小的约束。context.ts负责管理这一物理极限。窗口大小的决策链环境变量覆盖 (仅内部用户) → 模型名[1m]后缀检测 → 1M tokens → getModelCapability() 能力查询 → Beta Header 检查 → 实验分组检查 → 默认值200,000 tokens输出 Token 的精巧优化exportconstCAPPED_DEFAULT_MAX_TOKENS8_000// 默认上限exportconstESCALATED_MAX_TOKENS64_000// 达到上限后重试的值根据实际数据p99 的输出约 4,911 tokens而默认 max_tokens 如果设为 32K/64K 会过度预留 8-16 倍容量。Claude Code 的策略是先小后大——默认 8K只有当模型实际触达上限时才提升到 64K 重试。99% 的请求因此节省了大量预留空间为对话历史腾出更多上下文窗口。三、设计模式提炼纵观第 7 章的压缩策略和系统 Prompt 工程可以提炼出四个核心设计模式模式一后台 Agent 驱动的会话记忆问题长对话压缩中 LLM 摘要不可避免地丢失结构化任务状态。核心思想Fork 一个专用子 Agent在后台周期性提取结构化的会话记忆。主对话流 (REPL) ↓ postSamplingHook ↓ extractSessionMemory() ↓ 双阈值判断 (tokens 阈值 AND 工具调用 阈值) ↓ createSubagentContext() ↓ setupSessionMemoryFile() ↓ runForkedAgent() — 只允许 FileEditTool只能编辑 summary.md ↓ 完成设计要点双阈值触发token 10000 工具调用 3 次避免闲聊时浪费资源工具权限隔离后台 Agent 只被授权 FileEditTool 只能编辑指定文件sequential()并发控制 Compact 前等待提取完成15 秒超时9 章节结构化模板总限制 12000 tokens与 Compact 的协同Session Memory 优先于传统 Compact 被触发。当 Session Memory 存在时Compact 操作会使用会话记忆内容作为摘要而非重新调用 LLM 生成实现**零 LLM 成本的 Compact**。模式二内容引用分离问题大段代码/日志内联存储导致历史文件膨胀到数百 MB。核心思想基于大小阈值的内联-引用分离——小内容直接存储大内容用 SHA256 哈希引用指向独立的缓存文件。// 写入时分流if(content.length1024){stored{id,type:text,content}// 小内容内联}else{consthashsha256(content).slice(0,16)// 16字符截断awaitstorePastedText(hash,content)// 存到 paste-cache/stored{id,type:text,contentHash:hash}// 只存引用}设计要点阈值 1024 字节太小导致碎片化太大导致历史膨胀——1KB 是经验平衡点SHA256 取前 16 字符64bit冲突概率在单用户场景下可忽略倒序替换展开引用时从后往前处理避免前面的替换改变后面引用的字符偏移量懒加载语义历史文件记录引用而非内容只在实际需要还原时才从 paste-cache 读取模式三缓存感知 Prompt 分层问题Prompt 包含不同变更频率的内容混在一起无法利用 API 缓存。核心思想按变更频率分层精确映射缓存策略。关键技术三层管线 DANGEROUS_API 治理 cache_control映射 SYSTEM_PROMPT_DYNAMIC_BOUNDARY分隔标记。模式四覆盖链配置问题多级配置需要灵活覆盖但自然语言规则难以机器比较。核心思想多级文件按优先级叠加模型仲裁冲突。关键技术四级层级 条件规则glob 模式 include 引用 LLM 冲突仲裁。模式速查表模式问题核心思想关键技术后台 Agent 记忆长对话压缩丢失结构Fork 子 Agent 后台提取双阈值触发、工具权限隔离、sequential 并发控制内容引用分离大内容内联导致膨胀小内联、大哈希引用SHA256 截断、倒序替换、懒加载展开缓存感知分层Prompt 含不同频率内容按频率分层映射缓存三层管线、DANGEROUS_API 治理、cache_control覆盖链配置多级配置灵活覆盖多级叠加模型仲裁四级层级、条件规则、include 引用四、横向对比System Prompt 组装 vs 其他 Agent 框架维度Claude CodeLangChainOpenAI AssistantsPrompt 来源三层管线静态动态用户代码级拼接单一 instructions 字段缓存感知精确映射 API 缓存粒度无API 级自动缓存动态章节注册表模式并行计算代码级条件渲染无动态概念用户定制四级覆盖链 条件规则无内置机制无内置机制冲突仲裁LLM 软仲裁 层级标注代码级覆盖最后写入者胜出治理模式DANGEROUS_ API 命名无无CLAUDE.md 四级覆盖 vs 其他配置体系维度CLAUDE.mdESLint 配置Git 配置层级数4 级Managed/User/Project/Local3 级Home/Project/Override3 级System/Global/Local条件规则glob 模式 YAML Frontmatteroverrides 字段无冲突处理全部注入 LLM 仲裁靠后优先覆盖靠后优先覆盖引用机制include 三层安全防护extends pluginsincludeIf条件包含企业管控Managed 层 MDM 分发共享配置包系统级模板核心差异CLAUDE.md 的全部注入 LLM 仲裁是独一无二的——其他配置体系都用代码级覆盖而 Claude Code 把模糊冲突交给最擅长理解自然语言的 LLM。五、实战启示启示 1缓存感知是 Prompt 架构的第一性原理Claude Code 的三层管线不是为了好看而分层——每一层都精确映射 API 的缓存粒度。如果你在设计 Agent 系统的 Prompt 体系第一件事不是写 Prompt 内容而是搞清楚你的 API 提供商的缓存边界在哪里。把不变的内容放前面全局缓存会话级变化的内容放中间会话缓存用户个性化内容放后面无缓存——这个变更频率递增的排列顺序就是缓存感知的核心。启示 2API 命名是最廉价的治理工具DANGEROUS_前缀不需要任何运行时成本却能在代码审查时立刻引发警觉。在你的系统中如果某个操作有高成本或高风险让它看起来危险比写文档更有效。类似的模式React 的dangerouslySetInnerHTML、Rust 的unsafe块——都在用命名传递意图。启示 3覆盖链的关键不是谁覆盖谁而是冲突怎么处理四级覆盖链的创新不在层级本身CSS/Git/ESLint 都有多级配置而在于冲突仲裁策略代码级覆盖靠后优先适合结构化配置但对自然语言规则无能为力LLM 仲裁适合模糊冲突但不是确定性的——需要层级标注辅助实践建议对于安全关键规则在代码层做硬性执行如权限系统的 deny 规则对于风格偏好等软性规则交给 LLM 仲裁——硬约束代码化软约束 Prompt 化。启示 4输出 Token 的先小后大策略默认 8K、触达后升级 64K——这不是一个简单的参数选择而是对99% vs 1%场景的精确建模。p99 输出 4,911 tokens 意味着 32K/64K 的默认值是在为 1% 的极端场景浪费 8-16 倍预留空间。通用原则为常见场景优化默认值为极端场景准备升级路径。过度预留是上下文窗口的隐形杀手。六、第7章全章总结上下文管理的核心智慧回望整个第7章从四层压缩策略到三层 Prompt 管线到四级覆盖链一条主线贯穿始终分层 渐进——不试图用一个万能方案解决所有问题而是按照不同维度成本、变更频率、信任层级将问题分解每层用最适合的策略处理。压缩策略零成本 → 零 LLM → LLM 驱动渐进升级Prompt 管线全局缓存 → 会话缓存 → 无缓存变更频率递增配置覆盖企业 → 个人 → 项目 → 本地信任层级递减四者协同压缩解决对话太长Session Memory 在压缩中保留结构化知识Prompt 管线确保每次调用携带正确行为指令CLAUDE.md 覆盖链让用户精细控制 Agent 行为——让一个有限窗口的 LLM 能够支撑无限长度的工作会话。下期预告第 13 篇我们将进入第8章——安全纵深防御这是 Claude Code 安全架构的集大成之作六层防御模型总览、OS 级沙箱、命令注入防护、路径遍历防护。当 AI 拥有了执行能力安全就不再是一个功能而是一个体系。第13篇预告沙箱里的自由——Claude Code 六层纵深防御体系全解本篇为《Claude Code 架构解密》精读笔记第12篇覆盖第7章后半7.5-7.8。上一篇[第11篇] Context 的生死抉择——四层压缩、截断算法与 Session Memory系列持续更新中关注获取更多精读内容。