---
title: 【图解】Claude Code 源码解析 ｜Prompt 提示词模块
source_url: https://mp.weixin.qq.com/s/ogougiFVBLXAY2IihS94JA
publish_date: 2026-05-08
tags: [wechat, article, claude, agent]
review_value: 7
review_confidence: 7
review_recommendation: neutral
sha256: c029f207960e490b992a3644fc22b23c3c76aa4c13227c2c7a9d4e248ebd9ea1
---
# 【图解】Claude Code 源码解析 ｜Prompt 提示词模块
作者：FanOne
## 六大 Prompt 模块概览
Claude Code 的提示词体系分为六大模块：
| 模块 | 职责 |
|------|------|
| Core System Prompt | 明确角色、任务边界、输出风格、风险动作原则、工具总原则 |
| Tool Prompts | 每个工具的用途、输入约束、使用边界 |
| Skill Prompts | 专项知识包、触发条件、限定工具集、渐进式展开 |
| Agent Prompts | coordinator/worker/verifier/planner 四种角色的职责定义 |
| Context Management Prompts | 压缩、会话总结、记忆提取、恢复 |
| Memory Prompts | 存储内容、存储方式 |
## Core System Prompt：静态/动态分离
整个系统提示词由**静态规则**和**动态 dynamicSections** 组成：
- **静态规则**：做缓存（不变的部分反复使用）
- **动态规则**：每次会话更新
- 两者之间有明确的 **boundary** 划分
```javascript
// 静态规则示例
if (isEnvTruthy(process.env.CLAUDE_CODE_SIMPLE)) {
    return [`You are Claude Code, Anthropic's official CLI for Claude.\n\nCWD: ${getCwd()}\nDate: ${getSessionStartDate()}`]
}
// 动态 sections
const dynamicSections = [
    systemPromptSection('session_guidance', () => getSessionSpecificGuidanceSection(...)),
    systemPromptSection('memory', () => loadMemoryPrompt()),
    systemPromptSection('language', () => getLanguageSection(settings.language)),
    systemPromptSection('output_style', () => getOutputStyleSection(outputStyleConfig)),
    DANGEROUS_uncachedSystemPromptSection('mcp_instructions', () => getMcpInstructionsSection(mcpClients)),
    systemPromptSection('summarize_tool_results', () => SUMMARIZE_TOOL_RESULTS_SECTION)
]
```
### 优先级策略树：`buildEffectiveSystemPrompt`
在多模式、多角色、多来源 prompt 共存时，通过优先级策略树保证覆盖关系清晰：
| 优先级 | 类型 | 规则 |
|--------|------|------|
| **P0** | Override SystemPrompt | 硬覆盖，设置后替换其他所有 prompt |
| **P1** | Coordinator Prompt | 开启 coordinator mode 时，主线程变为调度者 |
| **P2** | Agent Prompt | 设置 mainThreadAgentDefinition 时；proactive mode 下追加而非替换 |
| **P3** | Custom System Prompt | 用户传入 `--system-prompt` |
| **P4** | Default System Prompt | 最终兜底的系统默认 |
## Tool Prompts：自然语言行为协议
CC 里 Skill 和 SubAgent 都是以 **Tool 形式**调用的（ToolSkill、ToolAgent）。
每个 Tool 自带的 prompt/description 定义：
- 这个工具是什么
- 什么时候该用 / 什么时候不该用
- 参数/调用约束是什么
**关键设计理念**：CC 把规则以**自然语言**放在 Prompt 里，而不是用代码对大模型输出做规则补丁。充分相信大模型的理解能力。
**BashTool 的 prompt 特殊之处**：已经复杂到像一份高风险工具专用操作 SOP。定义了 git 提交/PR 的详细流程、禁止事项、用 Skill 替代部分 git 流程。看起来像是 Skill 的前身。
## Skill Prompts：渐进式加载
如果所有工具定义都塞进上下文，token 浪费严重。**渐进式 Skill** 解决了这个问题。
**核心机制**：
- Skill 作为 Prompt 资产**先注册**
- SkillTool 在**运行时**把 Skill 展开成新的上下文消息
- 而不是像普通 Tool 那样直接执行外部动作
### Skill 的结构（以 `claude-api` skill 为例）
```markdown
name: Claude API
description: 这个技能用于帮助你使用 Claude API、Anthropic SDK 或 Agent SDK...
allowedTools: [Read, WebFetch, ...]
model: ...
hooks: ...
paths: ...
# Reading Guide（文档索引）
- 单轮文本分类/摘要/问答 → {lang}/claude-api/README.md
- 聊天 UI/流式响应 → README.md + streaming.md
- 长对话（可能超窗口） → README.md 中的 Compaction 部分
```
### Token 优化策略
**Reading Guide + 语言检测**：
- `detectLanguage` 判断项目语言（Python → pyproject.toml/requirements.txt，Go → go.mod，Java → pom.xml）
- 只发**当前项目最相关的那一套文档**，不发全部语言文档
- doc 标签区分文档来源，防止重复找相同文件：
```xml
<doc path="typescript/claude-api/README.md">...内容...</doc>
<doc path="shared/tool-use-concepts.md">...内容...</doc>
```
### Skill Prompt 标准格式
```markdown
***
name: Claude API
description: 使用场景，触发条件...
allowed-tools: [Read, WebFetch, ...]
***
# Claude API / Anthropic SDK 专项技能
## Reference Documentation
...Reading Guide...
## Included Documentation
<doc path="go/claude-api/README.md">...</doc>
<doc path="shared/tool-use-concepts.md">...</doc>
## When to Use WebFetch
...
## Common Pitfalls
避免：模型名错误、流式写法错误、tool use 方式错误、缓存误解等
```
## Agent Prompts：强角色边界 SOP
有两种 Agent Prompt：
### 第一种：给主线程看的（如何使用 AgentTool）
Prompt 结构：
1. **Shared core**：什么是 AgentTool、available agents 列表、subagent_type/fork 基本语义
2. **When NOT to use**：读文件别开 agent、搜类定义别开 agent
3. **Usage notes**：description 怎么写、前台/后台 agent 区别
4. **Writing the prompt**：fresh agent 写完整背景、fork 写 directive 不重复背景
5. **When to fork**：fork 继承上下文、不要偷看 output_file、不要猜结果
6. **Examples**：coordinator/fork 模式和普通模式示例
### 第二种：给具体 Agent 当 system prompt 用
抽象成可复用模块：
```markdown
你是一个 xxx 角色。
## 你的工作职责是
- 你负责什么
- 你的核心价值是什么
## 强制边界
- 你绝对不能做什么
- 哪些行为会失败或被拒绝
## 你可以获取的信息
- 你会拿到什么输入
- 哪些上下文可以依赖
## 执行过程
1. 先做什么
2. 再做什么
3. 什么时候停止
4. 什么时候升级/转交
## 错误处理
- 你最常见的错误行为是什么
- 出现时应该如何纠正
## 工具使用指南
- 应该优先怎么用工具
- 哪些工具不能碰
- 哪些信号要检查而不是假设
## 输出的结果是什么
- 必须怎么汇报结果
- 必须包含哪些字段
- 是否需要 verdict / critical files / summary
```
**模型友好型原则**：尽量用有逻辑的自然语言描述，不用 JSON/key-value 类的编码语言。
## Memory Prompts：四类分级存储
### Memory 系统定位
```markdown
你有一个持久化的、基于文件的 memory 系统，位于：
- private memory: <auto memory dir>
- team memory: <team memory dir>（如果启用 team 模式）
你应该逐步建立这套 memory 系统，让未来的会话能够知道：
- 用户是谁
- 用户喜欢如何协作
- 哪些行为应该避免
- 当前工作背后的上下文
如果用户明确要求你记住某件事，立即保存。
如果用户要求你忘记某件事，找到对应条目并删除。
```
### 四类 Memory
| 类型 | 记什么 | 写法 |
|------|--------|------|
| **user** | 用户角色、目标、知识水平、偏好 | 直接描述 |
| **feedback** | 用户对你工作的反馈 | 规则 → Why → How to apply |
| **project** | 项目事实、决策、动机、截止时间、事故背景 | 事实/决策 → Why → How to apply |
| **reference** | 外部系统入口（看板/dashboard/Slack/Linear） | 直接描述 |
**前提**：project 类 memory 不能从代码/git/CLAUDE.md 直接推导出来。
### 不进 Memory 的内容
- 代码结构、架构、文件路径
- git 历史和改动记录
- 修 bug 的具体 recipe
- 已写在 CLAUDE.md 的内容
- 当前会话临时任务状态（plan/task 另有用途）
### 保存 Memory 两步法
**Step 1**：每条 memory 写到单独文件，带 frontmatter：
```markdown
---
name: ...
description: ...
type: user|feedback|project|reference
---
# Memory 标题
正文...
```
**Step 2**：文件入口加到 `MEMORY.md`（仅作索引，不写正文）
### Memory 读取时机
- memory 看起来相关时去读
- 用户明确要求 recall/check/remember 时必须读
- 用户说 ignore memory 时，当 memory 为空
- memory 内容可能过时——提到文件/函数/flag 时先验证是否还存在
### 搜索历史上下文的顺序
1. 先搜 memory topic files
2. 不够再搜 transcript jsonl