Claude Code Prompt解剖：五层运行时控制协议

本文深入剖析了Claude Code项目的Prompt工程体系，重点从工程实现角度分析了其分层架构和运行时机制。该系统采用五层Prompt结构：主系统Prompt定义核心行为约束；动态System Section实现可变信息管理；Tool Prompt指导工具使用；任务型Prompt驱动后台能力；模式化Prompt支持特殊协作场景。文章详细阐述了Prompt的装配链路，包括主入口getSystem

Tale_G

267人浏览 · 2026-04-07 08:46:24

Tale_G · 2026-04-07 08:46:24 发布

本文聚焦 Claude Code 项目中的 Prompt 体系，重点从工程实现角度梳理：Prompt 如何分层、如何进入运行时、如何与工具和模式耦合，以及这些设计对代码代理系统意味着什么。

1. 文档目的

本文档基于当前仓库快照与 cli.js.map 内嵌的 sourcesContent，对 Claude Code 项目的 Prompt 体系进行一次面向工程实现的深度 Review，重点说明：

Prompt 在项目中的分层方式
Prompt 如何被组装、缓存、覆盖与追加
各类 Tool Prompt 的职责与设计风格
各类任务型 Prompt 的原码片段与用途
这些 Prompt 背后的设计理念、工程权衡与学习价值

