Claude Code 的提示词工程

不要把 Claude Code 的 prompt 理解成“一大段总提示词”

很多人第一次研究 Claude Code，都会先找那段“终极 system prompt”。
但源码里真正存在的，不是一条 prompt，而是一整套分层装配的提示词系统。

Claude Code 至少同时存在这几类 prompt：

• 会话级 system prompt
• 运行时动态追加的 prompt section
• 工具级 prompt
• 专项子系统 prompt
• 多 Agent / teammate 模式下的附加 prompt

也就是说，Claude Code 的 prompt 工程不是“写一段厉害的话”，而是“把不同职责的提示词放到不同层，再按运行时状态拼起来”。

一张图看懂 Claude Code 的提示词体系

第一层：主会话的 System Prompt

Claude Code 最核心的 prompt 入口在 constants/prompts.ts。

源码里最醒目的一段是：

function getSimpleIntroSection(outputStyleConfig: OutputStyleConfig | null): string {
  return `
You are an interactive agent that helps users ${
  outputStyleConfig !== null
    ? 'according to your "Output Style" below, which describes how you should respond to user queries.'
    : 'with software engineering tasks.'
} Use the instructions below and the tools available to you to assist the user.

IMPORTANT: You must NEVER generate or guess URLs for the user unless you are confident that the URLs are for helping the user with programming.`
}

这段话定义了 Claude Code 的基础身份：
它不是纯聊天机器人，而是一个带工具、带任务目标、面向软件工程的交互式 Agent。

中文翻译

你是一个交互式智能体，负责帮助用户完成软件工程任务。请结合下面的指令和可用工具来协助用户。
重要：除非你能确定某个 URL 确实是在帮助用户完成编程任务，否则绝不能为用户凭空生成或猜测 URL。

这段 prompt 的作用

• 先确定“身份”
• 再确定“任务域”是软件工程
• 再强调“工具可用”
• 最后给出安全边界

这类 prompt 属于 Claude Code 的总纲提示词。

第二层：System Prompt 不是固定字符串，而是动态分段拼装

Claude Code 并没有把所有系统提示词写死成一个超长模板。
它会把许多 section 动态拼起来：

const dynamicSections = [
  systemPromptSection('session_guidance', () =>
    getSessionSpecificGuidanceSection(enabledTools, skillToolCommands),
  ),
  systemPromptSection('memory', () => loadMemoryPrompt()),
  systemPromptSection('env_info_simple', () =>
    computeSimpleEnvInfo(model, additionalWorkingDirectories),
  ),
  systemPromptSection('language', () =>
    getLanguageSection(settings.language),
  ),
  systemPromptSection('output_style', () =>
    getOutputStyleSection(outputStyleConfig),
  ),
  DANGEROUS_uncachedSystemPromptSection(
    'mcp_instructions',
    () => isMcpInstructionsDeltaEnabled() ? null : getMcpInstructionsSection(mcpClients),
    'MCP servers connect/disconnect between turns',
  ),
]

这说明 Claude Code 的 system prompt 至少由这些部分组成：

• 会话指导
• Memory 记忆
• 环境信息
• 语言偏好
• 输出风格
• MCP 指令

动态装配流程图

中文解释

这意味着 Claude Code 在做的不是：

把一段固定 system prompt 塞给模型

而是在做：

根据当前会话状态，拼装出当前这一轮最合适的 system prompt

这也是它比很多“复制一段提示词”的 AI 工具更工程化的原因。

第三层：用户可以替换或追加 System Prompt

在 main.tsx 里，CLI 直接暴露了 prompt 定制入口：

addOption(new Option('--system-prompt <prompt>', 'System prompt to use for the session').argParser(String))
addOption(new Option('--append-system-prompt <prompt>', 'Append a system prompt to the default system prompt').argParser(String))

而在 utils/queryContext.ts 里，系统又进一步把这两种语义分开处理：

// customSystemPrompt replaces the default system prompt entirely.
// appendSystemPrompt appends extra text after the default system prompt.

中文翻译

customSystemPrompt 会完全替换默认系统提示词。
appendSystemPrompt 会在默认系统提示词后面追加额外内容。

为什么这点很重要

很多产品只有“覆盖 prompt”这一种模式，但 Claude Code 区分了两类需求：

• replace：我要完全换掉默认系统行为
• append：我要保留默认能力，只在末尾增加约束

这是一种很典型的工程设计。
因为绝大多数真实需求并不是“推翻默认 prompt”，而是“在默认 prompt 上叠加额外规则”。

第四层：Teammate 模式还会自动追加额外 prompt

在多 Agent 协作模式下，Claude Code 还会给 teammate 附加专属说明。

main.tsx 里有这样一段：

if (isAgentSwarmsEnabled() && storedTeammateOpts?.agentId && storedTeammateOpts?.agentName && storedTeammateOpts?.teamName) {
  const addendum = getTeammatePromptAddendum().TEAMMATE_SYSTEM_PROMPT_ADDENDUM;
  appendSystemPrompt = appendSystemPrompt ? `${appendSystemPrompt}\n\n${addendum}` : addendum;
}

