Claude Code Harness Chapter 5: 系统提示词架构：AI 行为的控制平面
2026-04-04
AI Claude Code System Prompt Prompt Engineering Harness Engineering
Claude Code Harness Chapter 5: 系统提示词架构：AI 行为的控制平面
引言：无形的控制者
在前几章中，我们探讨了 Claude Code 的"硬"架构——工具、执行、编排。但这些只是"能力"。真正决定 AI 如何使用这些能力的，是"软"架构：系统提示词（System Prompts）。
系统提示词是 AI 的"控制平面"（Control Plane），就像操作系统的内核代码决定了操作系统的行为一样，系统提示词决定了 AI 的：
- 🧭 角色定位：它是什么，应该做什么
- 🎯 行为准则：如何响应不同类型的请求
- 🛡️ 安全边界：什么不能做
- 🎨 沟通风格：如何与用户交互
- ⚙️ 决策策略：如何在多种选项中选择
本章将深入剖析 Claude Code 的系统提示词架构，揭示如何通过精心设计的提示词层级系统，创建一个既强大又安全、既智能又可控的 AI Agent。
系统提示词的核心作用
什么是系统提示词？
系统提示词是在对话开始时发送给模型的特殊指令，它定义了 AI 的基本行为模式：
flowchart LR
A[System Prompt
System Prompt] --> B[AI behavior pattern]
C[User Message
User Message] --> D[Specific task]
B --> E[AI response]
D --> E
style A fill:#f9f,stroke:#333,stroke-width:3px
style B fill:#f9f,stroke:#333,stroke-width:2px系统提示词 vs 用户消息：
| 维度 | 系统提示词 | 用户消息 |
|---|---|---|
| 作用 | 定义行为 | 提供任务 |
| 优先级 | 高（控制层面） | 低（具体请求） |
| 可见性 | 通常不可见 | 完全可见 |
| 内容 | 角色定位、规则、约束 | 具体问题、数据 |
| 变化频率 | 很少变化 | 每次对话都变化 |
系统提示词的 5 大功能
mindmap
root((System prompts))
Role definition
Who you are
What you can do
Your limitations
Behavior rules
How to respond
Decision strategy
Priority
Safety constraints
What not to do
Risk assessment
Permission checks
Context guidance
How to understand code
How to analyze problems
How to plan tasks
Interaction style
Tone and voice
Output format
Communication style提示词层级架构
Claude Code 使用复杂的多层级提示词系统，不同来源的提示词有不同的优先级：
完整的优先级层级
graph TD
A[Override System Prompt
CLAUDE.md] -->|Highest priority| Z[Final system prompt]
B[Coordinator Prompt
Multi-agent coordination] --> Z
C[Agent System Prompt
Custom agent] --> Z
D[Custom System Prompt
--system-prompt] --> Z
E[Default System Prompt
Standard Claude Code] --> Z
F[Append System Prompt
Always append] -->|Lowest priority| Z
style A fill:#f66,stroke:#333,stroke-width:4px
style Z fill:#f9f,stroke:#333,stroke-width:3px
style F fill:#6f6,stroke:#333,stroke-width:2px层级详解
| 层级 | 来源 | 优先级 | 用途 | 示例 |
|---|---|---|---|---|
| Override | 项目根目录的 CLAUDE.md | 🔴 最高 | 项目特定指令 | "这个项目使用 TypeScript 严格模式" |
| Coordinator | 多 Agent 模式 | 🟠 很高 | 协调多个 Agent | "你是主协调 Agent，负责分配任务" |
| Agent | 自定义 Agent 定义 | 🟡 高 | 特定 Agent 行为 | "你是代码审查 Agent，专注于安全性" |
| Custom | CLI 参数 | 🟢 中 | 用户自定义 | "使用简洁的输出风格" |
| Default | Claude Code 内置 | 🔵 低 | 标准行为 | Claude Code 的默认提示词 |
| Append | 系统追加 | ⚪ 最低 | 强制添加 | "永远保持代码可读性" |
提示词合并流程
flowchart TD
A[Start building] --> B{Has Override?}
B -->|Yes| C[Use CLAUDE.md]
B -->|No| D{Has Coordinator?}
D -->|Yes| E[Add coordinator prompt]
D -->|No| F{Has Agent prompt?}
F -->|Yes| G[Add agent prompt]
F -->|No| H{Has Custom prompt?}
H -->|Yes| I[Add custom prompt]
H -->|No| J[Use default prompt]
E --> K[Add default base]
G --> K
I --> K
J --> K
C --> K
K --> L[Add append prompt]
L --> M[Final system prompt]
style C fill:#f66
style L fill:#6f6
style M fill:#f9f默认系统提示词的架构
核心组件
Claude Code 的默认系统提示词包含多个关键部分：
graph TB
A[System prompts] --> B[Role definition]
A --> C[Core principles]
A --> D[Capability description]
A --> E[Behavior rules]
A --> F[Safety constraints]
A --> G[Output format]
A --> H[Tool usage guide]
B --> B1[You are Claude Code]
B --> B2[AI programming assistant]
C --> C1[Accuracy first]
C --> C2[Show don't tell]
C --> C3[Respect user time]
D --> D1[Code understanding]
D --> D2[Code writing]
D --> D3[Debugging capability]
E --> E1[Read before acting]
E --> E2[Use tools to verify]
E --> E3[State assumptions]
F --> F1[Permission checks]
F --> F2[Risk warnings]
F --> F3[Data protection]
G --> G1[Code block syntax]
G --> G2[File reference format]
G --> G3[Status update format]
H --> H1[When to use tools]
H --> H2[Tool selection strategy]
H --> H3[Concurrent execution rules]
style A fill:#f9f,stroke:#333,stroke-width:3px关键设计原则
1. 角色清晰性
✅ 好的角色定义：
"你是 Claude Code，Anthropic 开发的 AI 编程助手。
你帮助用户理解、编写和调试代码，通过专门的工具与文件系统交互。"
❌ 差的角色定义：
"你是一个有用的助手。"2. 原则优先
✅ 好的原则表达：
"遵循以下核心原则：
1. 准确优先：从不猜测，不确定时说明
2. 展示而非讲述：用代码示例而非抽象描述
3. 尊重时间：每句话都要有价值"
❌ 差的原则表达：
"尽量做好一点。"3. 行为具体化
✅ 好的行为规则：
"在编辑文件前：
1. 先读取文件内容
2. 使用 Edit 工具进行精确修改
3. 验证修改是否成功"
❌ 差的行为规则：
"要小心编辑文件。"CLAUDE.md：用户覆盖层
什么是 CLAUDE.md？
CLAUDE.md 是项目根目录下的特殊文件，它允许用户为项目定义自定义指令：
flowchart LR
A[Project directory] --> B[CLAUDE.md]
B --> C[Project-specific rules]
C --> D[Override default behavior]
D --> E[Code style]
D --> F[Tech stack]
D --> G[Workflow]
D --> H[Constraints]
style B fill:#f66,stroke:#333,stroke-width:2px
style D fill:#f66,stroke:#333,stroke-width:2pxCLAUDE.md 的典型内容
示例 1：技术栈规范
# 项目规范
## 技术栈
- 前端: React + TypeScript + Tailwind
- 后端: Node.js + Express
- 数据库: PostgreSQL
## 代码风格
- 使用 TypeScript 严格模式
- 函数组件优于类组件
- 优先使用 async/await 而非 Promise chains示例 2：工作流程
# 工作流程
## 开发流程
1. 任何新功能必须先写测试
2. 运行 `npm test` 确保测试通过
3. 运行 `npm run lint` 确保代码风格
4. 提交前必须通过 CI
## 约束
- 不要修改 `core/` 目录下的文件
- 所有新组件必须有 PropTypesCLAUDE.md 的优先级机制
graph TD
A[User request] --> B{CLAUDE.md exists?}
B -->|No| C[Use default behavior]
B -->|Yes| D[Read CLAUDE.md]
D --> E{Has relevant rules?}
E -->|Yes| F[Apply override rules]
E -->|No| C
F --> G[Merge with default]
G --> H[Priority on conflict]
H --> I[Execute]
style F fill:#f66
style H fill:#f66冲突解决示例：
| 场景 | 默认行为 | CLAUDE.md | 最终行为 |
|---|---|---|---|
| 代码风格 | 使用分号 | "不使用分号" | ❌ 不使用分号 |
| 测试框架 | Jest | "使用 Vitest" | ✅ 使用 Vitest |
| 文件组织 | 按功能分组 | "按类型分组" | ✅ 按类型分组 |
| 未指定 | 4 空格缩进 | （无规则） | 4 空格缩进 |
Agent 系统提示词
自定义 Agent
Claude Code 支持创建专门的 Agent，每个有自己的系统提示词：
graph TB
A[Agent definition] --> B[Agent System prompts]
B --> C[Specialized role]
C --> D[Specific capabilities]
C --> E[Specific constraints]
C --> F[Specific style]
D --> D1[Code review]
D --> D2[Test generation]
D --> D3[Documentation]
E --> E1[Read-only mode]
E --> E2[Don't modify core]
E --> E3[Enforce tests]
F --> F1[Formal style]
F --> F2[Detailed explanations]
F --> F3[List output]
style B fill:#e1f5ffAgent 类型示例
1. 代码审查 Agent
角色：代码审查专家
专注：安全性、性能、可维护性
行为：
- 识别潜在的安全漏洞
- 建议性能优化
- 检查代码复杂度
- 确保遵循最佳实践
约束：只提供建议，不直接修改代码2. 测试生成 Agent
角色：测试工程专家
专注：全面的测试覆盖
行为：
- 生成单元测试
- 生成集成测试
- 考虑边界情况
- 使用测试框架特性
约束：所有测试必须可运行3. 文档编写 Agent
角色：技术文档专家
专注：清晰、完整的文档
行为：
- 生成 API 文档
- 添加代码注释
- 编写使用示例
- 解释复杂逻辑
约束：使用 Markdown 格式，保持一致性提示词工程最佳实践
1. 结构化组织
flowchart TD
A[System prompts] --> B[层次 1: Role definition]
A --> C[层次 2: Core principles]
A --> D[层次 3: Capability description]
A --> E[层次 4: Behavior rules]
A --> F[层次 5: Constraints]
A --> G[层次 6: Output format]
B --> H[Short, clear]
C --> H
D --> I[Specific, detailed]
E --> I
F --> I
G --> J[Explicit, examples]
style H fill:#6f6
style I fill:#e1f5ff
style J fill:#e1f5ff2. 可测试性
好的系统提示词应该产生可预测的行为：
flowchart LR
A[Prompt] --> B[Define behavior]
B --> C[Write tests]
C --> D[Verify output]
D --> E{As expected?}
E -->|No| F[调整Prompt]
F --> B
E -->|Yes| G[Prompt有效]
style C fill:#e1f5ff
style G fill:#6f6测试场景示例：
| 测试场景 | 期望行为 | 实际验证 |
|---|---|---|
| 用户要求"删除所有文件" | 拒绝并警告 | ✅ 符合 |
| 用户要求"写一个函数" | 先询问需求 | ✅ 符合 |
| 用户要求"修复 bug" | 先运行测试 | ✅ 符合 |
| 用户要求"部署" | 请求确认 | ✅ 符合 |
3. 渐进增强
系统提示词应该逐步增强，而非一次性编写完美：
pie title PromptEvolution阶段
"MVP: Basic role" : 20
"v1: Add principles" : 20
"v2: 添加Behavior rules" : 25
"v3: Add tool guidelines" : 20
"v4: Refine and polish" : 15演进示例：
v0 (MVP):
"你是 Claude Code，帮助用户编写代码。"
v1:
"你是 Claude Code。
核心原则：准确、展示而非讲述、尊重时间。"
v2:
"你是 Claude Code。
核心原则：...
行为规则：
1. 先阅读再编辑
2. 使用工具验证
3. 明确说明假设"
v3:
"你是 Claude Code。
核心原则：...
行为规则：...
工具使用：
- Read: 读取文件内容
- Edit: 精确修改文件
- Bash: 运行命令和测试"
v4:
[基于实际使用反馈，优化每个部分]提示词的性能影响
Token 成本分析
系统提示词直接影响 token 使用：
pie title Token 使用分布
"System prompts" : 15
"Conversation history" : 50
"File content" : 25
"Tool results" : 10优化策略：
| 策略 | Token 减少 | 适用场景 |
|---|---|---|
| 精简表达 | 20-30% | 所有场景 |
| 延迟加载 | 40-60% | 大型提示词 |
| 条件包含 | 30-50% | 多模式提示词 |
| 模板化 | 25-40% | 重复性内容 |
提示词长度 vs 行为控制
flowchart TD
A[Prompt长度] --> B[短Prompt
~500 tokens]
A --> C[中等Prompt
~2000 tokens]
A --> D[长Prompt
~5000+ tokens]
B --> B1[Pros: Flexible, saves tokens]
B --> B2[Cons: Unstable behavior]
C --> C1[Pros: Balanced]
C --> C2[Cons: Possibly redundant]
D --> D1[Pros: Precise behavior]
D --> D2[Cons: Expensive tokens]
style B2 fill:#fc6
style C1 fill:#6f6
style D2 fill:#fc6最佳实践： 使用中等长度的提示词（1500-2500 tokens），在精确性和效率之间取得平衡。
多模型适配
不同模型需要不同提示
Claude Code 支持多个模型，每个需要调整提示词：
graph TD
A[Model selection] --> B[Opus 4.5]
A --> C[Sonnet 4.5]
A --> D[Haiku]
B --> E[Needs detailed instructions]
C --> F[Balanced instructions]
D --> G[Concise instructions]
E --> H[Include reasoning steps]
F --> I[Implicit reasoning]
G --> J[Skip reasoning]
style B fill:#f9f
style C fill:#e1f5ff
style D fill:#6f6模型特定优化：
| 方面 | Opus | Sonnet | Haiku |
|---|---|---|---|
| 指令详细度 | 高 | 中 | 低 |
| 推理要求 | 显式步骤 | 隐式 | 跳过 |
| 示例使用 | 多个示例 | 关键示例 | 极少示例 |
| 风格指令 | 正式、详细 | 对话式 | 简洁 |
| Token 预算 | 充分使用 | 平衡使用 | 严格节省 |
提示词的 A/B 测试
测试框架
flowchart LR
A[Prompt版本 A] --> B[Test scenarios]
C[Prompt版本 B] --> B
B --> D[Execute 100 次]
D --> E[Collect metrics]
E --> F[Success rate]
E --> G[User satisfaction]
E --> H[Token efficiency]
F --> I[Compare results]
G --> I
H --> I
I --> J{Which is better?}
J -->|A| K[Deploy A]
J -->|B| L[Deploy B]
J -->|相似| M[Merge benefits]
style K fill:#6f6
style L fill:#6f6
style M fill:#e1f5ff关键指标
| 指标 | 测量方法 | 目标 |
|---|---|---|
| 任务成功率 | 任务完成的比例 | > 95% |
| 用户满意度 | 用户反馈评分 | > 4.5/5 |
| Token 效率 | 任务平均 token 数 | 最小化 |
| 响应时间 | 首次响应时间 | < 2s |
| 安全合规 | 违规行为的比例 | 0% |
实战案例：优化提示词
场景：代码编辑行为
初始提示词：
"当编辑代码时，要小心谨慎。"问题分析：
| 问题 | 影响 |
|---|---|
| 太模糊 | 行为不一致 |
| 无具体指导 | 依赖模型猜测 |
| 缺少验证步骤 | 容易出错 |
优化后的提示词：
"代码编辑流程：
1. 使用 Read 工具读取完整文件
2. 识别需要修改的确切位置
3. 使用 Edit 工具进行精确替换
- old_string: 必须唯一匹配
- new_string: 完整的替换内容
4. 验证修改是否成功
5. 如果是代码更改，运行测试
注意：
- 永远不要猜测文件内容
- 确保修改的上下文完整性
- 保留原有代码风格"改进效果：
pie title Before improvement后对比
"编辑Success rate（Before improvement）" : 75
"编辑Success rate（After improvement）" : 98
"User satisfaction（Before improvement）" : 3.8
"User satisfaction（After improvement）" : 4.7结论：提示词即控制
系统提示词架构是 Claude Code 的"控制平面"，它实现了：
- 角色定义：明确 AI 是什么，应该做什么
- 行为引导：通过规则和原则指导决策
- 安全约束：设置不可逾越的边界
- 用户定制：通过 CLAUDE.md 覆盖默认行为
- 专门化：通过 Agent 实现特定用途
- 持续优化：通过 A/B 测试不断改进
核心原则：
| 原则 | 实现 | 价值 |
|---|---|---|
| 结构化 | 清晰的层次和组织 | 可维护性 |
| 可测试 | 明确的行为预期 | 可靠性 |
| 可定制 | 多层级覆盖系统 | 灵活性 |
| 效率 | 平衡长度和控制 | 成本效益 |
| 演进 | 基于反馈优化 | 持续改进 |
系统提示词展示了 Harness Engineering 的精髓：不是让 AI 自由发挥，而是通过精心设计的控制系统，让 AI 智能在正确的轨道上运行。
在下一章中，我们将探讨如何通过提示词引导 AI 的具体行为——从任务分解到错误处理，从沟通风格到决策策略。
关键要点
- 系统提示词是控制平面：定义 AI 的基本行为模式
- 多层级架构：Override > Coordinator > Agent > Custom > Default > Append
- CLAUDE.md 很强大：用户可以覆盖默认行为
- Agent 专门化：不同任务使用不同的系统提示词
- 提示词需要优化：通过 A/B 测试持续改进
- 模型特定调整：不同模型需要不同的提示策略
延伸阅读
- 第 6 章：通过提示词引导行为——具体技术
- 第 7 章：模型特定的调优和 A/B 测试
- 系统提示词源码：
src/utils/systemPrompt.ts - 提示词最佳实践：Anthropic Prompt Library