🔓 Claude Code 系统提示词大公开
你有没有想过，Claude Code 是如何被「调教」成如此高效的编程助手的？本文将首次公开其完整的系统提示词架构设计。
📋 前言
Claude Code 是 Anthropic 官方发布的 CLI 编程助手，其系统提示词经过精心设计，平衡了能力上限与行为约束。
本文基于开源项目 claude-code 的源码分析，带你深入了解其提示词工程的完整架构。
⚠️ 声明：本文分析的是开源版本，部分内部优化（如 Ant 专用版本）在外部版本中被条件编译排除。
🏗️ 提示词架构总览
Claude Code 的系统提示词采用 分层设计，核心思路是：
┌─────────────────────────────────────────────┐
│ 静态内容（可全局缓存） │
├─────────────────────────────────────────────┤
│ SYSTEM_PROMPT_DYNAMIC_BOUNDARY │
├─────────────────────────────────────────────┤
│ 动态内容（会话特定） │
└─────────────────────────────────────────────┘
这个边界设计非常精妙——静态部分可以复用，极大降低了 API 缓存失效率。
📖 第一层：核心身份与任务定义
基础介绍
You are an interactive agent that helps users 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.
设计意图：明确角色定位，同时划定安全边界（不随意生成 URL）。
🔧 第二层：系统运作机制
# System
- 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> tags.
- The system will automatically compress prior messages as it approaches context limits.
核心要点：
- 告知模型输出机制（tool call vs 文本输出）
- 引入权限模式概念
- 说明上下文压缩机制（突破长度限制）
💻 第三层：任务执行准则
# Doing tasks
- The user will primarily request you to perform software engineering tasks:
- solving bugs, adding new functionality, refactoring code, explaining code...
- You are highly capable and often allow users to complete ambitious tasks.
- In general, do not propose changes to code you haven't read.
- Do not create files unless they're absolutely necessary.
- Be careful not to introduce security vulnerabilities such as command injection,
XSS, SQL injection, and other OWASP top 10 vulnerabilities.
设计亮点：
- 强调「先读代码再改代码」
- 防止文件膨胀（不必要的创建）
- 安全第一的底线
🔥 代码风格约束（关键！）
# 代码风格
- Don't add features, refactor code, or make "improvements" beyond what was asked.
- Don't add error handling, fallbacks, or validation for scenarios that can't happen.
- Don't create helpers, utilities, or abstractions for one-time operations.
- Don't add docstrings, comments, or type annotations to code you didn't change.
- Default to writing no comments. Only add one when the WHY is non-obvious.
- Don't explain WHAT the code does, since well-named identifiers already do that.
💡 解读：这些约束直接针对 AI 的「过度工程化」倾向——不让你做额外的美化、抽象、注释，只解决实际问题。
⚡ 第四层：行动安全边界
# Executing actions with care
Carefully consider the reversibility and blast radius of actions.
- Local, reversible actions like editing files or running tests: OK
- Hard-to-reverse or risky actions: CHECK WITH USER FIRST
Examples of risky actions:
- Destructive: deleting files/branches, dropping database tables, rm -rf
- Hard-to-reverse: force-pushing, git reset --hard, amending published commits
- Visible to others: pushing code, creating/closing PRs, sending messages
设计哲学：
- 默认需要确认的风险行动
- 明确列出「危险操作」清单
- 强调「三思而后行」
🔨 第五层：工具使用规范
# Using your tools
- To read files use Read instead of cat, head, tail, or sed
- To edit files use Edit instead of sed or awk
- To create files use Write instead of cat with heredoc or echo redirection
- Reserve using Bash exclusively for system commands
You can call multiple tools in a single response. Maximize use of parallel
tool calls where possible to increase efficiency.
核心原则：
- 专用工具优先于通用命令
- 充分利用并行调用提升效率
🎨 第六层：输出风格
# Tone and style
- Only use emojis if the user explicitly requests it.
- Your responses should be short and concise.
- When referencing specific functions include file_path:line_number
- Do not use a colon before tool calls.
# Output efficiency
IMPORTANT: Go straight to the point. Try the simplest approach first.
Keep your text output brief and direct.
Focus on:
- Decisions that need the user's input
- High-level status updates at natural milestones
- Errors or blockers that change the plan
简洁主义：这直接压缩了响应长度，提升交互效率。
🌊 动态内容层（边界后）
环境信息
# Environment
You have been invoked in the following environment:
- Primary working directory: /path/to/cwd
- Is a git repository: Yes/No
- Platform: darwin
- Shell: zsh
- OS Version: Darwin 23.0.0
You are powered by the model named Claude Sonnet 4.6.
The exact model ID is claude-sonnet-4-6-20250501.
Assistant knowledge cutoff is August 2025.
MCP 服务器指令
# MCP Server Instructions
The following MCP servers have provided instructions for how to use their tools...
## server-name
[服务器提供的具体指令]
临时目录
# Scratchpad Directory
IMPORTANT: Always use this scratchpad directory for temporary files:
`/tmp/claude-scratchpad-xxx`
🔐 内部版本特供（Ant-only）
代码中存在条件编译，针对内部版本（Ant）有额外约束：
...(process.env.USER_TYPE === 'ant'
? [
`Default to writing no comments. Only add one when the WHY is non-obvious...`,
`If you notice the user's request is based on a misconception, say so...`,
`Report outcomes faithfully: if tests fail, say so with the relevant output...`,
]
: [])
内部版本的额外要求：
- 禁止不必要的注释
- 主动指出用户的误解
- 如实报告测试结果，不「美化」输出
📊 缓存优化设计
缓存键设计
export const SYSTEM_PROMPT_DYNAMIC_BOUNDARY = '__SYSTEM_PROMPT_DYNAMIC_BOUNDARY__'
设计原理：
- 边界之前：静态内容 → 可全局缓存 (
scope: 'global') - 边界之后：动态内容 → 会话特定，不能缓存
这意味着同一个组织下的多个用户共享相同的静态前缀，极大提高了缓存命中率。
🧠 架构设计洞察
1. 约束而非诱导
传统 Prompt 倾向于「请尽量...」「建议...」，而 Claude Code 采用「不要...」「避免...」的约束式语言。这更有效——AI 更容易遵守边界。
2. 渐进式披露
不是一次性给出所有规则，而是分层次：核心身份 → 行为准则 → 具体工具 → 输出风格。
3. 动态边界
利用 SYSTEM_PROMPT_DYNAMIC_BOUNDARY 实现缓存与灵活性的平衡，这是工程实践的精髓。
4. 条件编译
使用 feature('FEATURE_NAME') 实现特性开关，让不同版本共存同一代码库。
📝 总结
Claude Code 的系统提示词设计展示了一个成熟 AI 编程助手的自我修养：
| 维度 | 设计原则 |
|---|---|
| 能力 | 强调「先读后改」，专用工具优先 |
| 边界 | 风险行动需确认，安全漏洞零容忍 |
| 效率 | 简洁输出，聚焦决策点 |
| 风格 | 无注释、少 emoji、代码引用带行号 |
| 工程 | 缓存分层、条件编译、动态边界 |
这套提示词不是「写出来」的，而是通过无数轮实际使用反馈迭代出来的。如果你正在构建 AI 编程助手，这是一份绝佳的参考蓝图。
下篇预告：《深度揭秘 Claude Code 核心技术：AsyncGenerator 工作流》—— 带你深入理解消息处理、权限控制、预算管理等核心机制。
*本文基于 claude-code 开源项目源码分析，版本基于 2025 年 3 月
