Claude Code 的提示词工程

Claude Code 的提示词工程并非依赖一段“终极 System Prompt”，而是基于一套分层装配的动态提示词系统。该体系将基础身份、会话状态、运行时环境、工具规范与多 Agent 协作规则解耦为独立模块，并在执行时按当前上下文动态拼装。理解这一架构，是掌握 Claude Code 行为逻辑、路由策略与自定义扩展机制的核心。

Claude Code 最核心的提示词入口位于 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.`
}

中文释义：你是一个交互式智能体，负责帮助用户完成软件工程任务（或按下方“Output Style”配置响应）。请结合下面的指令和可用工具来协助用户。重要：除非你能确定某个 URL 确实是在帮助用户完成编程任务，否则绝不能为用户凭空生成或猜测 URL。

这段 Prompt 严格划定了四层逻辑：

• 确立基础身份：交互式 Agent（非纯聊天机器人）
• 锚定任务域：软件工程
• 声明交互前提：工具可用
• 设定安全边界：严禁无依据生成 URL

这构成了 Claude Code 的总纲提示词，决定了其后续所有行为的上限。

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',
  ),
]

该机制至少包含以下核心模块：

• 会话指导 (session_guidance)
• 记忆层 (memory)
• 基础环境信息 (env_info_simple)
• 语言偏好 (language)
• 输出风格配置 (output_style)
• MCP 服务器连接指令 (mcp_instructions)

执行逻辑对比： ❌ 传统模式：把一段固定 system prompt 塞给模型。 ✅ Claude Code 机制：根据当前会话状态，动态拼装出当前这一轮最合适的 system prompt。

这也是其工程化程度远超普通“复制提示词”类 AI 工具的根本原因。

CLI 层在 main.tsx 暴露了两种明确的 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”，而是“在默认能力上叠加约束”。区分 replace 与 append 是典型的防御性设计，兼顾了深度定制与基线稳定性。

在多 Agent 协作（Agent Swarms）模式下，系统会自动向节点注入专属通信规范。当检测到团队会话时，main.tsx 会触发附加逻辑：

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

${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 工具。

本质：这不属于知识型提示词，而是角色切换与权限边界声明。它强制模型明确当前身份（Identity）、通信半径（Visibility Boundary）与交互协议。

Claude Code 的工具不仅提供 JSON Schema，更内建了强约束的自然语言说明，直接干预模型的工具调用决策质量。

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.`

该 Prompt 的价值不在于声明“Read 工具存在”，而在于精准划定参数规范（必须绝对路径）、读取限制（默认 2000 行）、边界条件（只读文件不读目录需调用 Bash ls）及多模态拦截规则（截图路径强制调用此工具）。

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 → 退而求其次才调用 Bash。工具 Prompt 在此充当了隐式的策略控制器。

Plan Mode 同样拥有独立的约束 Prompt，核心目标非代码生成，而是规范“何时可结束规划”与“何时需交还用户决策”，确保主对话外的工具生命周期受控。

Claude Code 后台运行着一套不直接暴露于主窗口的隐式 Prompt 网络，专门支撑侧向任务流：

• /init 初始化指令：并非随机生成 CLAUDE.md，而是调用专属 Prompt 强制模型结构化输出项目结构、运行方式、常用命令、编码规范与协作约束，本质是自动化 Onboarding。
• Tool Summary / Prompt Suggestion：用于压缩冗杂的 Tool Call 结果、生成后续轮次引导建议。此类提示词侧重系统内部上下文调度与冗余削减，虽用户不可见，却直接决定交互流畅度。

• 非静态文案，而是分层运行时：核心提示词、动态拼接层、工具约束与角色规范分离，随会话状态实时重组。
• 强路由策略控制：工具自带 Prompt 直接干预模型决策树（如 Bash 的降级使用原则、Read 的多模态拦截）。
• replace vs append 分离设计：CLI 明确区分“覆盖基线”与“叠加约束”，兼顾深度定制与系统稳定性。
• 隐性调度层决定体验：/init、Tool Summary、Prompt Suggestion 等旁路提示词虽不可见，却主导初始化质量与上下文效率。
• 架构演进方向：Claude Code 已将 Prompt 工程从“文本编排”升级为“模块化运行时调度”，为复杂 Agent 协作奠定底层基础。