Claude Code 系统提示构建艺术:6层动态注入与提示词设计完整解析
Claude Code 系统提示构建艺术:6层动态注入与提示词设计完整解析
Claude Code 的系统提示(System Prompt)不是一段静态文本,而是在每次对话开始时由分层注入机制动态组装而成的"宪法"。它决定了 AI 的角色、能力边界与行为准则。这篇文章基于开源分析项目 claude-code-design-guide 的章节资料,带你完整解析 Claude Code 系统提示的动态提示词设计:从 6 层构建流程、缓存优化策略,到用户自定义入口与长度权衡。
一、为什么系统提示是 Claude Code 的"宪法"
系统提示是 AI 的"宪法"——它定义了 AI 的角色、能力和边界。
每次 API 调用时,系统提示都会告诉模型四件事:
| 维度 | 内容 | 类比 |
|---|---|---|
| 它是谁 | 角色设定 | 新员工的岗位说明书 |
| 能做什么 | 工具与能力 | 可用的工具箱 |
| 不能做什么 | 安全边界 | 操作红线 |
| 如何行动 | 行为准则 | 团队规范 |
系统提示的质量直接决定输出质量:写得好的提示能让 Claude 更准确地理解任务、更合理地选择工具、更安全地执行操作。这也是为什么 Claude Code 把系统提示当成一项系统工程而非"写一段文案"来处理。
📌 想理解更上层的概念,可先读 part5/12-context-what.md——它解释了"上下文工程(Context Engineering)"与"提示工程(Prompt Engineering)"的区别:前者管理整个会话生命周期中的全部上下文,后者只是其中一个子集。
二、系统提示的 6 层动态构建流程
Claude Code 的系统提示在每次对话开始时动态构建,而不是从配置文件里读一段固定文字。构建流程按固定顺序组装 6 类内容:
- 核心指令(Core Instructions)——几乎不变的固定部分,定义安全优先、透明操作、代码质量、错误处理等基本行为准则
- 工具定义(Tool Definitions)——根据当前可用工具动态生成,每个工具的
name、description、inputSchema都会序列化进提示 - 用户上下文(CLAUDE.md)——自动发现项目各级 CLAUDE.md 并合并注入
- 系统上下文(System Context)——git 分支、最近提交、工作区状态等实时信息
- 自定义系统提示——用户通过
--system-prompt传入,替换默认提示 - 追加系统提示——用户通过
--append-system-prompt传入,追加到默认提示之后
这套流程在 part5/13-system-prompt.md 中有完整的构建流程示意,其中 fetchSystemPromptParts() 函数把各部分按序 join 起来,任何一层缺失都不影响其余层的注入。
💡 这种分层注入的设计意味着:你不需要"改写"整个系统提示,只需在合适的层级补充内容——项目规范写进 CLAUDE.md,个人偏好追加到末尾即可。
三、分层注入详解:4 类提示来源各自负责什么
3.1 核心指令:简洁的行为准则
核心指令尽量精简,只包含最重要的原则。从源码推断,它覆盖四类准则:
- 安全优先:破坏性操作必须先获得用户确认
- 透明操作:调用工具时说明要做什么、为什么做,不确定就先问
- 代码质量:遵循项目规范,只修改最小必要的代码
- 错误处理:失败时先分析原因再尝试替代方案,不盲目重试
3.2 工具定义:系统提示中"最大的一块"
工具定义是系统提示里篇幅最大的部分。模型靠 description 和参数 schema 来理解"这个工具是干什么的、参数怎么填"。工具描述的质量直接影响模型的工具选择准确性——这正是"动态提示词设计"中常被低估的一环:改一个工具的描述文案,可能比调模型参数更见效。
3.3 用户上下文:CLAUDE.md 的多级注入
CLAUDE.md 从全局到项目级、再到子目录级逐级向上发现并合并:
~/.claude/CLAUDE.md # 全局配置(所有项目共享)
/project/CLAUDE.md # 项目级配置
/project/src/auth/CLAUDE.md # 模块级配置(最具体)
它支持 @ 语法引用其他文档(如 @docs/api-spec.md),让提示可以"按需展开"而不是全部塞进一个文件。详细写法见 part5/14-memory-claudemd.md。
3.4 系统上下文:实时的 git 状态
每次对话开始,Claude Code 会自动采集当前分支、主分支、最近 5 条提交和工作区状态,作为"实时快照"注入提示。这让模型在不额外询问的情况下就"知道仓库现在什么状态"。
四、用户自定义入口:替换 vs 追加怎么选
两个 CLI 参数的分工非常清晰,这是新手最容易混淆的地方:
| 参数 | 行为 | 适用场景 |
|---|---|---|
--system-prompt |
替换默认系统提示 | 完全自定义场景(如构建专用 Agent) |
--append-system-prompt |
追加到默认系统提示之后 | 在默认行为基础上做增量扩展 |
多来源提示的优先级从高到低为:
--append-system-prompt > --system-prompt > CLAUDE.md > 内置默认提示
⚠️ 实用建议:90% 的场景下,你只需要用 CLAUDE.md + --append-system-prompt,而不要整体替换默认提示——内置提示中沉淀了大量经过验证的行为准则,替换掉它们往往得不偿失。
五、缓存优化:稳定部分前置,动态部分后置
系统提示动态构建带来一个成本问题:每次请求都发一大段提示,token 消耗和延迟都会上升。Claude Code 的解法是利用 Prompt Caching(提示缓存),在排列顺序上做文章:
- 稳定部分放前面(可缓存):核心指令、工具定义——工具集不变时内容不变
- 动态部分放后面(不缓存):git 状态、CLAUDE.md 内容——每次都可能变化
缓存前缀完全一致的部分可以命中缓存,TTL 最长 1 小时。API 客户端层通过 getCacheControl() 设置缓存控制,并支持三种全局缓存策略(tool_based / system_prompt / none),细节见 architecture/04-API客户端/api-client.md。
🎯 这里有一个反直觉的结论:把易变信息塞进系统提示前部,会导致缓存频繁失效,成本陡增。所以 Claude Code 刻意把"变化最快"的内容排在最后。
六、对话中的动态注入:system-reminder 机制
系统提示的"动态性"不止发生在构建时。对话过程中,Claude Code 还会用 <system-reminder> 消息向上下文注入临时指令,典型场景有两个:
1. MCP 服务器指令
MCP 服务器可以在初始化时提供 instructions,它们不会混入用户系统提示,而是以独立的 system-reminder 块注入。这样模型能区分"核心系统指令"和"服务器指令"——后者优先级更低,且服务器断开后即可安全移除。源码还采用 delta 模式更新,避免每轮重建系统提示导致缓存失效。参见 architecture/08-MCP集成/mcp-integration.md。
2. 输出样式(Output Styles)
用户可以用 Markdown 文件定义响应风格(简洁技术风、教学模式等),放在 .claude/output-styles/(项目级)或 ~/.claude/output-styles/(用户级),通过 /output-style <name> 一键切换,样式文本同样注入系统提示。配置方式见 architecture/38-输出样式/output-styles.md。
七、长度权衡:在完整与消耗之间找平衡
系统提示越长,模型理解越完整,但 token 消耗越大。Claude Code 对每层都做了长度控制:
| 层 | 长度策略 |
|---|---|
| 核心指令 | 尽量简洁,只留最关键的行为准则 |
| 工具定义 | 无法压缩,但只注册当前需要的工具来减少总量 |
| CLAUDE.md | 由用户控制,官方建议保持在 2000 字以内 |
| git 状态 | 硬截断:超过 2000 字符即截断并提示运行 git status 查看完整输出 |
截断逻辑在 part5/13-system-prompt.md 中有明确说明:超过 MAX_STATUS_CHARS = 2000 的部分直接丢弃,而不是静默忽略——这是"诚实的降级"设计。
另外值得一提的是一个工程细节:源码中保留了一个标注为 ant-only(仅内部使用)的系统提示注入点,允许内部工程师不重启进程就修改提示用于调试,并会主动清除上下文缓存强制重建。调试功能明确标注用途、防止误用,是提示词工程里值得学习的实践。
八、总结:好的系统提示设计做对了什么
回顾全文,Claude Code 的系统提示构建可以归纳为 5 条设计原则:
- 动态构建——根据运行时状态生成,而非静态配置
- 分层注入——核心指令 + 工具定义 + 用户上下文 + 系统上下文各管一层
- 缓存友好——稳定内容前置、动态内容后置,最大化缓存命中率
- 长度受控——每层都有截断或预算,在完整性与成本之间取平衡
- 可扩展——CLAUDE.md、
--system-prompt、--append-system-prompt、输出样式、MCP 指令多通道接入
💬 一句话总结:系统提示的质量 = 分层是否清晰 + 注入是否动态 + 缓存是否友好。如果你想在自己的 AI 应用中复刻这套机制,建议从"把稳定部分前置"这一条开始——它最容易被忽视,收益却最直接。
📚 延伸阅读:
- 系统提示构建全流程:part5/13-system-prompt.md
- 上下文工程总览:part5/12-context-what.md
- CLAUDE.md 与 Memory 设计:part5/14-memory-claudemd.md
- API 客户端与提示缓存:architecture/04-API客户端/api-client.md
- 压缩机制(提示过长时的自救):part5/15-compact.md