需要特别说明的是：当前仓库并不是传统的完整 src/ 源码仓库，Prompt 源码主要来自 cli.js.map 中的 source map 内容。因此本文中的“源码 Prompt”来自 source map 还原结果，而不是直接来自落盘的 src/*.ts 文件。

为了让结构更清楚，全文会依次经过五个层次：

基础认知与运行时装配
Prompt 分类与源码材料
学习提炼与方法论总结
迁移、模板与实战落地
局限、代价与评估

后续章节都可以放回这五个层次里理解，而不是把整篇文档视为一条线性长笔记。

2. 基础认知：Prompt 体系总览

从运行时结构看，Claude Code 的 Prompt 并不是一段单独的大字符串，而是一套分层提示体系。可以拆成五层：

2.1 第一层：主系统 Prompt

这是一切行为约束的根。它定义：

代理身份
输出风格
工具使用原则
软件工程任务执行原则
风险动作边界
动态会话补充信息入口

对应核心文件：

../src/constants/prompts.ts
../src/utils/systemPrompt.ts
../src/constants/systemPromptSections.ts

2.2 第二层：动态 System Section

Claude Code 没有把所有提示内容都写死在一个 Prompt 中，而是将会变动的信息拆成多个动态 section，例如：

当前 session 的特殊指导
当前环境信息
当前语言偏好
MCP 指令
scratchpad 目录说明
tool result 清理提醒
token budget 指令
proactive/autonomous 模式说明

这些 section 会被动态解析，并且带缓存策略。

2.3 第三层：Tool Prompt

每一个工具都带有自己的模型侧说明。Tool Prompt 的作用不是给用户看，而是告诉模型：

这个工具是干什么的
什么情况下该用
什么情况下不该用
参数怎么理解
使用该工具时的约束与边界是什么

这是 Claude Code 工具调用质量高的关键原因之一。

2.4 第四层：任务型 Prompt

除了主系统 Prompt 和 Tool Prompt，项目还存在一类“内部任务 Prompt”，用于驱动特定后台能力，例如：

会话压缩
记忆提取
Session Memory 更新
Dream/Consolidation
Magic Docs 文档更新

这类 Prompt 往往不是面向用户交互，而是面向内部流程或异步能力。

2.5 第五层：模式化/协作型 Prompt

这类 Prompt 负责在特殊模式下改变代理行为，例如：

teammate 协作模式
Chrome 浏览器自动化模式
autonomous/proactive 模式
agent/fork/subagent 模式
plan/worktree 模式

这说明 Claude Code 的 Prompt 体系不是“一个模型，一个人设”，而是“一个运行时，多种 Prompt 叠加态”。

2.6 功能架构图

为了把前面的五层 Prompt 结构放回系统运行方式中理解，可以先看下面这张功能架构图：

这张图表达的核心关系有三层：

用户输入先进入运行时编排层，由对话状态管理、Prompt 装配逻辑和工具执行器共同决定当前轮如何行动
Prompt 控制层并不是单段文本，而是主系统 Prompt、动态 section、Tool Prompt、模式 addendum 与内部任务 Prompt 的组合
工具层与后台服务层共同支撑执行闭环：前者负责当前轮动作，后者负责长会话压缩、记忆提取、文档沉淀与下轮恢复

如果把 Claude Code 看成一个系统，这张图最重要的结论是：Prompt 不只是模型输入材料，而是连接“运行时编排”“工具路由”“状态恢复”“协作模式”的控制中枢。

3. 运行时装配：Prompt 组装链路

Prompt 的核心设计价值，不在于句子写得多优美，而在于“如何进入运行时”。Claude Code 在这方面的工程化程度很高。

3.1 主入口：`getSystemPrompt()`

主系统 Prompt 的起点在 ../src/constants/prompts.ts 的 getSystemPrompt()。这个函数负责：

收集工具列表
识别当前配置和模式
构建静态 section
注册动态 section
解析动态 section
最终返回 system prompt 数组

这个设计比“拼一个大字符串”成熟得多，因为它允许：

对不同 section 做独立演化
对动态片段做缓存
对模式切换做局部替换
控制 prompt cache 失效范围

3.2 动态 section 注册：`systemPromptSection()`

../src/constants/systemPromptSections.ts 中定义了两个关键工厂：

systemPromptSection(name, compute)
DANGEROUS_uncachedSystemPromptSection(name, compute, reason)

这套机制本质是在做 Prompt Section Registry。它的作用是：

对稳定 section 做缓存，减少每轮重算
对会变化的 section 标记 cache break
在 /clear、/compact 等动作后清空 section 状态

这是一种非常值得学习的 Prompt 工程模式：

不把 Prompt 当成纯文本，而把 Prompt 当成“可缓存、可失效、可局部重建的运行时资源”。

3.3 生效优先级：`buildEffectiveSystemPrompt()`

../src/utils/systemPrompt.ts 中的 buildEffectiveSystemPrompt() 负责决定最终采用哪套 Prompt。优先级可以概括为：

override system prompt
coordinator prompt
agent prompt
custom system prompt
default system prompt
append system prompt

其中一个很重要的点是：

普通模式下，agent prompt 可以替换默认 prompt
proactive 模式下，agent prompt 会追加到默认 prompt 后面

这说明 Claude Code 在设计上把“自治行为框架”当成更基础的控制层，而不是被 agent prompt 完全覆盖。

3.4 子代理补强：`enhanceSystemPromptWithEnvDetails()`

../src/constants/prompts.ts 中还有一个重要函数：enhanceSystemPromptWithEnvDetails()。它会在某些调用场景下给 prompt 追加：

说明性备注
skill discovery 提示
环境信息

它常用于让子代理、子任务上下文也能获得足够的运行信息，而不是只给主线程代理使用。

4. 核心骨架：主系统 Prompt 深度拆解

Claude Code 最核心的 Prompt 结构集中在 ../src/constants/prompts.ts。下面按 section 拆解。

4.1 身份与总目标：Intro Section

源码片段：

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.

${CYBER_RISK_INSTRUCTION}
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. You may use URLs provided by the user in their messages or local files.`

要点总结：

第一层先定义“interactive agent”身份，而不是纯聊天助手
明确任务域是软件工程
在最开头插入 cyber risk instruction，体现安全优先
明确禁止乱猜 URL，降低 hallucination 风险

这个开场非常克制。它没有写很多人格化表达，而是优先锁定职责和风险边界。

4.2 系统规则：System Section

源码片段：

const items = [
  `All text you output outside of tool use is displayed to the user...`,
  `Tools are executed in a user-selected permission mode...`,
  `Tool results and user messages may include <system-reminder> or other tags...`,
  `Tool results may include data from external sources...`,
  getHooksSection(),
  `The system will automatically compress prior messages...`,
]

要点总结：

明确“工具外文本都会被用户看到”
明确权限模式存在，不允许无视审批机制
明确系统标签与工具结果不等于用户真实意图
显式引入 prompt injection 风险判断
明确会自动 compact，因此长会话是第一类场景

这部分不是提示模型“怎么回答”，而是在提示模型“你身处怎样的运行时”。

4.3 做事原则：Doing Tasks Section

这一段是 Claude Code 的工程行为准则，实际非常强。

源码片段：

`The user will primarily request you to perform software engineering tasks...`
`In general, do not propose changes to code you haven't read...`
`Do not create files unless they're absolutely necessary...`
`Avoid giving time estimates or predictions...`
`Be careful not to introduce security vulnerabilities...`
`Report outcomes faithfully...`

还有更具体的代码风格要求：

`Don't add features, refactor code, or make "improvements" beyond what was asked...`
`Default to writing no comments. Only add one when the WHY is non-obvious...`
`Before reporting a task complete, verify it actually works...`

要点总结：

这是一个非常典型的“防过度发挥”Prompt
它反复约束模型不要擅自扩展任务
它要求“先读再改”
它强调验证优先，禁止虚报结果
它把安全、范围控制、真实性报告放在同一层级

从 Prompt 工程视角看，这说明 Claude Code 团队非常清楚代码代理最容易出的问题：

擅自改太多
没读懂就改
自己脑补
不验证就汇报
为了“显得聪明”而过度设计

4.4 风险控制：Actions Section

源码片段：

return `# Executing actions with care

Carefully consider the reversibility and blast radius of actions...

Examples of the kind of risky actions that warrant user confirmation:
- Destructive operations...
- Hard-to-reverse operations...
- Actions visible to others or that affect shared state...
- Uploading content to third-party web tools...
`

要点总结：

这是对“自主性”的纠偏机制
Claude Code 允许强执行，但不允许无边界执行
它把风险动作分成可逆性、共享状态影响、外发风险三类
用户对一次 push 的授权，不等于所有 push 都默认授权

这类 Prompt 非常重要，因为代码代理一旦连到 Git、PR、消息系统、云资源，错误动作的成本会急剧升高。

4.5 工具优先级：Using Your Tools Section

源码片段：

`Do NOT use the ${BASH_TOOL_NAME} to run commands when a relevant dedicated tool is provided...`
`To read files use ${FILE_READ_TOOL_NAME} instead of cat, head, tail, or sed`
`To edit files use ${FILE_EDIT_TOOL_NAME} instead of sed or awk`
`To create files use ${FILE_WRITE_TOOL_NAME} instead of cat with heredoc or echo redirection`
`To search for files use ${GLOB_TOOL_NAME} instead of find or ls`
`To search the content of files, use ${GREP_TOOL_NAME} instead of grep or rg`

要点总结：

Claude Code 不希望模型把 Bash 当万能入口
它希望每种行为尽量映射到显式工具
显式工具更利于权限审计、UI 展示、参数校验、用户复核
还特别要求无依赖工具并行调用，体现效率优化

这不是单纯“工具介绍”，而是一种强烈的 tool-first routing 策略。

4.6 Session-Specific Guidance

这一 section 是典型的运行态 Prompt。它会根据当前工具集和模式动态生成，例如：

是否允许 AskUserQuestion
是否启用 AgentTool
是否启用 Explore Agent
是否启用 SkillTool
是否启用 DiscoverSkills
是否启用 Verification Agent

源码片段：

hasAskUserQuestionTool
  ? `If you do not understand why the user has denied a tool call, use the ${ASK_USER_QUESTION_TOOL_NAME} to ask them.`
...
hasAgentTool ? getAgentToolSection() : null,
...
hasSkills
  ? `/<skill-name> ... Use the ${SKILL_TOOL_NAME} tool to execute them...`

要点总结：

这部分让 Prompt 不再是静态手册，而是“按当前能力投喂”
模型只在工具真的可用时收到对应操作指导
减少无效提示，降低认知噪声
也降低 prompt cache 被频繁击穿的风险

4.7 输出风格与沟通效率

源码片段：

return `# Output efficiency

IMPORTANT: Go straight to the point...
Keep your text output brief and direct...
Focus text output on:
- Decisions that need the user's input
- High-level status updates at natural milestones
- Errors or blockers that change the plan
`

以及：

return [`# Tone and style`, ...prependBullets(items)].join(`\n`)

要点总结：

要求模型避免输出流水账式内容
要求输出直接、可读、避免冗余
指定代码引用格式，便于 IDE 导航
禁止在 tool call 前加冒号等 UI 噪声

这说明 Claude Code 的 Prompt 设计不仅关注任务完成，还关注“终端 UX”。

5. 动态机制：Prompt 片段与缓存设计

Claude Code 的一个高级设计点，是把 Prompt 分成静态前缀与动态尾部，并通过 SYSTEM_PROMPT_DYNAMIC_BOUNDARY 做边界分隔。

5.1 为什么要做边界

源码中明确写出：

// === BOUNDARY MARKER - DO NOT MOVE OR REMOVE ===
...(shouldUseGlobalCacheScope() ? [SYSTEM_PROMPT_DYNAMIC_BOUNDARY] : []),

要点总结：

静态内容尽量稳定，提升 prompt cache 命中率
动态内容放在 boundary 之后，避免每次变化都使整个前缀失效
运行时 bits 多时，不会造成组合爆炸式 cache fragmentation

这是 Prompt 工程里的生产级技巧。

5.2 环境信息 Prompt

computeEnvInfo() / computeSimpleEnvInfo() 负责将环境塞给模型，例如：

当前工作目录
是否为 Git 仓库
平台与 shell
OS 版本
额外工作目录
模型知识截止时间

这使模型具备最基本的执行环境感知。

5.3 Scratchpad Prompt

源码片段：

return `# Scratchpad Directory

IMPORTANT: Always use this scratchpad directory for temporary files instead of \`/tmp\`...
Only use \`/tmp\` if the user explicitly requests it.
`

要点总结：

为临时文件提供统一隔离目录
降低污染用户工程目录或系统目录的概率
让 temporary files 具备 session 归属

5.4 Function Result Clearing Prompt

源码片段：

return `# Function Result Clearing

Old tool results will be automatically cleared from context to free up space...`

以及配套提醒：

const SUMMARIZE_TOOL_RESULTS_SECTION =
  `When working with tool results, write down any important information you might need later in your response...`

要点总结：

明确告诉模型：工具结果不是永久保留的
要求模型在必要时自行摘要关键结果
这相当于在给“长上下文运行时”设计记忆续航机制

5.5 Proactive / Autonomous Prompt

源码片段：

return `# Autonomous work

You are running autonomously. You will receive \`<${TICK_TAG}>\` prompts...
If you have nothing useful to do on a tick, you MUST call ${SLEEP_TOOL_NAME}.
On your very first tick in a new session, greet the user briefly...
`

要点总结：

这是独立模式下的人机节奏控制 Prompt
它定义 tick 的含义、空闲时行为、唤醒节奏、何时该睡眠
明确不要“still waiting”这类空耗 token 的回复
允许在无人盯屏时更自主，在用户聚焦时更协作

这已经超出普通 Prompt 的范畴，更接近 agent operating protocol。

5.6 Default Agent Prompt

源码片段：

export const DEFAULT_AGENT_PROMPT = `You are an agent for Claude Code, Anthropic's official CLI for Claude. Given the user's message, you should use the tools available to complete the task. Complete the task fully—don't gold-plate, but don't leave it half-done. When you complete the task, respond with a concise report covering what was done and any key findings — the caller will relay this to the user, so it only needs the essentials.`

要点总结：

这是给子代理/代理调用链使用的默认身份 Prompt
关键关键词是：complete the task fully、don’t gold-plate、concise report
它把“做完”和“别过度做”同时写进去，避免子代理跑偏

6. 工具层总览：Tool Prompt 总体设计

前五章解决的是“Claude Code 的 Prompt 骨架如何成立”。从这一章开始，文档转入第二个层次：按功能分类梳理各类 Prompt，重点回答“具体有哪些 Prompt、分别负责什么、设计边界在哪里”。

Tool Prompt 是 Claude Code 质量的另一根支柱。它们不是简单描述参数，而是在向模型编码一套“什么时候该用、什么时候应避免使用”的路由逻辑。

6.1 Tool Prompt 的共性设计

通看多个工具 Prompt，可以归纳出几条共性：

先定义用途，再定义边界
经常强调“优先使用专用工具，而不是 Bash”
经常强调路径必须是绝对路径
经常强调不要交互式命令、不要无意义轮询
强调参数格式和限制，而不是只写自然语言用途
对高风险工具添加防误用策略

6.2 Tool Prompt 的模块化分组

项目中的 Tool Prompt 可以分为八组：

文件与代码操作
Shell 与系统执行
检索与发现
网络与远程
计划与任务编排
Agent / Skill / Team 协作
模式切换
MCP 与外部资源

下面逐组展开。

7. 工具层一：文件与代码操作类 Prompt

7.1 FileReadTool

对应文件：../src/tools/FileReadTool/prompt.ts

核心导出：

FILE_READ_TOOL_NAME
DESCRIPTION
LINE_FORMAT_INSTRUCTION
OFFSET_INSTRUCTION_DEFAULT
OFFSET_INSTRUCTION_TARGETED
renderPromptTemplate()

要点总结：

重点强调绝对路径
强调 limit 必填
明确支持 offset、分页读取
说明最多读取多少行
说明图片也支持读取
鼓励“尽量少但足够”的读取范围

这类 Prompt 的价值是防止模型：

一次性读大文件
频繁重复读取
用错路径格式
把图片/二进制当文本乱处理

7.2 FileEditTool

对应文件：../src/tools/FileEditTool/prompt.ts

核心导出：

getEditToolDescription()

要点总结：

强调“编辑现有文件”
倾向结构化替换而不是命令行 hack
与读文件先行策略配套
强调使用专用编辑工具而非 Bash 修改

7.3 FileWriteTool

对应文件：../src/tools/FileWriteTool/prompt.ts

核心导出：

FILE_WRITE_TOOL_NAME
DESCRIPTION
getWriteToolDescription()

要点总结：

专门承载创建/覆盖文件
替代 heredoc、echo 重定向等 shell 写文件方式
与 FileRead、FileEdit 构成文件操作闭环

7.4 GlobTool

对应文件：../src/tools/GlobTool/prompt.ts

导出：

GLOB_TOOL_NAME
DESCRIPTION

要点总结：

明确用于按文件名/模式搜索
与 Grep 形成职责分离

7.5 GrepTool

对应文件：../src/tools/GrepTool/prompt.ts

导出：

GREP_TOOL_NAME
getDescription()

要点总结：

明确用于内容搜索
允许 regex、type、glob、上下文行数等参数
取代直接用 grep/rg

7.6 LSPTool 与 NotebookEditTool

对应文件：

../src/tools/LSPTool/prompt.ts
../src/tools/NotebookEditTool/prompt.ts

要点总结：

LSPTool 把“语言服务能力”显式暴露给模型
NotebookEditTool 针对 .ipynb 这种特殊格式提供专用修改方式

这体现了 Claude Code 的 Prompt 并不是只服务普通文本文件。

8. 工具层二：Shell、系统与网络类 Prompt

8.1 BashTool

对应文件：../src/tools/BashTool/prompt.ts

核心导出：

getDefaultTimeoutMs()
getMaxTimeoutMs()
getSimplePrompt()

源码片段：

return [
  'Executes a given bash command and returns its output.',
  '',
  "The working directory persists between commands, but shell state does not...",
  '',
  `IMPORTANT: Avoid using this tool to run ${avoidCommands} commands...`,
  ...
].join('\n')

Prompt 中明确包含这些策略：

优先使用专用工具，不要拿 Bash 代替读写搜改
路径包含空格时必须加双引号
尽量避免 cd
支持 timeout
支持后台运行
并行命令优先放在同一轮 tool call 中
Git 操作必须谨慎
不要无意义 sleep

这是一个非常强的“反滥用 Prompt”。

8.2 PowerShellTool

对应文件：../src/tools/PowerShellTool/prompt.ts

作用与 BashTool 类似，但面向 PowerShell 语境。设计上保持一致，体现跨 shell 的 Prompt 规范化。

8.3 WebFetchTool

对应文件：../src/tools/WebFetchTool/prompt.ts

导出：

WEB_FETCH_TOOL_NAME
DESCRIPTION
makeSecondaryModelPrompt()

要点总结：

用于抓取网页并转 markdown
强调 URL 必须完整有效
强调只读
通常作为“需要看网页正文”时的获取器

8.4 WebSearchTool

对应文件：../src/tools/WebSearchTool/prompt.ts

导出：

WEB_SEARCH_TOOL_NAME
getWebSearchPrompt()

要点总结：

用于互联网检索
Prompt 通常会限制使用频率
强调只在实时信息缺失或必须联网时使用

8.5 RemoteTriggerTool 与 ScheduleCronTool

对应文件：

../src/tools/RemoteTriggerTool/prompt.ts
../src/tools/ScheduleCronTool/prompt.ts

要点总结：

RemoteTriggerTool 面向 claude.ai 远程触发 API
ScheduleCronTool 面向定时任务创建、删除、列举
它们说明 Claude Code 已不只是“本地代码代理”，而是具备远程工作流能力

9. 工具层三：计划、任务与协作类 Prompt

9.1 TodoWriteTool

对应文件：../src/tools/TodoWriteTool/prompt.ts

源码片段：

export const PROMPT = `Use this tool to create and manage a structured task list for your current coding session...
Exactly ONE task must be in_progress at any time...
ONLY mark a task as completed when you have FULLY accomplished it...`

要点总结：

这是强流程管理 Prompt
它要求任务状态实时同步
明确只能一个 in_progress
不允许把失败任务标成完成

这说明 Claude Code 希望模型具备“可审计的工作流”。

9.2 AskUserQuestionTool

对应文件：../src/tools/AskUserQuestionTool/prompt.ts

源码片段：

export const ASK_USER_QUESTION_TOOL_PROMPT = `Use this tool when you need to ask the user questions during execution...
Plan mode note: In plan mode, use this tool to clarify requirements...
Do NOT use this tool to ask "Is my plan ready?" ... use ${EXIT_PLAN_MODE_TOOL_NAME} ...`

要点总结：

这段 Prompt 不只是规定“可以问用户”
还定义了什么情况下不应发问
特别限制 plan mode 中的错误用法
减少模型把“请确认”当作逃避执行的默认动作

9.3 Task 系列工具

对应文件：

TaskCreateTool/prompt.ts
TaskGetTool/prompt.ts
TaskListTool/prompt.ts
TaskUpdateTool/prompt.ts
TaskStopTool/prompt.ts

要点总结：

比 TodoWrite 更结构化
更接近长期任务系统或队列系统
表明 Claude Code 同时支持“会话内任务列表”和“实体化任务对象”两种层次

9.4 AgentTool

对应文件：../src/tools/AgentTool/prompt.ts

核心导出：

formatAgentLine()
shouldInjectAgentListInMessages()
getPrompt()

Prompt 中强调：

复杂、多步骤任务可以交给 agent
子代理有专门类型
fork 模式可以把大量上下文隔离出主线程
如果你自己已经是 fork，就不要继续重复委派

要点总结：

这是 Claude Code 的“上下文分流 Prompt”
它不仅做任务分派，还做上下文窗口保护
把代理协作当作 Prompt 层面的原生能力

9.5 SkillTool 与 ToolSearchTool

对应文件：

../src/tools/SkillTool/prompt.ts
../src/tools/ToolSearchTool/prompt.ts

要点总结：

SkillTool 负责加载技能 Prompt
ToolSearchTool 负责按语义发现延迟加载工具
这说明 Prompt 也被当成“按需扩展资源”，而非固定常量

9.6 SendMessage、TeamCreate、TeamDelete

对应文件：

../src/tools/SendMessageTool/prompt.ts
../src/tools/TeamCreateTool/prompt.ts
../src/tools/TeamDeleteTool/prompt.ts

要点总结：

这些 Prompt 让多代理协作具备实体化操作接口
Claude Code 不只是单代理，而是在向 team runtime 演化

10. 工具层四：模式切换类 Prompt

10.1 EnterPlanMode / ExitPlanMode

对应文件：

../src/tools/EnterPlanModeTool/prompt.ts
../src/tools/ExitPlanModeTool/prompt.ts

要点总结：

计划模式不是简单“先想再做”
它是一个显式的运行模式切换
Prompt 会告诉模型进入后该做什么、退出时该怎么请求批准

10.2 EnterWorktree / ExitWorktree

对应文件：

../src/tools/EnterWorktreeTool/prompt.ts
../src/tools/ExitWorktreeTool/prompt.ts

要点总结：

worktree 在 Claude Code 中不是纯 Git 技术细节
它已经提升为模型能理解的工作模式

10.3 BriefTool、ConfigTool、SleepTool

对应文件：

../src/tools/BriefTool/prompt.ts
../src/tools/ConfigTool/prompt.ts
../src/tools/SleepTool/prompt.ts

要点总结：

BriefTool 约束压缩输出风格
ConfigTool 允许模型调整和读取配置
SleepTool 是 autonomous 模式的节奏控制器

SleepTool 尤其值得关注：它说明“等待”本身也是一个一等行为，需要通过 Prompt 显式规范。

11. 工具层五：MCP 与外部资源 Prompt

对应文件：

../src/tools/MCPTool/prompt.ts
../src/tools/ListMcpResourcesTool/prompt.ts
../src/tools/ReadMcpResourceTool/prompt.ts

要点总结：

Claude Code 把 MCP 作为一等扩展系统
Prompt 中既有资源枚举，也有资源读取语义
说明模型不仅能调用工具，还能理解“外部资源目录”

这种 Prompt 设计为生态接入留出了标准位置。

12. 特殊模式层：模式化 Prompt

12.1 Chrome Browser Automation Prompt

对应文件：../src/utils/claudeInChrome/prompt.ts

关键导出：

BASE_CHROME_PROMPT
CHROME_TOOL_SEARCH_INSTRUCTIONS
getChromeSystemPrompt()
CLAUDE_IN_CHROME_SKILL_HINT
CLAUDE_IN_CHROME_SKILL_HINT_WITH_WEBBROWSER

源码片段：

export const CHROME_TOOL_SEARCH_INSTRUCTIONS = `**IMPORTANT: Before using any chrome browser tools, you MUST first load them using ToolSearch.**`

以及：

export const CLAUDE_IN_CHROME_SKILL_HINT = `**Browser Automation**: Chrome browser tools are available via the "claude-in-chrome" skill...`

要点总结：

Chrome 工具不是默认直接可用，而是有加载前提
需要先通过 ToolSearch 或 SkillTool 启用
同时区分“开发浏览器任务”和“用户真实 Chrome 会话”

这是一种非常成熟的 Prompt 分流：

WebBrowser 负责开发态页面
claude-in-chrome 负责用户真实登录态浏览器

12.2 Team Teammate Addendum

对应文件：../src/utils/swarm/teammatePromptAddendum.ts

源码片段：

export const TEAMMATE_SYSTEM_PROMPT_ADDENDUM = `
# Agent Teammate Communication

IMPORTANT: You are running as an agent in a team...
Just writing a response in text is not visible to others on your team - you MUST use the SendMessage tool.
`

要点总结：

明确 teammate 不是直接对用户说话
团队内沟通必须通过 SendMessage tool
限制模型误以为普通文本对同伴可见

这是典型的“运行环境可见性约束 Prompt”。

12.3 Buddy Prompt

对应文件：../src/buddy/prompt.ts

导出：

companionIntroText()
getCompanionIntroAttachment()

作用：

为 companion/buddy 类型的交互模式提供附加提示文本
更偏角色化和入口态提示，而非核心工程控制 Prompt

13. 内部任务层：任务型 Prompt

这一类 Prompt 面向 Claude Code 内部流程，是学习这个项目时非常值得注意的一组。

13.1 Compact Prompt

对应文件：../src/services/compact/prompt.ts

关键导出：

getPartialCompactPrompt()
getCompactPrompt()
formatCompactSummary()
getCompactUserSummaryMessage()

源码片段：

const NO_TOOLS_PREAMBLE = `CRITICAL: Respond with TEXT ONLY. Do NOT call any tools.`

const BASE_COMPACT_PROMPT = `Your task is to create a detailed summary of the conversation so far...`

要点总结：

compact 任务被明确禁止调用工具
要求先写 <analysis>，再写 <summary>
明确要记录用户请求、文件、错误、当前状态、下一步
本质是在做“可恢复开发上下文的高保真摘要”

这个 Prompt 非常强，几乎是 Claude Code 长会话能力的核心保障。

13.2 Session Memory Prompt

对应文件：../src/services/SessionMemory/prompts.ts

关键导出：

DEFAULT_SESSION_MEMORY_TEMPLATE
loadSessionMemoryTemplate()
loadSessionMemoryPrompt()
buildSessionMemoryUpdatePrompt()
truncateSessionMemoryForCompact()

要点总结：

Session Memory 与 transcript 不同
transcript 是对话事实记录
Session Memory 更像跨轮稳定记忆模板
update prompt 负责指导模型如何增量更新记忆

13.3 Extract Memories Prompt

对应文件：../src/services/extractMemories/prompts.ts

关键导出：

buildExtractAutoOnlyPrompt()
buildExtractCombinedPrompt()

要点总结：

从对话中自动抽取有长期价值的记忆
区分自动抽取与组合抽取逻辑
说明 Claude Code 的记忆系统并非单一 prompt

13.4 AutoDream Consolidation Prompt

对应文件：../src/services/autoDream/consolidationPrompt.ts

关键导出：

buildConsolidationPrompt()

要点总结：

用于 dream / consolidation 场景
更偏知识沉淀、信息整合，而非即时交互

13.5 Magic Docs Prompt

对应文件：../src/services/MagicDocs/prompts.ts

关键导出：

buildMagicDocsUpdatePrompt()

要点总结：

用于文档自动更新或结构化文档生成
属于 Claude Code 的文档型 agent 能力

14. 附录一：Prompt 文件总索引

前面的第 6-13 章已经按功能把 Prompt 分层展开；从这一章开始，文档切换到“附录与索引”视角，方便回到源码时做定位、对照和复查。

下面按模块给出本项目当前可识别的 Prompt 相关源码文件总表。

14.1 核心系统 Prompt 文件

../src/constants/prompts.ts
../src/utils/systemPrompt.ts
../src/constants/systemPromptSections.ts

14.2 工具 Prompt 文件

../src/tools/AgentTool/prompt.ts
../src/tools/AskUserQuestionTool/prompt.ts
../src/tools/BashTool/prompt.ts
../src/tools/BriefTool/prompt.ts
../src/tools/ConfigTool/prompt.ts
../src/tools/EnterPlanModeTool/prompt.ts
../src/tools/EnterWorktreeTool/prompt.ts
../src/tools/ExitPlanModeTool/prompt.ts
../src/tools/ExitWorktreeTool/prompt.ts
../src/tools/FileEditTool/prompt.ts
../src/tools/FileReadTool/prompt.ts
../src/tools/FileWriteTool/prompt.ts
../src/tools/GlobTool/prompt.ts
../src/tools/GrepTool/prompt.ts
../src/tools/LSPTool/prompt.ts
../src/tools/ListMcpResourcesTool/prompt.ts
../src/tools/MCPTool/prompt.ts
../src/tools/NotebookEditTool/prompt.ts
../src/tools/PowerShellTool/prompt.ts
../src/tools/ReadMcpResourceTool/prompt.ts
../src/tools/RemoteTriggerTool/prompt.ts
../src/tools/ScheduleCronTool/prompt.ts
../src/tools/SendMessageTool/prompt.ts
../src/tools/SkillTool/prompt.ts
../src/tools/SleepTool/prompt.ts
../src/tools/TaskCreateTool/prompt.ts
../src/tools/TaskGetTool/prompt.ts
../src/tools/TaskListTool/prompt.ts
../src/tools/TaskStopTool/prompt.ts
../src/tools/TaskUpdateTool/prompt.ts
../src/tools/TeamCreateTool/prompt.ts
../src/tools/TeamDeleteTool/prompt.ts
../src/tools/TodoWriteTool/prompt.ts
../src/tools/ToolSearchTool/prompt.ts
../src/tools/WebFetchTool/prompt.ts
../src/tools/WebSearchTool/prompt.ts

14.3 内部服务 Prompt 文件

../src/services/MagicDocs/prompts.ts
../src/services/SessionMemory/prompts.ts
../src/services/autoDream/consolidationPrompt.ts
../src/services/compact/prompt.ts
../src/services/extractMemories/prompts.ts

14.4 特殊模式与协作 Prompt 文件

../src/utils/claudeInChrome/prompt.ts
../src/utils/swarm/teammatePromptAddendum.ts
../src/buddy/prompt.ts

15. 附录二：重点 Prompt 的原码摘录

这一节不再只做“摘录”，而是补充三层内容：

保留关键源码片段
给出中文化意译，便于用户直接学习
解释这段 Prompt 在工程运行时中的真实作用

这里的“中文化”不是机械直译，而是尽量保留原文约束强度、语气和工程语义后的学习版意译。

15.1 默认子代理 Prompt

export const DEFAULT_AGENT_PROMPT = `You are an agent for Claude Code, Anthropic's official CLI for Claude. Given the user's message, you should use the tools available to complete the task. Complete the task fully—don't gold-plate, but don't leave it half-done. When you complete the task, respond with a concise report covering what was done and any key findings — the caller will relay this to the user, so it only needs the essentials.`

意译：

你是 Claude Code 的一个代理。收到用户消息后，你要使用当前可用工具把任务完成。要把任务真正做完，但不要过度发挥，也不要做一半就停。完成后，请给出一份简明报告，说明做了什么、发现了什么关键点；调用你的上层代理会把这份报告转述给用户，所以只保留必要信息即可。

工程解读：

这段 Prompt 很短，但目标极其明确：完成任务、不要过度设计、输出简报
Complete the task fully 用来防止子代理只做调研不落地，或者做完一半就把结果回抛
don't gold-plate 用来抑制子代理“顺手优化”“顺手重构”“顺手补架构”的冲动
concise report 说明子代理的直接受众不是终端用户，而是上层调度者
这是一种非常典型的“委派型 Prompt”：强调执行闭环，而不是开放式聊天

可借鉴点：

如果你在自己的 Agent 系统里也有主代理与子代理协作，这段 Prompt 值得直接借鉴
子代理 Prompt 不需要人格化，它最需要的是边界清楚、交付清楚、汇报格式清楚

15.2 自治模式 Prompt

return `# Autonomous work

You are running autonomously. You will receive \`<${TICK_TAG}>\` prompts...
Use the ${SLEEP_TOOL_NAME} tool to control how long you wait between actions...
If you have nothing useful to do on a tick, you MUST call ${SLEEP_TOOL_NAME}.
On your very first tick in a new session, greet the user briefly...
`

意译：

你当前处于自治运行模式。系统会周期性给你发送 <tick> 一类的保活消息，让你在多轮之间继续工作。你需要把这些 tick 理解成“你醒了，现在该继续做什么”。你要通过 Sleep 工具来决定下一次唤醒前等待多久：等待慢任务时可以睡久一点，快速迭代时可以睡短一点。如果某次被唤醒后没有任何有价值的事情可做，你必须调用 Sleep，而不是输出“我还在等”“目前没事做”这种空耗轮次的文本。在一个新会话的第一次唤醒里，只需简短问候并询问用户想做什么，不要未经指示就开始扫描代码或修改项目。

工程解读：

这不是普通系统提示，而是一份“自治代理调度协议”
它把 tick、sleep、空闲、首次唤醒、用户在线状态都编码成行为规则
其中最关键的，不是“能否自主”，而是“自主时如何不浪费 token、不骚扰用户、不扰乱节奏”
If you have nothing useful to do ... MUST call Sleep 本质上是在限制代理空转
“首次唤醒只问候、不乱探索”说明团队意识到自治模式如果默认过于激进，会明显伤害用户体验

可借鉴点：

如果你要做长时运行代理，这段 Prompt 的价值非常高
它提示我们：自治不是一句“你可以自己决定”，而是需要完整定义节奏、空闲策略和唤醒协议

15.3 输出效率 Prompt

return `# Output efficiency

IMPORTANT: Go straight to the point. Try the simplest approach first without going in circles. Do not overdo it. Be extra concise.
Keep your text output brief and direct. Lead with the answer or action, not the reasoning...
`

意译：

直接进入重点。优先尝试最简单的方案，不要兜圈子，不要用力过猛，尽量简洁。你输出给用户的文字要短、直接，并且先说结论或动作，而不是先铺垫一长串推理。不要写无意义的前言，不要重复用户的话；只保留用户理解当前状态真正需要的信息。

工程解读：

许多 Prompt 文档只讲“功能正确”，但 Claude Code 连“输出密度”和“终端可读性”都写进了系统规则
这里强调的不只是篇幅更短，而是“先答案、后解释”
它反对把推理过程平铺成流水账，因为 IDE 用户更关心结果、阻塞点与下一步
这也解释了 Claude Code 为什么在产品体验上强调简明汇报，而不是大段链路叙事

可借鉴点：

做 CLI Agent 或 IDE Agent 时，输出风格本身就是产品能力的一部分
好 Prompt 不只是让模型更聪明，也要让模型更“好用”

15.4 风险动作 Prompt

return `# Executing actions with care

Carefully consider the reversibility and blast radius of actions...
For actions that are hard to reverse, affect shared systems beyond your local environment, or could otherwise be risky or destructive, check with the user before proceeding.
`

意译：

你在执行动作时，要认真评估这个动作是否可逆、影响范围有多大。像本地改文件、跑测试这类可逆动作通常可以直接做；但对于难以回退、会影响本地环境之外的共享系统、或者可能造成破坏的动作，应该先向用户确认，再继续。暂停确认的成本通常很低，但错误动作的代价可能非常高。用户曾经批准过某个动作，并不等于在所有上下文里都默认授权；授权只对明确给定的范围有效。

工程解读：

这一段真正关键的是两个词：reversibility 和 blast radius
这说明团队不是只从“危险/不危险”二元视角写 Prompt，而是在训练模型按工程风险维度做判断
这段 Prompt 把“共享状态”看得很重，例如远端分支、消息系统、数据库、第三方服务
明确反对“用户上次同意过，所以这次也能做”这类简化推理

可借鉴点：

如果你的 Agent 会连 Git、云平台、消息平台、数据库，这段 Prompt 几乎是必修
很多事故并非因为模型不会执行，而是因为模型不知道何时应先暂停确认

15.5 问用户工具 Prompt

export const ASK_USER_QUESTION_TOOL_PROMPT = `Use this tool when you need to ask the user questions during execution. This allows you to:
1. Gather user preferences or requirements
2. Clarify ambiguous instructions
3. Get decisions on implementation choices as you work
4. Offer choices to the user about what direction to take.

Plan mode note: In plan mode, use this tool to clarify requirements or choose between approaches BEFORE finalizing your plan. Do NOT use this tool to ask "Is my plan ready?" or "Should I proceed?" ...`

意译：

当你在执行过程中确实需要向用户提问时，可以使用这个工具。它适用于四类场景：收集用户偏好或需求、澄清含糊指令、在实现过程中获取关键决策、向用户提供多个方向供选择。在 plan mode 中，这个工具只用于澄清需求或在不同方案之间做选择，不能拿来问“我的计划可以了吗”“我要继续吗”。如果你需要的是计划审批，应使用退出计划模式的专用方式，而不是把确认请求塞进普通提问里。

工程解读：

这段 Prompt 的重点不是“允许提问”，而是“限制无效提问”
它直接封住了模型最常见的偷懒路径：遇到任何不确定就问一句“要不要继续”
在 plan mode 中尤其严格，因为用户在 UI 里未必能看到完整计划
所以这里不仅是行为约束，也是产品交互约束：不允许模型提一个用户根本无法有效回答的问题

可借鉴点：

很多 Agent 的“低效感”都来自高频、低信息量确认
好的提问工具 Prompt 应该规定“什么时候问”，更要规定“什么时候绝不能问”

15.6 TodoWrite 工作流 Prompt

export const PROMPT = `Use this tool to create and manage a structured task list for your current coding session...
1. Complex multi-step tasks...
6. When you start working on a task - Mark it as in_progress BEFORE beginning work. Ideally you should only have one todo as in_progress at a time
7. After completing a task - Mark it as completed...
`

意译：

使用这个工具为当前编码会话创建和维护结构化任务列表。它帮助你跟踪进度、组织复杂任务，也让用户看到当前整体进展。对于复杂多步骤任务、非平凡任务、用户明确要求使用 todo、一次给出多项任务、收到新的用户指令等场景，都应该主动使用它。开始做某个任务之前，应先把它标记为 in_progress；理想情况下，同时只能有一个任务处于进行中。任务真正完成后，再把它标记为 completed，并补充实现中发现的新后续任务。

工程解读：

这段 Prompt 本质上把“任务状态同步”做成系统硬约束
它不是把 Todo 当 UI 装饰，而是把 Todo 当成执行过程的一部分
only one todo as in_progress 很关键，这能强制代理维持主线，避免并行叙事和状态失真
“收到新指令立刻登记”被列为推荐动作，这说明任务面板同时承担需求记忆功能

可借鉴点：

如果你要做可审计型 Agent，Prompt 必须把状态更新写成明确规则
单有任务列表组件没有用，真正起作用的是模型是否被要求持续维护它

15.7 Compact 摘要 Prompt

const NO_TOOLS_PREAMBLE = `CRITICAL: Respond with TEXT ONLY. Do NOT call any tools.`
const BASE_COMPACT_PROMPT = `Your task is to create a detailed summary of the conversation so far...`

意译：

严格要求：你只能输出文本，绝对不要调用任何工具。你的任务是为当前对话生成一份尽可能详细、可恢复上下文的总结。总结需要覆盖用户请求、已分析或修改的文件、关键函数与代码模式、出现过的错误与修复、用户反馈、当前仍未完成的工作，以及紧接着最应该继续的下一步。

工程解读：

TEXT ONLY 是内部任务 Prompt 的典型写法，先锁死边界，再定义目标
compact 的目标不是“写个摘要”，而是“生成可恢复工作现场的接力文档”
它要求保留文件名、函数名、报错、待办和最近工作点，这些都是恢复工程上下文的关键锚点
这说明 Claude Code 的长会话能力并不只是靠大上下文，而是靠专门的 Prompt 驱动压缩与接续

可借鉴点：

如果你的 Agent 需要跨长时会话继续工作，就不能只做普通摘要
你需要像这里一样，把“恢复现场所需的信息结构”写进 Prompt

15.8 Team 协作 Prompt

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

意译：

你当前是团队中的一个代理。若要与队友沟通，必须使用 SendMessage：给具体成员发消息时用 to: "<name>"，需要全员广播时才谨慎使用 to: "*"。单纯在文本里写一句话并不会被你的队友看到，因此团队内沟通必须走消息工具，而不是普通回复文本。

工程解读：

这是非常典型的“可见性约束 Prompt”
多代理系统最容易出的问题之一，是模型搞不清“文本回复”和“团队通信”是不是同一件事
这段 Prompt 直接把通信信道与普通输出区分开，从而减少协作型幻觉
sparingly 也很重要，它防止广播泛滥，保护团队通道质量

可借鉴点：

一旦系统中存在多个接收者、多个通道，就必须把“谁能看到什么”写进 Prompt
否则模型非常容易把“我说了”误当成“别人已经收到了”

15.9 工具优先级 Prompt

`Do NOT use the ${BASH_TOOL_NAME} to run commands when a relevant dedicated tool is provided...`

意译：

如果系统已经提供了更合适的专用工具，就不要再用 Bash 去兜底执行命令。能用文件读取工具时，就不再使用 cat/head/tail；能用编辑工具时，就不再使用 sed/awk；能用文件搜索工具时，就不再使用 find/ls；能用内容搜索工具时，就不再使用 grep/rg。

工程解读：

这是 Claude Code 非常核心的一条 routing 原则：专用工具优先，Shell 兜底但不主导
因为专用工具更利于做参数校验、权限审计、UI 展示、用户复核和结构化结果处理
这条 Prompt 实际改善了三个方面：调用正确率、结果稳定性、可审计性
这也会间接减少 shell hack，因为 Prompt 从一开始就在抑制“凡事依赖 Bash 兜底”的倾向

可借鉴点：

很多 Agent 工具链效果不佳，不是因为工具不够，而是因为模型总会优先走最熟悉的 Shell 路径
如果要提升工具调用质量，必须用 Prompt 明确建立“工具优先级”

15.10 Bash 简化 Prompt

const toolPreferenceItems = [
  `File search: Use ${GLOB_TOOL_NAME} (NOT find or ls)`,
  `Content search: Use ${GREP_TOOL_NAME} (NOT grep or rg)`,
  `Read files: Use ${FILE_READ_TOOL_NAME} (NOT cat/head/tail)`,
  `Edit files: Use ${FILE_EDIT_TOOL_NAME} (NOT sed/awk)`,
  `Write files: Use ${FILE_WRITE_TOOL_NAME} (NOT echo >/cat <<EOF)`,
  'Communication: Output text directly (NOT echo/printf)',
]

意译：

在命令行环境中，也要遵循工具分工：搜文件用 Glob，不要用 find 或 ls；搜内容用 Grep，不要用 grep/rg；读文件用 Read，不要用 cat/head/tail；改文件用 Edit，不要用 sed/awk；写文件用 Write，不要用重定向或 heredoc；和用户沟通时直接输出文本，不要再绕一层 echo/printf。

工程解读：

这一段把“工具优先级”从主系统 Prompt 再次下沉到 Bash Prompt 里，形成双重约束
这说明团队很清楚：模型一旦进入 Shell 语境，会本能回到命令行习惯，所以必须再次提醒
它还把“沟通”纳入规范，要求将自然语言直接发给用户，而不是伪装成终端输出
这是 Prompt 设计上的一个重要技巧：对高频误用点重复设防，而不是只提醒一次

可借鉴点：

如果某类错误高频出现，不要怕在多个层次重复约束
高质量 Prompt 工程往往不是靠一句最强提示，而是靠多层次、一致性的规则网络

16. 学习提炼一：设计理念总结

如果说前半部分主要回答“有哪些 Prompt、它们位于哪里、运行时如何拼起来”，那么从这一章开始，文档进入第三个层次：从事实整理转向方法提炼，总结 Claude Code Prompt 体系背后的共性原则。

综合整个项目的 Prompt 设计，可以总结出八条核心理念。

16.1 Prompt 不是文案，而是运行时协议

Claude Code 的 Prompt 设计已经远远超过“写几句系统提示”的范围，更接近一套协议：

规定身份
规定权限边界
规定模式切换
规定工具路由
规定摘要方式
规定协作通信方式

16.2 把 Prompt 做成分层系统，而不是单块文本

好处是：

易于维护
易于扩展
易于缓存
易于按模式注入
易于灰度实验

16.3 把“不要做什么”写得和“要做什么”一样清楚

Claude Code 的许多 Prompt 都在防止模型犯下工程上代价最高的错误：

不要未经确认擅自修改
不要基于未验证信息推断
不要发起低信息量确认
不要擅自执行 push
不要无意义地进入 sleep
不要把 Bash 当成通用替代方案

16.4 Prompt 与 Tool 设计耦合非常深

这里的 Tool Prompt 不是附属说明书，而是工具调度质量的一部分。Prompt 直接影响：

工具选择
参数质量
并发策略
风险控制
用户可审计性

16.5 长会话能力离不开 Prompt 工程

Claude Code 的 compact、memory、summary、result clearing 提示共同支撑长会话。没有这套 Prompt：

上下文会迅速退化
工具结果会丢失关键事实
resume 质量会明显下降

16.6 Prompt 必须感知模式与环境

例如：

proactive 模式
team 模式
chrome 模式
plan 模式
worktree 模式
agent 模式

每一种模式都会注入不同 Prompt。高质量 agent 不能只有一套固定系统提示。

16.7 真实性汇报是 Prompt 的硬要求

项目多处都在强调：

没验证就不能说已完成
测试失败就要如实报告
不要制造“绿灯假象”

这表明 Claude Code 把“可信汇报”视为核心产品能力，而不是附加要求。

16.8 Prompt 设计服务的是产品体验

不少约束看起来像工程细节，本质上都在服务用户体验：

减少无效确认
减少废话
减少 tool misuse
减少错误提交
增强可恢复性
增强可复核性

17. 学习提炼二：对学习 Prompt 工程的启发

如果你想从这个项目里学 Prompt 设计，最值得关注的不是某一句“金句”，而是背后的方法论。

17.1 把行为拆层

不要把身份、任务、工具、模式、风险、输出风格全写进一段 Prompt。应该像 Claude Code 一样：

基础身份层
任务行为层
工具路由层
动态环境层
模式增强层
内部任务层

17.2 为不同内部任务单独设计 Prompt

不要拿同一套主 Prompt 去做：

代码编辑
上下文压缩
记忆提取
文档更新

Claude Code 的做法是每种后台任务有单独 Prompt。

17.3 显式管理缓存

Prompt cache 命中率是生产系统的重要成本项。Claude Code 的做法值得直接借鉴：

稳定内容前置
动态内容后置
用 boundary 做分界
用 registry 控制 section 缓存

17.4 把失败模式写进 Prompt

很多团队只写“理想情况怎么做”，Claude Code 会写：

如果用户拒绝工具怎么办
如果无事可做怎么办
如果工具结果会被清理怎么办
如果是 team agent 怎么沟通

这才更接近生产级 Prompt。

17.5 用 Prompt 把系统能力解释给模型

Prompt 的一个关键作用，不是“控制模型语气”，而是向模型解释系统：

工具有哪些
权限如何工作
会话如何 compact
scratchpad 在哪里
模式如何切换
谁能看到消息

Claude Code 在这一点上做得非常彻底。

18. 阶段小结：从架构视角看 Claude Code Prompt

Claude Code 的 Prompt 体系有三个最值得借鉴的地方：

它是分层的，而不是单一长提示
它是工程化的，而不是文案化的
它把工具、记忆、协作、模式、安全、恢复全部纳入 Prompt 设计

如果用一句话概括：

Claude Code 的 Prompt 不是“让模型更会说话”，而是“让模型在复杂软件工程运行时中更会做事、更少犯错、还能长期持续协作”。

对于研究代码代理、CLI Agent、长会话系统、Prompt 工程平台化的人来说，这个项目很有参考价值。真正值得借鉴的不是某条提示词，而是它如何把 Prompt 做成一个有边界、有优先级、有缓存策略、有模式感知能力的运行时控制系统。

19. 附录三：Prompt 导出项速查表

这一组内容仍然属于附录，但重点已经从“文件在哪里”转向“应该先看哪些导出项、每个导出项最值得关注什么”。

前面的“Prompt 文件总索引”更偏文件维度；这一节补成“学习者速查版”，不仅告诉你文件在哪，还告诉你该文件最值得关注的导出项、它们分别负责什么、学习时应该先看什么。

19.1 核心系统 Prompt 速查

文件	关键导出 / 函数	职责	学习重点
`../src/constants/prompts.ts`	`getSystemPrompt()`	主系统 Prompt 总装配入口	看它如何拼接静态规则、动态 section、工具提示、环境信息
`../src/constants/prompts.ts`	`DEFAULT_AGENT_PROMPT`	子代理默认身份 Prompt	看“做完但不过度做”的短 Prompt 写法
`../src/constants/prompts.ts`	`enhanceSystemPromptWithEnvDetails()`	给子代理或特殊调用链补环境说明	看主线程外的 Prompt 补强策略
`../src/constants/prompts.ts`	`getProactiveSection()`	自治模式规则	看 tick、sleep、首次唤醒、空闲行为如何被协议化
`../src/constants/prompts.ts`	`getActionsSection()`	风险动作边界	看可逆性、影响范围、确认策略如何进入 Prompt
`../src/constants/prompts.ts`	`getUsingYourToolsSection()`	工具优先级与路由策略	看专用工具优先、Bash 降级兜底的设计
`../src/constants/prompts.ts`	`getOutputEfficiencySection()`	用户可见输出风格约束	看终端 UX 如何被写进系统 Prompt
`../src/utils/systemPrompt.ts`	`buildEffectiveSystemPrompt()`	决定最终到底用哪套 Prompt	看 override、coordinator、agent、custom、append 的优先级关系
`../src/constants/systemPromptSections.ts`	`systemPromptSection()`	注册可缓存 section	看稳定片段如何做缓存友好处理
`../src/constants/systemPromptSections.ts`	`DANGEROUS_uncachedSystemPromptSection()`	注册会击穿缓存的动态 section	看为何要显式标注 cache break
`../src/constants/systemPromptSections.ts`	`resolveSystemPromptSections()`	统一解析所有 section	看 section registry 如何进入最终字符串

阅读建议：

如果你第一次读 Claude Code 的 Prompt 体系，优先顺序建议是：getSystemPrompt() → buildEffectiveSystemPrompt() → systemPromptSection() → 各个 section 函数
这样看更容易理解“谁负责总装配、谁负责优先级、谁负责缓存、谁负责具体内容”

19.2 文件与代码操作类 Prompt 速查

文件	关键导出 / 函数	职责	学习重点
`../src/tools/FileReadTool/prompt.ts`	`DESCRIPTION`、`LINE_FORMAT_INSTRUCTION`、`renderPromptTemplate()`	定义文件读取规则	看绝对路径、分页读取、limit 必填、图片支持
`../src/tools/FileEditTool/prompt.ts`	`getEditToolDescription()`	定义如何编辑现有文件	看“先读后改”和结构化编辑导向
`../src/tools/FileWriteTool/prompt.ts`	`DESCRIPTION`、`getWriteToolDescription()`	定义新建/覆盖文件行为	看为什么要避免 heredoc 与 echo 重定向
`../src/tools/GlobTool/prompt.ts`	`DESCRIPTION`	文件名/路径模式搜索	看与 Grep 的职责分离
`../src/tools/GrepTool/prompt.ts`	`getDescription()`	文件内容搜索	看 regex、glob、type、上下文行参数如何暴露给模型
`../src/tools/LSPTool/prompt.ts`	相关 Prompt 导出	语言服务能力说明	看 IDE 级语义能力如何被提示给模型
`../src/tools/NotebookEditTool/prompt.ts`	相关 Prompt 导出	Notebook 专用编辑规则	看非普通文本文件如何有专用 Prompt

阅读建议：

这一组最值得借鉴的内容，不是单个句子，而是“输入限制 + 参数说明 + 边界约束”的组合写法
Claude Code 在这里明显不是把 Prompt 当自然语言帮助文档，而是在写“工具接口契约”

19.3 Shell、网络与外部访问类 Prompt 速查

文件	关键导出 / 函数	职责	学习重点
`../src/tools/BashTool/prompt.ts`	`getSimplePrompt()`、`getDefaultTimeoutMs()`、`getMaxTimeoutMs()`	Shell 执行行为说明	看 Bash 如何被限制为兜底工具，而不是主入口
`../src/tools/PowerShellTool/prompt.ts`	相关 Prompt 导出	PowerShell 规则	看跨 shell 约束的一致性
`../src/tools/WebFetchTool/prompt.ts`	`DESCRIPTION`、`makeSecondaryModelPrompt()`	抓取网页正文	看只读约束、URL 格式、Markdown 转换
`../src/tools/WebSearchTool/prompt.ts`	`getWebSearchPrompt()`	联网搜索	看“何时必须联网、何时禁止滥用联网”
`../src/tools/RemoteTriggerTool/prompt.ts`	相关 Prompt 导出	远程触发任务	看本地 CLI 如何扩展到远程工作流
`../src/tools/ScheduleCronTool/prompt.ts`	相关 Prompt 导出	定时任务调度	看“等待与计划任务”如何成为一等系统能力

阅读建议：

这一组尤其适合观察 Claude Code 如何把外部副作用写进 Prompt
一旦工具与网络、远程系统、异步执行有关，Prompt 的边界就会明显更强

19.4 任务管理与协作类 Prompt 速查

文件	关键导出 / 函数	职责	学习重点
`../src/tools/TodoWriteTool/prompt.ts`	`PROMPT`	会话内任务列表管理	看如何让模型维护可审计流程
`../src/tools/AskUserQuestionTool/prompt.ts`	`ASK_USER_QUESTION_TOOL_PROMPT`	用户提问与决策收集	看如何约束“何时问、何时不要问”
`../src/tools/AgentTool/prompt.ts`	`getPrompt()`、`formatAgentLine()`	子代理委派与协作	看上下文分流和委派边界
`../src/tools/SkillTool/prompt.ts`	相关 Prompt 导出	技能加载入口	看 Prompt 如何支持延迟加载能力
`../src/tools/ToolSearchTool/prompt.ts`	相关 Prompt 导出	语义检索工具与延迟能力发现	看工具发现机制如何被提示驱动
`../src/tools/SendMessageTool/prompt.ts`	相关 Prompt 导出	多代理消息通信	看沟通通道如何显式化
`../src/tools/TeamCreateTool/prompt.ts`	相关 Prompt 导出	团队创建	看多代理组织结构如何进入模型认知
`../src/tools/TeamDeleteTool/prompt.ts`	相关 Prompt 导出	团队删除	看团队生命周期操作的边界

阅读建议：

如果你关心多代理系统，这一组是必读
Claude Code 在这里已经不是“单智能体 + 一堆工具”，而是“带任务系统和通信系统的代理运行时”

19.5 模式切换类 Prompt 速查

文件	关键导出 / 函数	职责	学习重点
`../src/tools/EnterPlanModeTool/prompt.ts`	相关 Prompt 导出	进入计划模式	看“先规划再执行”如何被做成显式模式
`../src/tools/ExitPlanModeTool/prompt.ts`	相关 Prompt 导出	退出计划模式	看计划审批如何和普通问答分离
`../src/tools/EnterWorktreeTool/prompt.ts`	相关 Prompt 导出	进入 worktree 模式	看 Git 工作隔离如何变成模型可理解的模式
`../src/tools/ExitWorktreeTool/prompt.ts`	相关 Prompt 导出	退出 worktree 模式	看模式结束后的清理与返回
`../src/tools/BriefTool/prompt.ts`	相关 Prompt 导出	输出压缩模式	看输出风格如何被显式切换
`../src/tools/ConfigTool/prompt.ts`	相关 Prompt 导出	配置读写与查看	看“配置”如何进入模型控制面
`../src/tools/SleepTool/prompt.ts`	相关 Prompt 导出	自治模式节奏控制	看等待行为如何被提升为一等动作

阅读建议：

这一组最能体现 Claude Code 的一个核心思路：Prompt 不是静态人设，而是模式感知控制层

19.6 内部服务 Prompt 速查

文件	关键导出 / 函数	职责	学习重点
`../src/services/compact/prompt.ts`	`getPartialCompactPrompt()`、`getCompactPrompt()`、`formatCompactSummary()`	长会话压缩与总结	看恢复现场型摘要如何设计
`../src/services/SessionMemory/prompts.ts`	`buildSessionMemoryUpdatePrompt()`	会话稳定记忆更新	看 transcript 与 memory 的分工
`../src/services/extractMemories/prompts.ts`	`buildExtractAutoOnlyPrompt()`、`buildExtractCombinedPrompt()`	从对话抽取长期记忆	看不同提取策略如何拆成不同 Prompt
`../src/services/autoDream/consolidationPrompt.ts`	`buildConsolidationPrompt()`	Dream / consolidation 整合	看异步知识沉淀任务的 Prompt 写法
`../src/services/MagicDocs/prompts.ts`	`buildMagicDocsUpdatePrompt()`	文档更新与结构化文档生成	看“文档 agent”型内部任务如何独立建 Prompt

阅读建议：

做长会话系统时，这一组比工具 Prompt 更重要
它直接决定系统能不能在上下文压缩、记忆提取、文档沉淀后继续稳定工作

19.7 特殊模式 Prompt 速查

文件	关键导出 / 函数	职责	学习重点
`../src/utils/claudeInChrome/prompt.ts`	`BASE_CHROME_PROMPT`、`getChromeSystemPrompt()`、`CLAUDE_IN_CHROME_SKILL_HINT`	Chrome 自动化模式	看内置浏览器能力与扩展技能如何分流
`../src/utils/swarm/teammatePromptAddendum.ts`	`TEAMMATE_SYSTEM_PROMPT_ADDENDUM`	teammate 协作补充 Prompt	看可见性与通信约束
`../src/buddy/prompt.ts`	`companionIntroText()`、`getCompanionIntroAttachment()`	buddy / companion 模式	看更轻角色化 Prompt 的入口设计

阅读建议：

这一组适合观察 Prompt 如何随产品形态切换而变化
Claude Code 没有把所有特殊场景集中堆叠进主 Prompt，而是通过 addendum 或独立 Prompt 做模块化扩展

20. 附录四：Prompt 注入时序图解

前面讲了很多 Prompt 内容，但真正决定系统行为的，是这些 Prompt 何时被创建、何时被覆盖、何时被追加、何时被缓存、何时被截断。下面按运行时顺序把链路串起来。

20.1 总览：从用户输入到最终 Prompt 生效

可以把 Claude Code 的 Prompt 生效链路概括成下面 8 步：

收集当前运行态上下文
组装默认系统 Prompt
注册并解析动态 section
根据模式与配置计算最终有效 Prompt
为工具调用注入 Tool Prompt
在特殊模式下追加补充 Prompt
会话过长时切换到 compact / memory 类内部 Prompt
将结果写回 transcript、memory 或文档系统，供下一轮继续使用

这 8 步不是完全线性死板执行，但足以帮助学习者建立整体心智模型。

20.2 第一步：收集运行态上下文

主入口是 getSystemPrompt()。从已有分析可以看出，它在真正拼 Prompt 之前，会先收集一批运行时信息，例如：

当前可用工具集合
当前工作目录与环境信息
输出风格配置
是否存在额外工作目录
是否有 MCP client
当前是否启用了 proactive、team、chrome、skills 等模式能力

这一阶段的本质不是“开始写 Prompt”，而是“先把运行时状态结构化”。

可借鉴点：

很多项目的问题，在于 Prompt 先被写死，之后再临时塞变量
Claude Code 的顺序相反：先理解当前能力，再决定该给模型看哪些规则

20.3 第二步：生成默认系统 Prompt 骨架

getSystemPrompt() 会生成一套默认主系统 Prompt。你可以把它理解成基础宪法层，里面通常包括：

身份与职责
输出规则
做事原则
风险动作约束
工具使用优先级
会话环境信息

这一层的特点是：

相对稳定
跨任务复用
决定代理的基础行为风格

可借鉴点：

一个成熟系统通常需要稳定的基础骨架层，不能每次都从零拼接

20.4 第三步：注册动态 section，并处理缓存边界

Claude Code 没有把所有系统信息直接串成一整块字符串，而是通过 systemPromptSection() 注册“可缓存 section”，通过 DANGEROUS_uncachedSystemPromptSection() 注册“可能击穿缓存的动态 section”。

这一步的工程意义非常大：

稳定片段不必每轮重算
易变片段可以显式标记为 cache break
/clear、/compact 这类动作可以更准确地让部分 section 失效

这里实际涉及两件事：

Prompt 内容管理
Prompt 缓存管理

可借鉴点：

Prompt 一旦进生产，成本问题就不只是 token 数量，还包括 cache 命中率
Claude Code 把缓存语义写进 Prompt 装配层，这是非常值得借鉴的工程做法

20.5 第四步：根据优先级选择“最终有效 Prompt”

默认系统 Prompt 并不是最终一定发给模型的版本。buildEffectiveSystemPrompt() 还会基于不同来源做最终决策。

从目前梳理出的逻辑看，优先级大致可以理解为：

override system prompt
coordinator prompt
agent prompt
custom system prompt
default system prompt
append system prompt

这意味着：

某些场景下，默认主 Prompt 可以被整体替换
某些场景下，agent prompt 是增强，而不是覆盖
append system prompt 更像尾部补充规则

可借鉴点：

Prompt 系统一旦存在多来源输入，就必须定义清晰的优先级
否则越往后做，越容易出现规则冲突、覆盖混乱和不可解释行为

20.6 第五步：把工具说明作为 Tool Prompt 注入

当系统把工具暴露给模型时，并不是只传一个工具名和 JSON schema。每个工具还会附带自己的 Prompt 说明，用来定义：

工具的职责是什么
什么情况下应使用
什么情况下不应使用
参数的含义是什么
使用时有哪些边界与风险

这一步是 Claude Code 质量的重要来源，因为它显式解决了两个问题：

模型是否选对工具
模型是否以正确方式使用工具

可借鉴点：

很多工具系统只做 schema，不做强 Prompt 约束，最后模型就会“知道有工具，但不会正确使用工具”
Claude Code 则把路由规则、风险控制、参数语义都写进 Tool Prompt

20.7 第六步：在特殊模式下叠加补充 Prompt

如果当前处于特殊模式，系统会在主 Prompt 之外叠加额外约束。例如：

proactive 模式加上自治调度协议
teammate 模式加上团队通信约束
chrome 模式加上浏览器自动化与 skill 加载提示
子代理场景加上环境补强说明

这一步非常关键，因为它体现了“多态 Prompt 架构”：

基础 Prompt 负责稳定共性
模式 addendum 负责局部增强

可借鉴点：

当你的系统有多种工作模式时，不要试图把所有规则塞进一个终极 Prompt
更好的做法是维持主骨架稳定，再按模式叠加最小增量 Prompt

20.8 第七步：长会话时切换到内部任务 Prompt

当会话过长，或者系统需要做摘要、记忆提取、文档更新时，运行时会切换到另一类内部 Prompt，例如：

compact Prompt
session memory update Prompt
extract memories Prompt
magic docs update Prompt

这些 Prompt 和主系统 Prompt 的差别非常大：

目标更单一
输出结构更严格
通常禁止多余工具调用
明确服务于“压缩、抽取、沉淀、恢复”类后台任务

可借鉴点：

这是 Claude Code 的一个核心经验：不要用同一套主 Prompt 去承担所有后台任务
后台任务需要专门的行为边界和专门的输出格式

20.9 第八步：把结果回灌给下一轮运行时

Prompt 生效不是单轮闭环，它会影响下一轮：

transcript 会保存会话事实
compact summary 会在需要时接管长会话恢复
session memory 会沉淀更稳定的用户/项目信息
magic docs 会把部分结果转成结构化文档

因此 Claude Code 的 Prompt 体系不是只面向“当前回答”，而是面向“下一轮还能继续接上”。

可借鉴点：

真正的工程型 Agent 不是只把当前轮答对，而是要把状态传给未来
所以 Prompt 设计一定要和 transcript、memory、summary 机制联动思考

20.10 一张文字版时序图

为了更容易记忆，可以把整条链路简化成下面这张文字版时序图：

用户输入
  -> 运行时收集环境 / 工具 / 模式信息
  -> getSystemPrompt() 生成默认主系统 Prompt
  -> systemPromptSection() / uncached section 解析动态片段
  -> buildEffectiveSystemPrompt() 计算最终有效 Prompt
  -> Tool Prompt 按当前工具集注入
  -> 特殊模式 addendum 叠加
  -> 模型执行当前轮任务
  -> 若上下文过长或需后台处理，则切换到 compact / memory / docs Prompt
  -> transcript / memory / summary 回写
  -> 下一轮继续

这张图的学习重点在于：Prompt 不是“调用模型前的一段说明”，而是贯穿整个运行时生命周期的控制链。

20.11 为什么这条链路值得学习

Claude Code 这套设计之所以有学习价值，不只是因为 Prompt 写得好，而是因为它把 Prompt 放在了正确的位置：

用 Prompt 解释系统能力
用 Prompt 约束工具路由
用 Prompt 处理风险动作
用 Prompt 管理长会话恢复
用 Prompt 适配不同工作模式
用 Prompt 支撑多代理协作

也就是说，Prompt 在这里不是“给模型一点灵感”，而是“把复杂软件工程运行时翻译成模型能执行的协议层”。

21. 学习路线：Prompt 源码精读路线

从这一章开始，文档不再只提供信息，而是进一步帮助你建立“怎么读”的顺序感。它更适合作为精读时的路线图，而不是一次性通读材料。

到这一节为止，这份文档已经把 Prompt 分层、工具 Prompt、内部任务 Prompt、注入链路都梳理了一遍。接下来更重要的问题是：

如果我要真正去读源码，应该按什么顺序看，才不会一上来就迷失在大量 Prompt 文件里？

下面给出一条更适合学习者的精读路线。

21.1 第一阶段：先建立总装配视角

第一阶段不要急着看几十个工具 Prompt，而应该先看“总控层”。

建议顺序：

../src/constants/prompts.ts
../src/utils/systemPrompt.ts
../src/constants/systemPromptSections.ts

为什么先看这三处：

prompts.ts 告诉你主系统 Prompt 里到底装了什么
systemPrompt.ts 告诉你多套 Prompt 来源是如何决策优先级的
systemPromptSections.ts 告诉你动态 section 为什么可以缓存、何时会失效

这一阶段的阅读目标不是背 Prompt 文案，而是先回答三个问题：

主 Prompt 是谁拼出来的
多来源 Prompt 冲突时谁说了算
动态 Prompt 为什么不会每轮都把缓存打爆

如果这三个问题没搞清楚，后面看单个 Prompt 文件时很容易“只见树木，不见森林”。

21.2 第二阶段：再看最核心的系统 section

当你已经知道总装配链路后，第二阶段应该回到 ../src/constants/prompts.ts，重点精读下面几类 section：

身份与总目标 section
Doing Tasks section
Actions section
Using Your Tools section
Output efficiency section
Proactive / Autonomous section

推荐阅读顺序：

Doing Tasks
Actions
Using Your Tools
Output efficiency
Proactive

为什么这样排：

Doing Tasks 决定“平时怎么干活”
Actions 决定“哪些动作需要更谨慎”
Using Your Tools 决定“工具优先级与路由策略”
Output efficiency 决定“如何把结果告诉用户”
Proactive 决定“自治模式下如何安排节奏”

学习重点：

Claude Code 最有价值的地方，往往不是“让模型做什么”
而是“在什么情况下不能乱做”“应该优先怎么做”“完成后应该如何简洁可信地汇报”

21.3 第三阶段：重点精读 6 个最有代表性的 Tool Prompt

工具 Prompt 数量较多，不宜一开始全部通读。更适合作为入门切口的是下面 6 个：

FileReadTool/prompt.ts
FileEditTool/prompt.ts
BashTool/prompt.ts
AskUserQuestionTool/prompt.ts
TodoWriteTool/prompt.ts
AgentTool/prompt.ts

这 6 个几乎覆盖了 Claude Code 的核心行为面：

如何读代码
如何改代码
如何使用 Shell
如何向用户提问
如何维护任务状态
如何把任务分派给子代理

阅读这 6 个文件时，最建议用一套固定问题去审视它们：

这个工具的默认用途是什么
Prompt 明确限制了哪些误用
Prompt 有没有定义“什么情况下应避免使用它”
Prompt 有没有把参数格式、边界、风险写清楚
这个 Prompt 是不是在帮系统做路由，而不仅仅是在写工具描述

如果你带着这些问题去看，就会发现 Claude Code 的 Tool Prompt 远比表面看起来更工程化。

21.4 第四阶段：转向长会话与内部任务 Prompt

当你已经理解主 Prompt 和 Tool Prompt 后，就该看 Claude Code 最强、也最容易被忽视的一层：内部服务 Prompt。

推荐顺序：

../src/services/compact/prompt.ts
../src/services/SessionMemory/prompts.ts
../src/services/extractMemories/prompts.ts
../src/services/MagicDocs/prompts.ts
../src/services/autoDream/consolidationPrompt.ts

为什么先看 compact：

它直接决定长会话能否恢复
它也最能说明 Claude Code 不是只靠大上下文，而是靠 Prompt 工程做上下文治理

为什么再看 memory / extract：

这两者能帮助你理解 transcript、summary、memory 不是一回事
Claude Code 不是“把所有历史都塞回去”，而是分层保存不同类型的信息

为什么 Magic Docs 也值得看：

它说明 Prompt 不只服务于聊天和代码修改
它还可以服务于文档生成、文档更新与知识沉淀

21.5 第五阶段：最后看特殊模式与协作 Prompt

这一阶段更适合已经对主链路有整体把握后再读。

建议顺序：

../src/utils/swarm/teammatePromptAddendum.ts
../src/utils/claudeInChrome/prompt.ts
../src/buddy/prompt.ts

为什么把它们放最后：

它们是模式增强层，不是主骨架
如果先看这类 Prompt，很容易误以为这些特殊规则是系统的普适逻辑

学习重点：

它们最值得借鉴的不是“具体 wording”
而是“如何在不污染主 Prompt 的前提下，为特殊场景单独叠加行为约束”

21.6 一条适合真正学习的阅读顺序

如果你想把上面的阶段压缩成一条可执行路线，可以直接按下面顺序读：

prompts.ts 里的 getSystemPrompt()
systemPrompt.ts 里的 buildEffectiveSystemPrompt()
systemPromptSections.ts 里的 systemPromptSection()
prompts.ts 里的 Doing Tasks / Actions / Using Your Tools / Proactive
FileReadTool / FileEditTool / BashTool
AskUserQuestionTool / TodoWriteTool / AgentTool
compact/prompt.ts
SessionMemory/prompts.ts 与 extractMemories/prompts.ts
MagicDocs/prompts.ts
teammatePromptAddendum.ts 与 claudeInChrome/prompt.ts

这条顺序的优势是：

先有主干，再看枝叶
先看系统控制层，再看具体工具
先看单轮执行，再看长会话恢复
先看通用逻辑，再看特殊模式

22. 学习避坑：学 Prompt 工程时最容易踩的误区

读 Claude Code 这类项目时，很多人会因为关注点放错，而错过真正重要的设计价值。下面列几个最常见的误区。

22.1 误区一：只抄“金句”，不看运行时位置

很多人在学习 Prompt 时，最先做的往往是摘几句看起来很强的提示词，例如：

“Do not overdo it”
“Use the simplest approach first”
“Do NOT call any tools”

问题在于：

同一句话放在不同运行时位置，意义完全不同
放在主系统 Prompt、Tool Prompt、compact Prompt、mode addendum 中，约束强度和作用对象都不一样

Claude Code 最值得借鉴的地方，不是这些句子本身，而是：

这句话为什么出现在这里
它约束的是主代理、子代理、工具调用，还是内部后台任务
它与其他 Prompt 规则是什么关系

真正该学的是“位置 + 作用对象 + 生效时机”，而不是只抄 wording。

22.2 误区二：把 Prompt 当成说明书，而不是协议

初学者很容易觉得 Tool Prompt 只是“工具帮助文档”，系统 Prompt 只是“产品说明书”。

但 Claude Code 的真实做法是：

用 Prompt 规定哪些行为允许发生
用 Prompt 规定哪些行为必须先确认
用 Prompt 规定工具选择优先级
用 Prompt 规定长会话如何恢复
用 Prompt 规定多代理如何通信

也就是说，这不是“告诉模型一些背景信息”，而是在给模型发一份可执行协议。

可借鉴点：

如果你自己做 Agent，不要只写“工具简介”
要写“边界、优先级、失败场景、确认条件、可见性规则”

22.3 误区三：只盯主系统 Prompt，忽略内部任务 Prompt

这是最常见的误判之一。很多人看完主系统 Prompt，就以为自己已经理解了整个系统。

但 Claude Code 最强的一部分恰恰在这里：

compact Prompt
memory update Prompt
extract memories Prompt
magic docs Prompt

这些 Prompt 才真正决定：

长会话会不会断档
历史信息能不能压缩后继续使用
记忆是不是能稳定演化
文档型任务是不是能独立运转

可借鉴点：

只读主 Prompt，你看到的是“当前轮怎么说”
读内部任务 Prompt，你看到的是“系统如何长期活着”

22.4 误区四：把长会话问题理解成上下文窗口问题

很多团队遇到长会话问题，会本能认为：

只要模型上下文更大就行
只要把历史原样塞回去就行

Claude Code 的做法说明这远远不够。真正困难的是：

哪些信息要原样保留
哪些信息适合摘要
哪些信息应该沉淀进 memory
哪些信息应该变成结构化文档

也就是说，长会话不是单纯的“窗口容量问题”，而是“信息治理问题”。

可借鉴点：

如果你只扩大上下文而不做 Prompt 分层，系统还是会逐渐退化

22.5 误区五：以为工具多，模型自然就会用得好

很多系统做了很多工具，却忽略了一个事实：

模型并不会天然理解每个工具该在什么时候用
更不会天然理解“哪个工具优先、哪个工具只是兜底”

Claude Code 明显在反复做一件事：

不断把工具路由规则写进主 Prompt 和 Tool Prompt
反复阻止模型把 Bash 当万能入口
反复强调专用工具优先

可借鉴点：

工具链质量 = 工具设计 + Prompt 路由设计
只有 schema，没有 Prompt 路由，最终效果通常会很差

22.6 误区六：把“自治”理解成“少约束”

很多人会以为自治模式就是：

少问用户
自己做决定
尽可能持续工作

但 Claude Code 的自治 Prompt 恰恰说明，自治越强，越需要清楚定义：

tick 是什么
空闲时怎么办
何时必须 sleep
用户在看和不在看时，行为应该怎么变

可借鉴点：

自治不是放权那么简单
自治是另一套更严格的行为协议

22.7 误区七：忽略“用户体验”也是 Prompt 设计目标

很多技术分析只关注 Prompt 是否能提高任务成功率，却不关注：

输出是否啰嗦
是否频繁确认
是否让用户理解成本很高
是否容易形成“看起来在做事，实际上没推进”的体验

Claude Code 很多 Prompt 明显在优化这些问题：

输出简洁
减少冗余表达
高价值更新
减少低信息量确认
风险动作才确认

可借鉴点：

Prompt 工程不仅是模型控制，也是产品体验设计

23. 学习方法：带着问题去读源码

如果还要继续深入这份项目，更有效的方式不是被动通读，而是带着问题去搜索和验证。下面给出一套适合精读时反复使用的问题清单。

23.1 读主系统 Prompt 时，问自己这 5 个问题

这段 Prompt 约束的是“身份”“流程”“风险”还是“输出”
它是稳定规则，还是会随会话变化的动态规则
它有没有和别的 section 形成前后呼应
它是在鼓励某种行为，还是在阻止某种失败模式
它为什么必须放在主系统 Prompt，而不是某个 Tool Prompt 里

23.2 读 Tool Prompt 时，问自己这 5 个问题

这个工具的最佳使用场景是什么
Prompt 有没有告诉模型“什么情况下不应使用这个工具”
Prompt 有没有把危险用法写出来
Prompt 是不是在替产品做权限和审计友好设计
如果去掉这段 Prompt，模型最容易怎么误用这个工具

23.3 读内部任务 Prompt 时，问自己这 5 个问题

这个 Prompt 服务的是哪种后台任务
为什么它不能复用主系统 Prompt
它要求的输出格式，是否明显强于普通对话
它是在做压缩、抽取、整合，还是恢复
它最后产出的内容，会怎么回流到下一轮系统里

23.4 读模式化 Prompt 时，问自己这 5 个问题

这类 Prompt 为什么不能直接写进主 Prompt
它在给哪种特殊场景加规则
它和通用规则之间有没有冲突
它是不是在定义新的通信方式、可见性约束或节奏协议
如果没有这段 addendum，系统最可能出现什么错觉

23.5 最后一个总问题

读完一段 Prompt 后，最值得问自己的不是：

这句话写得好不好？

而是：

如果删掉这段 Prompt，系统最可能坏在哪里？

持续用这个问题去读 Claude Code 的 Prompt，会更容易看见它背后的工程目的，而不只是表面的文字。

24. 方法论一：Claude Code 中反复出现的 Prompt 设计模式

如果把前面的所有分析再往上抽一层，会发现 Claude Code 并不是“写了很多 Prompt”，而是在反复使用一组稳定的 Prompt 设计模式。真正值得学习的，就是这些模式。

24.1 模式一：边界前置模式

这个模式的典型写法是：

先写禁止事项
先写使用边界
先写高风险限制
再写能力与目标

最典型的例子包括：

compact Prompt 一开头就写 CRITICAL: Respond with TEXT ONLY. Do NOT call any tools.
Bash Prompt 反复强调不要拿 Shell 去替代专用工具
风险动作 section 先定义哪些动作要确认，再谈可以如何执行

为什么要这样设计：

因为模型最容易先按“我能做什么”展开
如果不先收紧边界，后面的目标导向很容易把模型带到错误路径上

可借鉴点：

在高风险、强结构、强流程任务里，先写“不能怎么做”，往往比先写“要怎么做”更重要

24.2 模式二：专用工具优先模式

Claude Code 几乎在多个层次都在重复同一件事：

文件读写搜改尽量走专用工具
Bash 是兜底能力，不是默认入口
工具之间的职责要明确分离

这个模式同时出现在：

主系统 Prompt
BashTool Prompt
FileRead / FileEdit / FileWrite / Glob / Grep 各自的说明中

为什么要反复强调：

因为模型天然更熟悉通用 Shell
如果不持续提醒，模型会本能地走“一个 Bash 命令解决一切”的旧习惯

可借鉴点：

如果你希望系统具备高可审计性、高结构化结果和更好的权限控制，就必须让 Prompt 主动建立工具优先级

24.3 模式三：失败场景显式化模式

Claude Code 的一个成熟之处在于，它不只写理想路径，还写失败路径与异常路径。

常见写法包括：

如果用户拒绝工具怎么办
如果当前无事可做怎么办
如果工具结果会被清理怎么办
如果团队成员看不到普通文本怎么办
如果计划还没显示给用户，就不要问“计划如何”

为什么这很重要：

很多真实问题并不出现在主流程，而是出现在例外路径
生产环境里的 Agent，必须知道“不顺利的时候怎么继续”

可借鉴点：

Prompt 工程里，失败路径不是附属品
谁把失败路径写清楚，谁的系统就更稳

24.4 模式四：模式增量叠加模式

Claude Code 没有试图把所有规则塞进一个庞大主 Prompt，而是采用：

主骨架 Prompt
动态 section
mode addendum
子代理补强 Prompt

这种方式的核心思想是：

先维持稳定共性
再对特殊场景做最小增量增强

最典型的例子有：

proactive 模式加自治 section
teammate 模式加通信 addendum
chrome 模式加浏览器技能提示
子代理调用链补环境细节

可借鉴点：

系统一旦支持多模式，Prompt 也应该是模块化可叠加的
不要把“所有场景的一切规则”都写进单一主提示里

24.5 模式五：缓存友好模式

这是 Claude Code 很有工程味的一点。

它不是单纯追求 Prompt 内容完整，而是在设计时就考虑：

哪些内容稳定
哪些内容经常变化
哪些变化会击穿 cache
如何通过 section registry 把波动范围局部化

所以你会看到：

systemPromptSection() 用于稳定 section
DANGEROUS_uncachedSystemPromptSection() 用于易变 section
boundary 用于切开稳定前缀与动态尾部

可借鉴点：

当 Prompt 进入生产系统后，成本控制和缓存命中率就是一等问题
Prompt 写法不只是语义问题，也是系统性能问题

24.6 模式六：长会话恢复模式

Claude Code 对长会话的处理不是“把对话全塞回上下文”，而是做了多层次恢复设计：

transcript 保留事实轨迹
compact summary 负责高保真摘要
session memory 保留稳定记忆
extract memories 负责提炼长期价值信息
magic docs 负责文档化沉淀

为什么这是一个设计模式：

因为这里已经不是单条 Prompt 的事
而是一组 Prompt 共同承担“会话如何继续活下去”

可借鉴点：

做长会话 Agent 时，Prompt 必须和 memory / summary / docs 一起设计
单靠主系统 Prompt 是撑不起长会话质量的

24.7 模式七：可见性与通信显式化模式

在单代理系统里，这个问题不明显；但一旦进入多代理协作，这会变成刚需。

Claude Code 在 teammate Prompt 里显式规定：

文本回复不等于团队可见消息
发给具体成员和全员广播不是一回事
团队内沟通必须通过专用消息通道

为什么这是重要模式：

多代理系统特别容易出现“我以为别人看见了”的错觉
一旦通信可见性不清楚，整个协作链会快速失真

可借鉴点：

只要系统里有多个接收者、多个通道、多个角色，就要把可见性规则写进 Prompt

24.8 模式八：输出即产品体验模式

Claude Code 在这一点上的约束非常明确：

直接进入重点
高价值更新
减少冗余表达
只在必要时确认
不写低信息量状态消息

这说明它把 Prompt 当成产品体验控制器，而不是只当模型控制器。

可借鉴点：

Prompt 设计不能只关注“能不能完成任务”
还要关注“用户感受到的清晰度、可信度与可用性”

24.9 模式九：子代理闭环交付模式

子代理 Prompt 的核心不是人格，而是闭环：

接收任务
完成任务
不过度发挥
输出简洁结果

这是一种非常适合多代理系统的模式，因为它避免子代理：

无限扩展范围
做到一半就停
把大量无关过程甩回主代理

可借鉴点：

只要系统里有委派链路，就要专门设计“交付闭环型 Prompt”

24.10 模式十：把系统能力翻译给模型的模式

Claude Code 的很多 Prompt，表面上像规则，实际上是在做一件更底层的事：

向模型解释当前系统有哪些能力
哪些能力是短期的、动态的、模式相关的
哪些能力要通过专用工具或技能加载后才能使用

这就是为什么它会写：

哪些工具可用
哪些模式已启用
谁能看到消息
什么时候结果会被清理
为什么 scratchpad 要优先于 /tmp

可借鉴点：

Prompt 的重要作用之一，是把“系统语义层”翻译成模型能理解的操作语义

25. 方法论二：Claude Code Prompt 与常见 AI 助手 Prompt 的差异

为了更容易理解 Claude Code 的价值，可以把它和常见的通用 AI 助手 Prompt 做一个对比。

25.1 常见 AI 助手 Prompt 更像“行为说明”

普通 AI 助手的 Prompt 往往更接近下面这类结构：

你是谁
你要礼貌
你要准确
尽量帮助用户
不要输出危险内容

这类 Prompt 当然有价值，但它更偏向：

角色约束
安全约束
基础回答风格约束

它通常不需要处理：

多工具路由
长会话恢复
模式切换
多代理协作
本地与远程副作用

25.2 Claude Code Prompt 更像“运行时控制层”

Claude Code 的 Prompt 不只是让模型“会回答”，而是让模型在一个复杂软件工程运行时里“会行动”。

它要处理的维度包括：

工具该怎么选
哪些动作要先确认
用户拒绝工具后怎么办
何时该 sleep
会话压缩后如何恢复
子代理如何交付
团队成员如何通信

所以两者最大的差别不是长度，而是职责边界。

25.3 差异一：普通助手以对话为中心，Claude Code 以任务执行为中心

普通助手重点关注：

怎么把话说清楚
怎么回答问题
怎么保持礼貌与安全

Claude Code 重点关注：

怎么推进任务
怎么正确调用工具
怎么控制副作用
怎么维护会话状态

这意味着：

普通助手的 Prompt 更像对话规范
Claude Code 的 Prompt 更像执行协议

25.4 差异二：普通助手主要约束“输出”，Claude Code 同时约束“过程”

在普通助手里，很多 Prompt 关注的是：

回答格式
语气
安全表述

而在 Claude Code 里，Prompt 明确约束：

改代码前先读
不要无授权执行高风险动作
该用专用工具时不要偷懒用 Bash
有待办时如何维护任务状态
无事可做时不要空转，要 sleep

也就是说，Claude Code 不只管“最后怎么说”，还管“中间怎么做”。

25.5 差异三：普通助手通常是一套 Prompt，Claude Code 是分层 Prompt 系统

常见助手通常是一套主系统 Prompt，再叠加少量开发者约束。

Claude Code 则明显更复杂：

主系统 Prompt
动态 section
Tool Prompt
mode addendum
internal task Prompt
subagent Prompt

这意味着 Claude Code 真正构建的是 Prompt 架构，而不是单条 Prompt。

25.6 差异四：普通助手少有缓存语义，Claude Code 直接为 cache 设计 Prompt

大多数普通助手 Prompt 不会明确考虑：

哪些片段稳定
哪些片段动态
如何减少 cache fragmentation

Claude Code 则在 Prompt 装配层直接考虑这些问题。

这说明：

当系统进入高频调用、多轮执行、长时运行场景后，Prompt 不能再只按“语义完整”来写
还必须按“运行成本最优”来写

25.7 差异五：普通助手很少有“恢复现场”Prompt

普通聊天助手通常不需要专门的 compact Prompt、memory update Prompt、Magic Docs Prompt。

Claude Code 却把这些做成核心能力，因为它要解决：

会话很长怎么办
中途打断后如何恢复
哪些信息该摘要
哪些信息该沉淀成记忆
哪些信息该转成文档

这说明它面对的是工程连续性问题，而不只是单轮回答问题。

25.8 差异六：普通助手很少需要定义“谁能看到什么”

在一般聊天产品里，模型默认只和当前用户交互。

Claude Code 则不同，它可能面向：

用户
主代理
子代理
团队成员
特殊模式下的外部工具系统

所以它必须明确：

文本回复给谁看
SendMessage 发给谁
广播和单播有什么区别
哪些信息只在某个模式中有效

这也是它比普通助手 Prompt 更像分布式系统协议的原因之一。

25.9 差异七：普通助手的“自治”通常较弱，Claude Code 的自治是完整协议

很多助手即使号称自动化，也只是：

少打断用户
自动多做几步

Claude Code 的自治则已经明确到：

tick 语义
sleep 节奏
首次唤醒行为
空闲处理
用户聚焦与离开时的不同策略

这已经不是“更主动一点”，而是接近一套 agent runtime protocol。

25.10 差异八：普通助手的 Prompt 更像人设，Claude Code 的 Prompt 更像工程系统

把两者最本质的区别压缩成一句话就是：

普通 AI 助手 Prompt 更多是在塑造“这个助手怎么说话”
Claude Code Prompt 更多是在规定“这个代理如何在工程系统里可靠地做事”

这也是为什么研究 Claude Code Prompt 时，最值得借鉴的不是文风，而是架构。

26. 方法论三：最终总结——应该从这个项目里学什么

如果把整份文档再压缩成最后一层结论，那么 Claude Code Prompt 体系最值得借鉴的，不是某句措辞，而是下面 6 件事。

26.1 学分层

不要把所有规则都塞进一段总 Prompt。

应该拆成：

主系统层
动态 section 层
Tool Prompt 层
模式增强层
内部任务层
子代理层

26.2 学边界

高质量 Prompt 的核心，往往不是“赋能”，而是“定边界”。

你要能清楚写出：

什么能做
什么不能做
什么时候要确认
什么时候必须换工具
什么时候必须停下

26.3 学恢复

工程系统不是只跑一轮。

所以必须思考：

中断后怎么恢复
上下文长了怎么压缩
哪些信息该沉淀成记忆
哪些结果该转成文档

26.4 学模式化

当系统进入多模式、多角色、多环境后，Prompt 必须支持：

按模式增量叠加
按角色区别约束
按运行态动态调整

26.5 学工具路由

工具多不等于效果好。

真正重要的是：

工具职责是否清晰
模型是否知道优先级
Prompt 是否防止高频误用

26.6 学把 Prompt 当系统设计，而不是文案设计

Claude Code 给人的最大启发是：

Prompt 不是一段对模型说的话，而是把整个运行时设计翻译成模型可以遵守的协议。

当你以这个角度回头看这份项目，就会发现它真正强的地方不在“会写提示词”，而在“会设计一个让提示词长期稳定发挥作用的系统”。

27. 实践迁移一：如何借鉴 Claude Code 设计你自己的 Prompt 系统

前面的讨论主要是在理解 Claude Code 本身；从这一章开始，文档进入第四个层次：把这些经验迁移到自己的 Agent、CLI 助手或多代理系统中。

如果研究这个项目的目的，不只是“看懂 Anthropic 是怎么写 Prompt 的”，而是把经验迁移到自己的 Agent、CLI 助手、IDE 助手或多代理系统中，那么最关键的问题只有一个：

Claude Code 的哪些做法，可以直接借鉴？哪些应该按场景裁剪？

这一节把前面的分析收敛成一套可落地的实践思路。

27.1 第一步：先定义你的系统到底是哪一类 Agent

不要一开始就写 Prompt，而应先回答下面几个问题：

你的系统主要是聊天型、任务执行型，还是混合型
它会不会调用工具
它会不会修改文件、执行命令、联网
它是否需要长会话恢复
它是否存在子代理或多代理协作
它是否存在 plan mode、review mode、autonomous mode 这类模式切换

为什么这一步重要：

因为 Claude Code 的 Prompt 复杂，是由运行时复杂度决定的
如果你的系统只是轻量问答助手，完全没必要照搬它的全部分层
但如果你的系统要改代码、调工具、跑长任务、跨轮恢复，那它的很多模式就非常值得借鉴

可以压缩成一句话：先定义系统形态，再定义 Prompt 架构，最后才是具体 wording。

27.2 第二步：先画 Prompt 架构图，再写 Prompt

更合适的做法，是先在纸上或文档里画出你自己的 Prompt 分层，例如：

主系统 Prompt
动态环境 section
Tool Prompt
模式 addendum
内部任务 Prompt
子代理 Prompt

如果你不先做这张图，后面通常会遇到三个问题：

新需求一来，只能继续往主 Prompt 中堆叠内容
规则越来越多，却不知道该放哪一层
一旦需要特殊模式，就只能复制一份 Prompt 再做大量局部改写

Claude Code 最值得借鉴的一点，是把 Prompt 当架构对象来管理，而不是当单段文本来堆积。

27.3 第三步：主系统 Prompt 只放“稳定共性”

如果你照搬 Claude Code 的思想，那么主系统 Prompt 最适合承载的是：

身份与职责
输出与沟通基本规则
风险动作总原则
工具使用总原则
软件工程做事原则

不要把这些内容塞进主系统 Prompt：

某个特定模式才需要的细节
某个内部任务才需要的输出格式
某个工具独有的参数解释
某个临时实验功能的特殊约束

原因很简单：主系统 Prompt 越稳定，越利于维护和缓存；特定场景规则越局部化，越不容易互相污染。

27.4 第四步：把 Tool Prompt 当“行为接口契约”来写

如果你的系统有工具，最不应该做的事，就是只给模型一个 schema，就假设它会自然学会怎么用。

更好的做法是像 Claude Code 一样，让每个 Tool Prompt 明确回答 5 个问题：

这个工具是做什么的
最适合在什么场景下使用
哪些情况不该使用
参数应该怎么理解
有哪些风险、限制或误用成本

这样写 Tool Prompt，模型拿到的就不只是“函数说明书”，而是“工具路由规则 + 安全边界 + 参数语义”。

27.5 第五步：为长会话单独设计内部 Prompt

这一步最容易被忽略。

如果你的系统满足任意一条：

会话很长
会被打断后继续
需要跨轮积累用户偏好或项目状态
需要把阶段性结果沉淀成文档或记忆

那你就不应该只依赖主系统 Prompt，而应该单独设计：

summary / compact Prompt
memory update Prompt
extract Prompt
docs update Prompt

Claude Code 的核心经验可以压缩成两句：

单轮任务靠主 Prompt 和 Tool Prompt
长期连续性靠内部任务 Prompt

27.6 第六步：把模式切换做成“增量 Prompt”

如果你的系统会出现特殊模式，例如：

自治模式
计划模式
审查模式
浏览器模式
团队模式

更合适的做法不是复制一份主 Prompt，而是做成增量 addendum。

这样做有四个直接好处：主 Prompt 不会被污染，特殊模式边界更清晰，模式开关更容易解释，不同模式也更容易组合扩展。

这也是 Claude Code 中 proactive、teammate、chrome 等模式最值得借鉴的地方。

28. 实践迁移二：可直接参考的 Prompt 模板骨架

下面给出的不是 Claude Code 原文复刻，而是从它的设计思想里抽出来的一组“模板骨架”，可直接作为自己系统的起点。

28.1 主系统 Prompt 模板

适用场景：代码助手、CLI Agent、IDE 助手、有工具调用能力的任务执行代理。

模板骨架：

你是一个帮助用户完成【任务域】的执行型代理。

你的总体目标：
- 正确理解用户需求
- 使用系统提供的能力推进任务
- 不超出用户请求范围
- 在完成后给出真实、简洁、可复核的结果

基本原则：
- 在修改或执行前，先获取足够上下文
- 不要假设未验证的信息为真
- 不要把未完成的工作描述为已完成
- 不要擅自扩展需求或做额外“优化”

风险动作原则：
- 对于高破坏性、难回退、影响共享状态的动作，先确认
- 用户一次性授权不代表永久授权

工具原则：
- 优先使用专用工具，不要滥用通用 Shell
- 使用最适合当前任务的最小能力集

输出原则：
- 直接进入重点
- 优先汇报结果、阻塞点、关键发现
- 不写无意义过程流水账

使用建议：这类模板适合作为系统“稳定骨架”，不要在这里塞太多模式专属细节。

28.2 Tool Prompt 模板

适用场景：文件工具、Shell 工具、搜索工具、网络工具、协作工具。

模板骨架：

这个工具用于【核心用途】。

适用场景：
- 当你需要【场景 A】时使用
- 当你需要【场景 B】时使用

不要在这些场景下使用：
- 如果【反例 A】，请改用【其他工具/方式】
- 如果【反例 B】，请不要调用本工具

参数说明：
- 参数 1 表示什么
- 参数 2 的格式要求是什么
- 哪些字段必填，哪些可选

使用限制：
- 路径是否必须绝对
- 是否允许交互式输入
- 是否允许长时间运行
- 是否存在危险副作用

最佳实践：
- 优先如何调用
- 如何减少误用
- 如何提高结果可读性和可审计性

使用建议：如果你发现模型老是误用某个工具，优先改 Tool Prompt，不要只改主系统 Prompt。

28.3 compact / summary Prompt 模板

适用场景：长会话压缩、中断恢复、会话交接。

模板骨架：

严格要求：
- 只输出文本
- 不要调用任何工具

你的任务是生成一份可恢复当前工作上下文的详细总结。

总结必须覆盖：
- 用户目前要做什么
- 已分析或修改了哪些文件
- 关键函数、模块或代码模式
- 出现过什么错误，如何修复
- 当前还剩哪些未完成事项
- 最合理的下一步是什么

输出要求：
- 信息完整
- 不省略关键上下文
- 让后续代理能直接接手继续工作

使用建议：这类 Prompt 的目标不是“写得漂亮”，而是“让下一轮能恢复现场”。

28.4 memory update Prompt 模板

适用场景：用户偏好积累、项目稳定事实沉淀、跨轮长期记忆。

模板骨架：

你的任务是根据最新对话，更新系统的长期记忆。

请只保留具有持续价值的信息，例如：
- 用户长期偏好
- 项目结构性事实
- 长期适用的约束
- 反复出现的重要背景

不要写入这些内容：
- 一次性临时状态
- 已经过时的信息
- 低价值过程细节

更新原则：
- 保持记忆稳定、简洁、可长期复用
- 如果新信息与旧信息冲突，以最新可信信息为准

使用建议：transcript 记录“发生过什么”，memory 记录“以后还值得记住什么”。

28.5 模式 addendum 模板

适用场景：自治模式、审核模式、团队模式、浏览器模式。

模板骨架：

你当前处于【模式名】。

在这个模式下，额外遵守以下规则：
- 规则 1
- 规则 2
- 规则 3

特别注意：
- 哪些行为在此模式下必须发生
- 哪些行为在此模式下禁止发生
- 谁能看到你的输出
- 如何与其他角色或工具交互

使用建议：addendum 最好只写“这个模式新增的差异规则”，不要把主系统 Prompt 的通用规则整段复制过来。

28.6 子代理 Prompt 模板

适用场景：子任务委派、分工协作、fork agent。

模板骨架：

你是主代理委派出来的子代理。

你的任务是完成【子任务】。

要求：
- 把任务真正做完
- 不要超出委派范围
- 不要过度发挥
- 完成后给主代理返回简洁结论与关键发现

如果缺少上下文：
- 优先使用已有工具补足
- 不要把不必要的问题回抛给主代理

使用建议：子代理 Prompt 的核心不是人格，而是交付闭环。

29. 实践迁移三：把 Claude Code 方法迁移到自己项目时的裁剪建议

并不是所有项目都需要完整复制 Claude Code。更合适的做法，是按系统复杂度分层借鉴。

29.1 轻量项目：最少借鉴方案

如果你的系统只是单代理、工具较少、没有长会话，也没有模式切换，那最少只需要借鉴三样：一套主系统 Prompt、每个工具的 Tool Prompt，以及一套风险动作边界规则。

这已经显著优于“只有一段总 Prompt + 一堆 schema”的做法。

29.2 中等复杂度项目：推荐借鉴方案

如果你的系统具备多轮任务执行、文件修改或命令执行、明确的工具路由需求，并且可能需要中断恢复，那推荐引入主系统 Prompt、动态 section、Tool Prompt、compact / summary Prompt，以及至少一种模式 addendum。

这通常是大多数代码助手或自动化助手最合适的层级。

29.3 高复杂度项目：完整借鉴方案

如果你的系统具备长会话、多工具、多模式、子代理、协作通信以及文档或记忆沉淀能力，那就应该认真借鉴 Claude Code 的整套思路，包括分层 Prompt 架构、section registry、缓存友好设计、内部任务 Prompt、模式 addendum、子代理 Prompt，以及会话恢复与记忆更新机制。

这时 Prompt 已经不是功能点，而是系统基础设施。

29.4 裁剪原则

你可以用一句话来决定该借鉴到哪一层：

你的运行时复杂度有多高，你的 Prompt 架构就应该有多分层。

运行时简单时，不必过度工程化；运行时复杂时，如果仍想靠一段总 Prompt 顶住，后续大概率会失控。

30. 实践迁移四：如何使用这份文档

到这里，这份文档主要有三种用法。

30.1 用法一：把它当 Claude Code Prompt 地图

当你再回头看源码时，可以把这份文档当成地图来用：先看分层，再看总装配，再看关键 Tool Prompt、内部任务 Prompt，最后看特殊模式。

这样更不容易在一开始就陷入文件海洋。

30.2 用法二：把它当 Prompt 工程方法论提纲

如果你在做自己的 Agent，可以从这份文档中直接提炼 Prompt 如何分层、Tool Prompt 如何写、长会话 Prompt 如何设计、模式 addendum 如何做，以及哪些地方应该前置边界。

这比只抄几句提示词有效得多。

30.3 用法三：把它当系统设计检查表

当你设计自己的 Agent 时，可以反过来用这份文档问自己：

我有没有把工具路由写清楚
我有没有定义高风险动作边界
我有没有考虑长会话恢复
我有没有区分 transcript 和 memory
我有没有为特殊模式设计增量 Prompt
我有没有把输出体验当成系统目标

如果这些问题里有很多还答不上来，通常说明你的 Prompt 系统还停留在“能跑”，还没有进入“可长期稳定运行”的阶段。

30.4 最后一层结论

Claude Code 最值得借鉴的，不是某条 Prompt 很会写，而是它把 Prompt、工具、模式、记忆、恢复、协作、风险控制全部放进了同一个运行时设计里。

所以从这个项目里学 Prompt，最终真正该学会的是：如何把 Prompt 从文案升级成协议，从单段文本升级成分层系统，并且让它为真实运行时负责。

这也是本文最希望帮你建立的视角。

31. 实战落地：从 0 到 1 搭建最小可用 Prompt 系统

如果你不是在研究 Claude Code 本身，而是想尽快搭一个“够用、稳定、不会马上失控”的 Prompt 系统，更务实的做法不是一上来追求完整复制，而是先做一个最小可用版本。

下面给出一条更贴近实战的落地路径。

31.1 第一步：先保留 3 层

最小可用 Prompt 系统在初始阶段建议只保留三层：

主系统 Prompt
Tool Prompt
summary / compact Prompt

为什么是这三层：主系统 Prompt 负责稳定行为底座，Tool Prompt 负责工具路由和边界，summary / compact Prompt 负责长任务或中断后的基本恢复。

为什么暂时不急着做更多：如果初期就引入模式 addendum、memory update、子代理 Prompt 和复杂缓存策略，很容易先把架构做复杂，却还没验证基本任务是否稳定。对起步阶段的 Agent 项目来说，优先把“能稳定做事 + 不误用工具 + 中断后还能接上”做好，收益更高。

31.2 第二步：先定义一个最小工具集

最小系统不应该有太多工具。建议只保留最常用、最可控的一组，例如：

读文件
编辑文件
搜索文件
搜索内容
执行命令

如果你的场景不是代码，而是知识工作流，也可以映射成：

读取资源
搜索资源
更新资源
执行外部动作

为什么最小工具集很重要：工具越多，路由难度越高，Tool Prompt 维护成本也越高；早期系统最容易出现的问题，就是“工具很多，但模型总选错”。

可借鉴点：

Claude Code 值得借鉴的不是“工具多”，而是“工具与 Prompt 的匹配关系”
所以先做少量高频工具，远比一开始铺满工具更有效

31.3 第三步：先写一版能落地的主系统 Prompt

在最小系统里，主系统 Prompt 不需要很长，但必须覆盖四件事：

任务目标
行为边界
工具原则
汇报原则

一个足够实用的最小版本，通常至少要回答六个问题：你是谁、核心任务是什么、哪些动作不能擅自做、何时需要先获取更多上下文、何时优先用专用工具，以及完成后如何向用户汇报。

如果这些问题没有写清楚，系统问题会很快显现：

做事跑偏
擅自扩展需求
工具乱用
汇报失真

31.4 第四步：给每个工具写最小可用 Tool Prompt

一开始不必把 Tool Prompt 写得很长，但至少要覆盖：

用途
最佳使用场景
不该使用的场景
参数要求
主要风险

例如一个读文件工具，至少要说明：

路径格式要求
是否支持分页
是否限制读取大小
何时不应该一次性读完整大文件

一个命令执行工具，至少要说明：

什么时候应该优先改用专用工具
是否允许长时间运行
是否允许交互式命令
哪些命令属于高风险

需要强调的是：Tool Prompt 不是附赠说明，而是模型正确使用工具的必要前提。

31.5 第五步：尽早加上 compact / summary Prompt

很多团队在早期会觉得系统还小、会话还不长，暂时不需要 summary；但任务一旦开始跨轮、用户中断后再回来，或者系统需要继续上次工作，恢复机制的重要性就会立刻暴露出来。

更稳妥的策略是尽早加入一个简单但结构清晰的 compact / summary Prompt。

哪怕一开始不复杂，也至少应该要求输出当前任务目标、关键文件与模块、已完成工作、未完成工作，以及下一步建议。

31.6 第六步：先跑真实任务，再决定要不要分层升级

最小系统完成后，不要立刻继续抽象。

先拿它去跑真实任务，例如：

小型代码修复
文件编辑任务
多步搜索与修改任务
一次跨轮恢复任务

然后观察它最容易在哪些地方失效：

主系统 Prompt 不够清楚
Tool Prompt 约束不够
Bash 被滥用
输出太啰嗦
中断恢复信息不足

只有当这些问题在真实任务里反复出现时，再决定是否：

是否拆动态 section
是否增加模式 addendum
是否增加 memory prompt
是否加入子代理 Prompt

这是一条更稳妥的演化路径。

31.7 一个最小系统的推荐演化顺序

如果要把这条路线压缩成一条非常实用的升级路径，可以按下面顺序做：

主系统 Prompt
每个核心工具的 Tool Prompt
compact / summary Prompt
风险动作边界规则
输出效率规则
模式 addendum
memory update Prompt
子代理 Prompt

这条顺序的意义在于：先保住基本任务完成能力，再保住工具使用质量和长会话恢复，最后再补复杂的模式化与协作能力。

32. 风险与边界：Claude Code Prompt 体系的局限与代价

在完成迁移和模板讨论之后，还需要补上一层现实约束：这套体系为什么强、为什么复杂，又会在什么地方带来额外代价。

前文一直在强调这套设计的价值，但如果只讲优点、不讲代价，理解仍然不完整。

Claude Code 这类 Prompt 架构固然强，但成本同样明显。

32.1 局限一：系统复杂度显著上升

一旦 Prompt 开始分层，你就不再只是维护一段主提示，而是在维护：

主系统 Prompt
section registry
Tool Prompt
模式 addendum
内部任务 Prompt
子代理 Prompt

这会带来直接后果：学习门槛更高，新成员更难快速上手，小改动也可能影响多处行为。

所以这套方法非常适合复杂运行时，但未必适合超轻量项目。

32.2 局限二：调试难度会增加

在单段 Prompt 模式里，行为异常时，排查相对直接。

但在 Claude Code 这种体系里，一个问题可能来自：

主系统 Prompt 某一条规则
Tool Prompt 的边界设定
mode addendum 的额外约束
内部任务 Prompt 的格式要求
Prompt 覆盖优先级问题

直接结果是：

行为错误更难定位
改一处规则，可能影响另一层表现

可借鉴点：

分层 Prompt 架构必须配套更好的验证与回归检查，否则维护成本会上升得很快

32.3 局限三：Prompt 越强，越需要持续治理

很多人会误以为，只要把 Prompt 写得更细，就能一劳永逸。

实际并不是这样，原因包括：模型行为会随着工具变化而变化，新模式会引入新冲突，产品交互变化会让原有 Prompt 不再合适，一些 Prompt 在旧场景里合理，在新场景里又可能显得过重。

所以这类系统不是“一次设计”，而是“持续治理”。

32.4 局限四：缓存友好与表达完整之间有张力

Claude Code 很强调缓存友好；这也意味着设计时经常需要在两者之间权衡：

想让 Prompt 更完整
但又不想让它频繁击穿缓存

这会带来一些工程折中：需要把内容拆成稳定前缀与动态尾部，额外维护 section registry，并控制动态信息注入位置。

可借鉴点：

生产级 Prompt 设计，经常不是“怎么写最全”，而是“怎么在成本和效果之间找到平衡”

32.5 局限五：过度借鉴会导致过度工程化

Claude Code 的体系能力很强，但并不意味着每个 Agent 都要复制它的复杂度。如果你的系统没有长会话、没有多模式、没有多代理，也没有复杂工具路由，那么强行照搬 section registry、大量 addendum、memory / docs / consolidation Prompt，往往收益有限，反而会增加维护负担。

这也是为什么前文一直强调要按运行时复杂度裁剪。

32.6 局限六：Prompt 仍然不是全部

再强的 Prompt，也不能替代：

正确的工具设计
清晰的权限系统
稳定的上下文管理
可靠的产品交互
合适的评估体系

Claude Code 的表现好，不是只靠 Prompt，而是靠 Prompt、工具、运行时、会话管理一起工作。

可借鉴点：

不要神化 Prompt
Prompt 很重要，但它永远只是系统的一部分

33. 评估方法：如何评估一套 Prompt 系统是否真的有效

很多团队优化 Prompt 时，最常见的问题不是不会写，而是不会评估。

如果没有评估标准，你很容易陷入几种错觉：觉得“好像更聪明了”、觉得“回复更长了”、觉得“看起来更专业了”。

但这些都不等于系统真的更好。

33.1 先区分三类评估目标

一套 Prompt 系统，至少应该从三类目标来评估：任务完成质量、运行过程质量、用户体验质量。

这三类缺一不可。

33.2 任务完成质量指标

最基础的问题是：系统到底有没有把任务做对。

可以观察的指标包括任务完成率、首次尝试成功率、修改后真实通过验证的比例、错误定位准确性，以及最终结果是否超出或偏离用户要求。

如果这些指标没有变好，哪怕 Prompt 看起来更完整，也未必真正有价值。

33.3 运行过程质量指标

Claude Code 这类系统尤其要看过程指标，因为它不只是“回答问题”，而是在执行任务。

建议关注工具选择正确率、Bash 滥用率、高风险动作误执行率、无意义确认频率、无价值空转回复频率，以及任务状态同步是否准确。

这些指标直接反映 Prompt 是否真的改善了系统行为，而不只是改善了输出表面。

33.4 长会话与恢复质量指标

如果你的系统涉及多轮与恢复，就一定要单独评估这一层。

建议关注 compact 后能否继续接着做、summary 是否保留关键文件和待办、memory 是否记录长期有价值信息，以及恢复后是否经常丢失上下文重点。

这是很多系统最容易被忽略、但最能拉开差距的地方。

33.5 用户体验指标

Prompt 优化不能只看完成率，还要看用户是否愿意持续使用。

建议关注回复是否过长、是否频繁要求确认低价值问题、用户是否容易理解当前状态、是否经常出现“看起来在推进，实际上没推进”的体验，以及用户是否能清楚知道结果、阻塞点和下一步。

这类指标虽然更偏产品，但对 Agent 系统非常关键。

33.6 一个有效的评估方法：看失败是否更可控

除了看成功案例，更建议重点看失败案例。

一套好的 Prompt 系统，不只是成功率更高，还应该让失败更可控：更少高风险误操作、更少错误自信、更少乱用工具、更少无意义反复确认，也更容易在失败后恢复。

也就是说，评估 Prompt 时，不只问：

成功时是不是更强了？

还要问：

失败时是不是更可预期、更可恢复、更少副作用？

33.7 推荐的验证顺序

如果你要系统性评估一套 Prompt 系统，建议按下面顺序做：

先看真实任务完成率
再看工具路由与风险动作是否更稳
再看长会话恢复是否更可靠
最后看用户体验是否更顺滑

为什么这样排：

因为任务做不对，后面一切体验优化都没有意义
但只看完成率，又会遗漏高风险误操作和糟糕体验

33.8 一个最终判断标准

如果要用一句话判断一套 Prompt 系统是否真的有效，我更推荐这个标准：

它是否让代理在更多真实任务中，更稳定地做对事、少做错事、出错后也更容易恢复。

如果答案是肯定的，那这套 Prompt 系统就不是“写得好看”，而是真的有工程价值。

https://edu.csdn.net/learn/39067/627173?utm_source=2019755004

汇聚全球AI编程工具，助力开发者即刻编程。

更多推荐

Codex又又又更新了！这次似乎不需要Xcode了？Codex更新、Codex遥控器、Codex手机版、iOS Builder、Xcode替代方案、AI编程工具、Codex客户端下载、Mac远程控制、

AI编程社区

告别拖拽做工作流：两个Skill让Dify应用全流程自动化

AI编程社区

68%的Agent因“提前放弃“而失败——长时域任务的真正考验

AI编程社区

所有评论(0)

查看更多评论

Tale_G

@kguogao

已为社区贡献1条内容

Claude Code Prompt解剖：五层运行时控制协议

Tale_G

1. 文档目的

2. 基础认知：Prompt 体系总览

2.1 第一层：主系统 Prompt

2.2 第二层：动态 System Section

2.3 第三层：Tool Prompt

2.4 第四层：任务型 Prompt

2.5 第五层：模式化/协作型 Prompt

2.6 功能架构图

3. 运行时装配：Prompt 组装链路

3.1 主入口：getSystemPrompt()

3.2 动态 section 注册：systemPromptSection()

3.3 生效优先级：buildEffectiveSystemPrompt()

3.4 子代理补强：enhanceSystemPromptWithEnvDetails()

4. 核心骨架：主系统 Prompt 深度拆解

4.1 身份与总目标：Intro Section

4.2 系统规则：System Section

4.3 做事原则：Doing Tasks Section

4.4 风险控制：Actions Section

4.5 工具优先级：Using Your Tools Section

4.6 Session-Specific Guidance

4.7 输出风格与沟通效率

5. 动态机制：Prompt 片段与缓存设计

5.1 为什么要做边界

5.2 环境信息 Prompt

5.3 Scratchpad Prompt

5.4 Function Result Clearing Prompt

5.5 Proactive / Autonomous Prompt

5.6 Default Agent Prompt

6. 工具层总览：Tool Prompt 总体设计

6.1 Tool Prompt 的共性设计

6.2 Tool Prompt 的模块化分组

7. 工具层一：文件与代码操作类 Prompt

7.1 FileReadTool

7.2 FileEditTool

7.3 FileWriteTool

7.4 GlobTool

7.5 GrepTool

7.6 LSPTool 与 NotebookEditTool

8. 工具层二：Shell、系统与网络类 Prompt

8.1 BashTool

8.2 PowerShellTool

8.3 WebFetchTool

8.4 WebSearchTool

8.5 RemoteTriggerTool 与 ScheduleCronTool

9. 工具层三：计划、任务与协作类 Prompt

9.1 TodoWriteTool

9.2 AskUserQuestionTool

9.3 Task 系列工具

9.4 AgentTool

9.5 SkillTool 与 ToolSearchTool

9.6 SendMessage、TeamCreate、TeamDelete

10. 工具层四：模式切换类 Prompt

10.1 EnterPlanMode / ExitPlanMode

10.2 EnterWorktree / ExitWorktree

10.3 BriefTool、ConfigTool、SleepTool

11. 工具层五：MCP 与外部资源 Prompt

12. 特殊模式层：模式化 Prompt

12.1 Chrome Browser Automation Prompt

12.2 Team Teammate Addendum

12.3 Buddy Prompt

13. 内部任务层：任务型 Prompt

13.1 Compact Prompt

13.2 Session Memory Prompt

13.3 Extract Memories Prompt

13.4 AutoDream Consolidation Prompt

13.5 Magic Docs Prompt

14. 附录一：Prompt 文件总索引

14.1 核心系统 Prompt 文件

14.2 工具 Prompt 文件

14.3 内部服务 Prompt 文件

14.4 特殊模式与协作 Prompt 文件

15. 附录二：重点 Prompt 的原码摘录

15.1 默认子代理 Prompt

15.2 自治模式 Prompt

15.3 输出效率 Prompt

15.4 风险动作 Prompt

15.5 问用户工具 Prompt

15.6 TodoWrite 工作流 Prompt

3.1 主入口：`getSystemPrompt()`

3.2 动态 section 注册：`systemPromptSection()`

3.3 生效优先级：`buildEffectiveSystemPrompt()`

3.4 子代理补强：`enhanceSystemPromptWithEnvDetails()`