
看了 claude-code 的系统提示词源码,我发现它不是靠一段简单的 system prompt 来提醒模型选对工具,而是靠一整套分层控制面在提前塑形。
看了 claude-code 的系统提示词源码,我有一个核心判断:它不是靠一段简单的 system prompt 来"提醒模型选对工具",而是靠一整套分层控制面在提前塑形。
这套控制面至少有六层。
默认 prompt 在 src/constants/prompts.ts:445-578 里组装,里面专门有 # Using your tools 段落,明确要求"有专用工具就不要用 Bash",并给出读文件、编辑文件、搜索文件、并行调用工具等全局规则。
src/context.ts:116-188 只负责产出上下文数据;真正怎么注入是在 src/utils/api.ts:437-474。这里把 systemContext 追加到 system prompt 尾部,把 userContext 作为一个 synthetic user message,并包成 <system-reminder>。
这很关键。repo 指令、memory、日期之类的信息按"语义角色"分开投喂,不是简单塞进同一个字符串。
工具 schema 发给模型之前,会通过 src/utils/api.ts:119-266 把每个 tool 的 prompt() 结果渲染成 API description。工具选择主要靠每个工具自己的 affordance 定义,不是靠顶层 prompt 猜。
典型例子:
src/tools/GrepTool/prompt.ts:6-17src/tools/FileReadTool/prompt.ts:27-48src/tools/BashTool/prompt.ts:42-160它们不是只在会话开始时加一次,而是:
src/utils/processUserInput/processUserInput.ts:495-513src/query.ts:1541-1593这些 attachment 最后在 src/utils/messages.ts:3660-4290 转成模型可见的 <system-reminder> 消息。这里会动态提醒 plan mode、auto mode、todo/task、skill、deferred tools、MCP instructions、compaction 等。
src/utils/toolSearch.ts:154-198 和 src/services/api/claude.ts:1105-1233 不只是告诉模型"该用哪个工具",而是直接决定哪些工具此刻可见、哪些要 defer、哪些要通过 ToolSearch 再发现。这层是最强的先验——模型看不见的工具就不会选。
src/constants/prompts.ts:115 放了 SYSTEM_PROMPT_DYNAMIC_BOUNDARY,src/utils/api.ts:321-435 负责把静态/动态 prompt block 拆开,src/constants/systemPromptSections.ts:17-57 负责 section 级缓存,src/utils/toolSchemaCache.ts:3-8 负责 tool schema 缓存。
更细的一层是 src/utils/messages.ts:1808-1950,会把 <system-reminder> 重新 wrap、smoosh、relocate,避免上下文拓扑本身诱发坏模式。
把"工具选择"当成一个持续控制回路,不是一次性提示词。
<system-reminder> 标签,并在消息归一化时特殊处理,避免模型把它误学成普通 user turn 模式很多 agent 系统的上下文构建还停留在"单字符串 system prompt + repo context 拼接 + tool modelDescription"这一层,缺少真正的分层上下文系统。
具体表现:
repoContext.content 直接拼成一个字符串stable 和 volatile 的概念,但还只是标签,没有真正驱动不同注入策略systemPrompt?: string,system 层还是"扁平字符串"模型MODEL_DESCRIPTION缺的不是"更多文案",而是缺一个独立的 reminder plane 和 request-time context assembly。
如果你正在构建类似的 agent 系统,可以考虑这些方向:
架构层面
PromptEnvelopeContextSection 思路补完整:加 channel(区分 system、user-reminder、post-tool-reminder)、保留 stability、再加 cadence 或 injectionPolicyAgentSession 在每次 provider 请求前做 context assembly,而不是 app 层先拼好一整段字符串再塞进去Context 使用
CLAUDE.md 链路更适合进稳定的 repo-instruction channelcwd/repoRoot/env 适合进 session 级 system sectioncurrent-date、git snapshot 更适合进 volatile reminder,而不是和 durable rules 混在一个字符串里工具层
preferredOver、fallbackOnly、primaryUseCases、counterExamplesReminder 策略
一句话概括:Claude Code 的强点不是 prompt 更长,而是它把"静态规则、动态提醒、工具 affordance、工具可见性、上下文结构稳定性"拆成了不同层。要升级的话,不是继续往 buildSystemPrompt() 里加句子,而是把上下文构建从"字符串拼接"升级成"分层装配"。