claude_code 预设开始,其中人类观察并指导工作。为具有不同界面、身份或权限模型的代理编写自己的提示词。
本页涵盖:
- 系统提示词如何工作,包含一个决策表,用于在预设、带有
append的预设和自定义提示词之间进行选择 - 自定义代理行为,使用 CLAUDE.md 文件、输出样式、
append或自定义字符串 - 比较四种方法,按持久性、范围和它们保留的内容进行比较
- 组合方法,将自定义方法分层组合在一起
系统提示词的工作原理
系统提示词是初始指令集,它塑造了 Claude 在整个对话中的行为方式。Agent SDK 有三个起点:- 最小默认值:当你在 TypeScript 中不设置
systemPrompt或在 Python 中不设置system_prompt时,SDK 使用最小提示词,涵盖工具调用但省略了 Claude Code 的编码指南、响应风格和项目上下文。这与claude -p不同,后者默认使用完整的 Claude Code 提示词。如果你从 CLI 迁移并想要匹配的行为,请设置claude_code预设。 claude_code预设:Claude Code CLI 使用的完整系统提示词,包含工具使用说明、代码风格和格式化指南、响应语气和详细程度规则、安全和安全指令,以及关于工作目录和环境的上下文。在 TypeScript 中设置systemPrompt: { type: "preset", preset: "claude_code" },或在 Python 中设置system_prompt={"type": "preset", "preset": "claude_code"},可选择使用append在末尾添加你自己的指令。- 自定义字符串:你自己编写的提示词。SDK 仅发送你提供的内容。
决定起点
决定因素是你的代理与 Claude Code 的相似程度:一个在存储库中运行的编码代理,有人类观看流式输出并指导工作。你的产品离这个越远,你就越想编写自己的提示词。
“不同于 Claude Code” 通常意味着以下之一:
- 不同的表面:输出不是由触发它的人在终端中读取的。聊天 UI、结构化输出消费者和非编码自动化各自需要一个与其输出呈现和审查方式相匹配的提示词。无人值守的编码自动化,如修复 lint 错误或审查差异的 CI 作业,仍然适合预设,因为工作本身就是预设为之编写的。
- 不同的身份:代理不应该将自己呈现为 Claude Code。支持机器人、数据分析助手或任何特定领域的代理需要自己的名称、范围和角色。
- 不同的权限模型:代理自主运行,无需人类批准每一步,或在一组狭窄的资源上运行。Claude Code 的提示词假设人类在循环中,可以访问完整的工具集。
- 非编码任务:Claude Code 提示词的大部分是编码指导。对于研究、内容或运营代理,该指导与你实际需要的指令竞争。
自定义 agent 行为
输出样式、append 和自定义提示词字符串各自直接改变系统提示词。CLAUDE.md 采用不同的方式:SDK 读取它并将其内容作为项目上下文注入到对话中,而不是注入到系统提示词中,因此它与你选择的任何系统提示词一起塑造行为。Skills、hooks 和 permissions 也在系统提示词之外塑造行为,并在各自的页面上介绍。
CLAUDE.md 文件用于项目级指令
CLAUDE.md 文件为 Claude 提供持久的项目上下文和指令。SDK 将其内容注入到对话中,而不是注入到系统提示词中,因此它们可以与任何系统提示词配置一起工作。关于在 CLAUDE.md 中放什么、在哪里放置它以及如何编写有效的指令,请参阅 Claude 如何记住你的项目。本节涵盖 SDK 特定的内容:CLAUDE.md 如何加载。 当匹配的设置源被启用时,SDK 读取 CLAUDE.md:'project' 从工作目录加载 CLAUDE.md 或 .claude/CLAUDE.md,'user' 加载 ~/.claude/CLAUDE.md。默认 query() 选项启用两个源,因此 CLAUDE.md 会自动加载。如果你在 TypeScript 中显式设置 settingSources 或在 Python 中设置 setting_sources,请包含你需要的源。CLAUDE.md 加载由设置源控制,而不是由 claude_code 预设控制。
使用 SDK 加载 CLAUDE.md
要加载 CLAUDE.md,请设置settingSources 以包含你的 CLAUDE.md 所在的级别。下面的示例加载项目级 CLAUDE.md 以及 claude_code 预设,因此 Claude 既有完整的编码 agent 提示词,也有你的项目约定:
settingSources 数组,则不会加载。
输出样式用于持久配置
输出样式是保存的配置,可以修改 Claude 的系统提示词。它们存储为 markdown 文件,可以在会话和项目中重复使用。创建输出样式
输出样式是一个 markdown 文件,其 frontmatter 中有元数据,后面是提示词内容。将其保存到~/.claude/output-styles/ 以获得在每个项目中可用的用户级样式,或保存到你的存储库中的 .claude/output-styles/ 以获得可以提交和与你的团队共享的项目级样式。
默认情况下,自定义输出样式会用你自己的指令替换 claude_code 预设的软件工程指令。要保留它们并在其基础上分层你的指令,请在 frontmatter 中设置 keep-coding-instructions: true。当你的 agent 仍在进行软件工程工作时保留它们。当你完全替换角色时省略它们。
下面的示例定义了一个代码审查角色,它保留了编码指令,因为审查代码仍然受益于 Claude Code 的安全性和代码质量指导。将其保存为 ~/.claude/output-styles/code-reviewer.md 以在项目中可用:
~/.claude/output-styles/code-reviewer.md
激活输出样式
创建后,通过以下方式激活输出样式:-
CLI:运行
/config并选择输出样式 -
设置:在
.claude/settings.local.json中设置outputStyle -
TypeScript SDK:在传递给
query()的内联settings对象内设置outputStyle,或将settings指向设置它的设置文件。outputStyle不是顶级Options字段:
.claude/settings.local.json 的仅代码部署,请改用 append 或自定义提示词字符串。
SDK 用户注意: 当你在选项中包含 settingSources: ['user'] 或 settingSources: ['project'](TypeScript)/ setting_sources=["user"] 或 setting_sources=["project"](Python)时,输出样式会被加载。
追加到 claude_code 预设
你可以使用带有 append 属性的 Claude Code 预设来添加自定义指令,同时保留所有内置功能。
改进跨用户和机器的提示词缓存
默认情况下,两个使用相同claude_code 预设和 append 文本的会话,如果从不同的工作目录运行,仍然无法共享提示词缓存条目。这是因为预设在你的 append 文本之前在系统提示词中嵌入了每个会话的上下文:工作目录、它是否是 git 存储库、平台、活跃的 shell、操作系统版本和自动记忆路径。该上下文中的任何差异都会产生不同的系统提示词和缓存未命中。CLAUDE.md 内容不会影响系统提示词缓存,因为 SDK 将其注入到对话中,而不是系统提示词。
要使系统提示词在会话中相同,请在 TypeScript 中设置 excludeDynamicSections: true,或在 Python 中设置 "exclude_dynamic_sections": True。每个会话的上下文移动到第一条用户消息中,只在系统提示词中保留静态预设和你的 append 文本,以便相同的配置在用户和机器之间共享缓存条目。
excludeDynamicSections 需要 @anthropic-ai/claude-agent-sdk v0.2.98 或更高版本,或 Python 的 claude-agent-sdk v0.1.58 或更高版本。它仅适用于预设对象形式,当 systemPrompt 是字符串时无效。append 块与 excludeDynamicSections 配对,以便从不同目录运行的 agent 群可以重复使用相同的缓存系统提示词:
--exclude-dynamic-system-prompt-sections。
自定义系统提示词
你可以提供自定义字符串作为systemPrompt 以完全用你自己的指令替换默认值。
比较四种方法
这四种自定义方法在存储位置、共享方式以及从claude_code 预设保留的内容方面有所不同。
“带有追加”是指在 TypeScript 中使用
systemPrompt: { type: "preset", preset: "claude_code", append: "..." },或在 Python 中使用 system_prompt={"type": "preset", "preset": "claude_code", "append": "..."}。CLAUDE.md 不会改变系统提示本身:SDK 将其内容作为项目上下文注入到对话中。
用例和最佳实践
何时使用 CLAUDE.md
使用 CLAUDE.md 来存储应该应用于项目中每个会话的指令,无论该会话使用哪个系统提示词:编码标准、常见命令、架构上下文和团队约定。CLAUDE.md 被提交到你的存储库,因此它与它描述的代码保持同步。有关完整指导,请参阅 何时添加到 CLAUDE.md。 当启用project 设置源时,CLAUDE.md 文件会加载,这对默认的 query() 选项是这样的。如果你显式设置 settingSources(TypeScript)或 setting_sources(Python),请包含 'project' 以继续加载项目级 CLAUDE.md。
何时使用输出样式
输出样式用于你想在 CLI 和 SDK 中重复使用的角色,而无需更改应用程序代码。因为它们作为文件存在于.claude/output-styles 中,同一个角色可从 CLI 中的 /config 和加载匹配设置源的任何 SDK 会话中获得。
最适合:
- 跨会话的持久行为更改
- 团队共享配置
- 专门的助手,如代码审查者、数据科学家或 DevOps 助手
- 需要版本控制的复杂提示词修改
- 创建专用的 SQL 优化助手
- 构建安全聚焦的代码审查者
- 开发具有特定教学法的教学助手
何时使用带有追加的 systemPrompt
当 claude_code 预设已经适合你的产品,而你只需要添加额外指令时,使用 append。你保留预设的工具指导、安全规则和编码约定,而无需重新实现它们。
最适合:
- 添加特定的编码标准或偏好
- 自定义输出格式
- 添加特定领域的知识
- 修改响应详细程度
- 增强 Claude Code 的默认行为而不失去工具指令
何时使用自定义 systemPrompt
当你的代理的表面、身份或权限模型与 Claude Code 的不同时,使用自定义提示词,如 决定起点 中所述。你定义完整的指令集,包括你的代理需要的任何工具指导和安全规则。
最适合:
- 完全控制 Claude 的行为
- 专门的单会话任务
- 测试新的提示词策略
- 不需要默认工具的情况
- 构建具有独特行为的专门代理
组合方法
这些方法可以组合使用。持久化的输出样式或 CLAUDE.md 设置长期行为,而append 在不触及保存配置的情况下在顶部分层会话特定的指令。
将输出样式与会话特定的添加组合
下面的示例假设代码审查员输出样式已经处于活动状态。append 块在角色的基础上分层会话特定的焦点区域,因此单个审查会话可以优先考虑 OAuth 和令牌存储,而无需更改保存的输出样式:
另请参阅
- 输出样式:为 CLI 创建、管理和共享输出样式,包括文件格式和存储位置
- Claude 如何记住您的项目:CLAUDE.md 中应放入的内容、放置位置以及如何编写有效的项目说明
- TypeScript SDK 参考:完整的
Options类型,包括systemPrompt、settingSources和settings - Python SDK 参考:完整的
ClaudeAgentOptions类型,包括system_prompt和setting_sources - Settings:
settings.json参考,包括输出样式和其他配置的存储位置