而真实追加内容定义在 utils/swarm/teammatePromptAddendum.ts：

export const TEAMMATE_SYSTEM_PROMPT_ADDENDUM = `
# Agent Teammate Communication

IMPORTANT: You are running as an agent in a team. To communicate with anyone on your team:
- Use the SendMessage tool with \`to: "<name>"\` to send messages to specific teammates
- Use the SendMessage tool with \`to: "*"\` sparingly for team-wide broadcasts

Just writing a response in text is not visible to others on your team - you MUST use the SendMessage tool.
`

中文翻译

你正在以团队成员 Agent 的身份运行。
如果你要和团队中的其他成员沟通：

• 使用 SendMessage 工具，并把 to 指向具体成员名字
• 只有在必要时才使用 to: "*" 进行全员广播

仅仅输出普通文本，团队里的其他成员是看不到的。
你必须使用 SendMessage 工具。

这段 prompt 的本质

这不是“知识型提示词”，而是角色切换提示词。
它的目标不是让模型更懂代码，而是让模型理解：

• 自己当前处于什么身份
• 自己的可见性边界是什么
• 自己和其他 Agent 的沟通方式是什么

第五层：工具本身也带 prompt

Claude Code 的很多工具不是只有 schema，没有语言说明。
它们本身就带 prompt，用来指导模型“什么时候用、怎么用、不要怎么用”。

这也是 Claude Code 很重要的一层提示词工程。

1. Read 工具的 prompt

tools/FileReadTool/prompt.ts：

return `Reads a file from the local filesystem. You can access any file directly by using this tool.
Assume this tool is able to read all files on the machine. If the User provides a path to a file assume that path is valid.

Usage:
- The file_path parameter must be an absolute path, not a relative path
- By default, it reads up to 2000 lines starting from the beginning of the file
- This tool can only read files, not directories. To read a directory, use an ls command via the Bash tool.
- You will regularly be asked to read screenshots. If the user provides a path to a screenshot, ALWAYS use this tool to view the file at the path.`

中文翻译

这个工具用于读取本地文件系统中的文件。你可以直接使用它访问任意文件。
如果用户给了一个文件路径，可以默认认为这个路径是有效的。

使用规则：

• file_path 参数必须是绝对路径，不能是相对路径
• 默认最多从文件开头读取 2000 行
• 这个工具只能读文件，不能读目录；如果要读目录，请通过 Bash 工具执行 ls
• 用户经常会要求你读取截图；只要用户给了截图路径，就必须使用这个工具来查看

这类工具 prompt 的价值

它并不是在告诉模型“Read 工具存在”。
它是在告诉模型：

• 参数该怎么填
• 哪些输入是非法的
• 什么时候该用别的工具
• 多模态文件应该怎么读

这会直接影响模型的工具选择质量。

2. Bash 工具的 prompt

tools/BashTool/prompt.ts 非常长，因为它承担了大量 Shell 行为约束。

其中一段很关键：

Do NOT use the Bash tool to run commands when a relevant dedicated tool is provided.

中文翻译

当已经提供了更合适的专用工具时，不要用 Bash 工具去执行命令。

这句话看起来简单，但影响非常大。
它实际上是在控制模型的工具路由策略：

• 读文件优先 Read
• 搜索优先 Grep
• glob 匹配优先 Glob
• 只有没有专用工具时才退回到 Bash

也就是说，工具 prompt 不只是文档，它其实在参与“策略控制”。

3. ExitPlanMode 工具的 prompt

Plan Mode 也有自己的 prompt 约束。
这类 prompt 的目标不是教模型写代码，而是规范什么时候可以结束规划、什么时候应该交还用户确认。

这说明 Claude Code 的提示词工程并不是只服务于“主对话”，而是深入到了工具生命周期里。

第六层：专项子系统也会用 prompt

Claude Code 里还有很多不直接暴露给用户的 prompt，它们服务于专项任务。

典型例子包括：

• /init 初始化项目说明
• 记忆筛选与记忆生成
• 工具结果总结
• prompt suggestion
• 子 Agent 默认提示词

这些 prompt 不一定总在主对话里显式出现，但它们会在旁路流程中持续工作。

1. /init 的 prompt

/init 并不是随便生成一个 CLAUDE.md。
它通常会带一套专门的初始化 prompt，让模型去总结：

• 项目结构
• 运行方式
• 常用命令
• 编码规范
• 协作约束

所以它本质上是一个“项目 onboarding prompt”。

2. Tool Summary / Prompt Suggestion

Claude Code 里还有一些 prompt 用于：

• 把工具调用结果压缩成更短总结
• 给出 prompt 建议
• 帮助后续轮次减少冗余上下文

这些 prompt 更偏系统内部调度，不一定出现在普通用户视角里，但对整体体验很关键。

提示词系统在架构中的位置

最后一句话总结

Claude Code 的提示词工程，本质上不是“写一个超强 system prompt”。
它真正厉害的地方是：

• 把 prompt 分层
• 把 prompt 模块化
• 把 prompt 和工具、角色、子系统、运行时状态结合起来

所以从源码视角看，Claude Code 的 prompt 系统更像一个提示词运行时，而不是一段静态文案。