本页目录11
- 不设置 systemPrompt 时 SDK 使用极简默认提示词,仅支持工具调用,不含 Claude Code 的编码规范、响应风格与项目上下文,这与 claude -p 默认使用完整提示词不同
- claude_code 预设通过 systemPrompt: { type: "preset", preset: "claude_code" }(TypeScript)或 system_prompt={"type": "preset", "preset": "claude_code"}(Python)启用,可选配合 append 追加自定义指令
- CLAUDE.md 不会改写系统提示词,而是被 SDK 注入到对话中作为项目上下文,依赖 settingSources / setting_sources 中包含 project 或 user
- excludeDynamicSections(TypeScript,需 @anthropic-ai/claude-agent-sdk v0.2.98+)/ exclude_dynamic_sections(Python,需 claude-agent-sdk v0.1.58+)可将工作目录等动态上下文移出系统提示词,提升跨会话的 prompt 缓存命中率,但仅对 preset 对象形式生效
- 自定义字符串会完全替换默认提示词,需自行承担工具指导与安全说明的补充责任;Python 中过长的自定义提示词建议用 system_prompt={"type": "file", "path": "..."} 从文件加载,避免命令行参数长度限制报错
- Python SDK 目前没有编程方式选择 output style 的选项,只能通过 CLI /config 或 .claude/settings.local.json 设置
本文是对 Claude Agent SDK 官方文档「Modifying system prompts」页面的中文整理,完整与最新内容以原文为准:https://code.claude.com/docs/en/agent-sdk/modifying-system-prompts
系统提示词(system prompt)定义了 Claude 的行为、能力与响应风格。对于人类在旁观察并引导工作的 CLI 或 IDE 类编码工具,建议从 claude_code 预设开始;若你的 agent 有不同的使用场景、身份或权限模型,则应自行编写提示词。
系统提示词的三种起点
Agent SDK 提供三种系统提示词起点:
- 极简默认(Minimal default):当 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在末尾追加自定义指令。
- TypeScript:
- 自定义字符串:完全由你自己编写的提示词,SDK 只会发送你提供的内容。
如何选择起点
决定因素在于你的 agent 与 Claude Code 的相似程度——即是否是在代码仓库中操作、由人类观察流式输出并引导工作的编码 agent。产品与该场景差异越大,就越需要自己编写提示词。
| 你正在构建 | 使用 | 你会得到 |
|---|---|---|
| 人类在旁观察并引导的 CLI 或 IDE 类编码工具,且 Claude Code 的默认设置正合适 | claude_code 预设 | 完整的 Claude Code 提示词:工具指导、安全规则、适合终端的响应、对仓库约定的感知 |
| 同类工具,但需附加产品特定规则,如编码规范、输出格式或领域上下文 | claude_code 预设 + append | 上述全部内容,加上追加在预设之后的你的指令。不删除任何内容,因此是风险最低的定制方式 |
| 使用场景、身份或权限模型不同的 agent,或非编码类 agent | 自定义提示词字符串 | 只包含你所写的内容。你需要自行承担替换你的 agent 仍需要的工具指导与安全说明的责任 |
| 无 agent 人设的纯工具调用循环,所有行为由用户提示词提供 | 不设置 systemPrompt 选项 | 极简默认:仅支持工具调用,不包含其他内容 |
「与 Claude Code 不同」通常指以下情形之一:
- 使用场景不同:输出并非由触发者本人在终端中阅读。聊天 UI、结构化输出的消费方、非编码类自动化各自需要匹配其渲染与审阅方式的提示词。而无人值守的编码自动化(如修复 lint 错误或审查 diff 的 CI 任务)仍然适合使用预设,因为这类工作正是预设所针对的场景。
- 身份不同:agent 不应以 Claude Code 自称。客服机器人、数据分析助手或任何领域专用 agent 需要自己的名称、范围与人设。
- 权限模型不同:agent 在无人逐步审批的情况下自主运行,或仅操作一组有限的资源。Claude Code 的提示词假设有人类在环并拥有完整工具集的访问权限。
- 非编码任务:Claude Code 提示词大部分是编码指导。对于研究、内容或运营类 agent,这些指导会与你实际需要的指令相竞争。
下方的「四种方式对比」表格展示了每种定制方式保留了哪些内容。
定制 agent 行为
输出样式(output styles)、append 与自定义提示词字符串都直接修改系统提示词。CLAUDE.md 走的是不同路径:SDK 会读取它并将其内容作为项目上下文注入对话,而非注入系统提示词,因此它会与你选择的任何系统提示词配置共同作用。Skills、hooks、permissions 同样在系统提示词之外影响行为,各自有独立文档介绍。
CLAUDE.md:项目级指令文件
CLAUDE.md 文件为 Claude 提供持久的项目上下文与指令。SDK 会将其内容注入对话,而不改动系统提示词,因此可与任意系统提示词配置搭配使用。关于 CLAUDE.md 应写什么、放在哪里、如何写出有效指令,请参见 When to add to CLAUDE.md 及 How Claude remembers your project 全文。本节仅覆盖 SDK 特有的部分:CLAUDE.md 如何被加载。
SDK 会在匹配的 setting source 启用时读取 CLAUDE.md:'project' 从工作目录加载 CLAUDE.md 或 .claude/CLAUDE.md,'user' 加载 ~/.claude/CLAUDE.md。query() 的默认选项会启用这两个来源,因此 CLAUDE.md 会自动加载。如果你显式设置了 TypeScript 中的 settingSources 或 Python 中的 setting_sources,需要包含你所需的来源。CLAUDE.md 的加载由 setting sources 控制,与 claude_code 预设无关。
通过 SDK 加载 CLAUDE.md
将 settingSources 设置为包含你的 CLAUDE.md 所在层级即可加载。以下示例在使用 claude_code 预设的同时加载项目级 CLAUDE.md,使 Claude 同时拥有完整的编码 agent 提示词与你项目的约定:
import { query } from "@anthropic-ai/claude-agent-sdk";
const messages = [];
for await (const message of query({
prompt: "Add a new React component for user profiles",
options: {
systemPrompt: {
type: "preset",
preset: "claude_code" // Use Claude Code's system prompt
},
settingSources: ["project"] // Loads CLAUDE.md from project
}
})) {
messages.push(message);
}
// Now Claude has access to your project guidelines from CLAUDE.md
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions
messages = []
async def main():
async for message in query(
prompt="Add a new React component for user profiles",
options=ClaudeAgentOptions(
system_prompt={
"type": "preset",
"preset": "claude_code", # Use Claude Code's system prompt
},
setting_sources=["project"], # Loads CLAUDE.md from project
),
):
messages.append(message)
asyncio.run(main())
# Now Claude has access to your project guidelines from CLAUDE.md
运行以上任一示例时,SDK 会在 Claude 工作过程中流式返回消息:一条 system init 消息、assistant 消息、携带工具结果的 user 消息,以及一条包含会话结果的最终 result 消息。
CLAUDE.md 在项目内的所有会话间持久存在,可通过 git 与团队共享,并且无需修改代码即可自动被发现。如果传入空的 settingSources 数组,则不会加载它。
输出样式(Output styles):持久化配置
输出样式是修改 Claude 系统提示词的已保存配置,以 markdown 文件形式存储,可在多个会话与项目间复用。
创建输出样式
输出样式是带有 frontmatter 元数据的 markdown 文件,后接提示词内容。保存到 ~/.claude/output-styles/ 可在每个项目中使用(用户级样式);保存到仓库中的 .claude/output-styles/ 可提交并与团队共享(项目级样式)。
默认情况下,自定义输出样式会用你自己的内容替换 claude_code 预设中的软件工程指令。若要保留这些指令并在其之上叠加你的指令,需在 frontmatter 中设置 keep-coding-instructions: true。当你的 agent 仍在做软件工程工作时应保留;若要完全替换角色,则不保留。
以下示例定义了一个保留编码指令的代码审查人设(因为审查代码仍受益于 Claude Code 的安全与代码质量指导)。保存为 ~/.claude/output-styles/code-reviewer.md 即可跨项目使用:
---
name: Code Reviewer
description: Thorough code review assistant
keep-coding-instructions: true
---
You are an expert code reviewer.
For every code submission:
1. Check for bugs and security issues
2. Evaluate performance
3. Suggest improvements
4. Rate code quality (1-10)
启用输出样式
创建后,可通过以下方式启用:
-
CLI:运行
/config并选择一个输出样式 -
Settings:在
.claude/settings.local.json中设置outputStyle -
TypeScript SDK:在传给
query()的内联settings对象中设置outputStyle,或让settings指向一个设置了它的配置文件。outputStyle不是Options的顶层字段:const options = { settings: { outputStyle: "Explanatory" } };
Python SDK 目前没有以编程方式选择输出样式的选项。对于无法写入 .claude/settings.local.json 的纯代码部署场景,请改用 append 或自定义提示词字符串。
SDK 用户须知:只有当选项中包含 settingSources: ['user'] 或 settingSources: ['project'](TypeScript)/ setting_sources=["user"] 或 setting_sources=["project"](Python)时,输出样式才会被加载。
在 claude_code 预设基础上追加(append)
可以在使用 Claude Code 预设的同时通过 append 属性添加自定义指令,同时保留全部内置功能。
import { query } from "@anthropic-ai/claude-agent-sdk";
const messages = [];
for await (const message of query({
prompt: "Help me write a Python function to calculate fibonacci numbers",
options: {
systemPrompt: {
type: "preset",
preset: "claude_code",
append: "Always include detailed docstrings and type hints in Python code."
}
}
})) {
messages.push(message);
if (message.type === "assistant") {
console.log(message.message.content);
}
}
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage
messages = []
async def main():
async for message in query(
prompt="Help me write a Python function to calculate fibonacci numbers",
options=ClaudeAgentOptions(
system_prompt={
"type": "preset",
"preset": "claude_code",
"append": "Always include detailed docstrings and type hints in Python code.",
}
),
):
messages.append(message)
if isinstance(message, AssistantMessage):
print(message.content)
asyncio.run(main())
提升跨用户、跨机器的 prompt 缓存命中率
默认情况下,即使两个会话使用相同的 claude_code 预设和相同的 append 文本,只要它们运行的工作目录不同,就无法共享 prompt 缓存条目。这是因为预设会在你的 append 文本之前嵌入每个会话特有的上下文:工作目录、是否为 git 仓库、平台、当前 shell、操作系统版本以及 auto memory 路径。这些上下文中的任何差异都会产生不同的系统提示词,从而导致缓存未命中。CLAUDE.md 内容不会影响系统提示词缓存,因为 SDK 是将其注入对话而非系统提示词。
要让系统提示词在多个会话间保持一致,可设置:
- TypeScript:
excludeDynamicSections: true - Python:
"exclude_dynamic_sections": True
这会将每个会话的上下文移动到第一条用户消息中,使系统提示词只剩下静态的预设内容与你的 append 文本,从而让相同配置在不同用户与机器间共享同一条缓存条目。
注意:
excludeDynamicSections需要@anthropic-ai/claude-agent-sdkv0.2.98 或更高版本,Python 端需要claude-agent-sdkv0.1.58 或更高版本。该选项仅对 preset 对象形式生效,当systemPrompt为字符串时无效。
以下示例将共享的 append 内容与 excludeDynamicSections 搭配使用,使运行在不同目录下的一批 agent 可以复用同一条缓存的系统提示词:
import { query } from "@anthropic-ai/claude-agent-sdk";
for await (const message of query({
prompt: "Triage the open issues in this repo",
options: {
systemPrompt: {
type: "preset",
preset: "claude_code",
append: "You operate Acme's internal triage workflow. Label issues by component and severity.",
excludeDynamicSections: true
}
}
})) {
// ...
}
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions
async def main():
async for message in query(
prompt="Triage the open issues in this repo",
options=ClaudeAgentOptions(
system_prompt={
"type": "preset",
"preset": "claude_code",
"append": "You operate Acme's internal triage workflow. Label issues by component and severity.",
"exclude_dynamic_sections": True,
},
),
):
...
asyncio.run(main())
权衡:工作目录、是否为 git 仓库、平台、当前 shell、操作系统版本与 auto memory 路径仍会传达给 Claude,只是变成第一条用户消息的一部分,而非系统提示词的一部分。用户消息中的指令权重略低于系统提示词中的同等文本,因此 Claude 在推理当前目录或 auto memory 路径时可能不会那么严格依赖它们。当跨会话缓存复用比环境上下文的最大权威性更重要时,再启用此选项。
非交互式 CLI 模式下等效的标志位参见 --exclude-dynamic-system-prompt-sections。
自定义系统提示词
可以将自定义字符串作为 systemPrompt 传入,完全用自己的指令替换默认提示词。
import { query } from "@anthropic-ai/claude-agent-sdk";
const customPrompt = `You are a Python coding specialist.
Follow these guidelines:
- Write clean, well-documented code
- Use type hints for all functions
- Include comprehensive docstrings
- Prefer functional programming patterns when appropriate
- Always explain your code choices`;
const messages = [];
for await (const message of query({
prompt: "Create a data processing pipeline",
options: {
systemPrompt: customPrompt
}
})) {
messages.push(message);
if (message.type === "assistant") {
console.log(message.message.content);
}
}
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage
custom_prompt = """You are a Python coding specialist.
Follow these guidelines:
- Write clean, well-documented code
- Use type hints for all functions
- Include comprehensive docstrings
- Prefer functional programming patterns when appropriate
- Always explain your code choices"""
messages = []
async def main():
async for message in query(
prompt="Create a data processing pipeline",
options=ClaudeAgentOptions(system_prompt=custom_prompt),
):
messages.append(message)
if isinstance(message, AssistantMessage):
print(message.content)
asyncio.run(main())
在 Python 中,对于较大的自定义提示词,建议使用 system_prompt={"type": "file", "path": "..."} 从文件加载,而不是直接传字符串。这是因为 Python SDK 会将字符串形式的提示词作为一个命令行参数传给 CLI 子进程,一旦提示词超出操作系统的参数长度限制,进程尚未发起就会失败(不会发出任何 API 请求)。在 Linux 上报错信息为 Argument list too long。各平台的具体阈值与 Windows 行为参见 SystemPromptFile。
四种方式对比
四种定制方式在存放位置、共享方式,以及对 claude_code 预设内容的保留程度上有所不同:
| 特性 | CLAUDE.md | Output Styles | systemPrompt + append | 自定义 systemPrompt |
|---|---|---|---|---|
| 持久性 | 项目内文件 | 保存为文件 | 仅当前会话 | 仅当前会话 |
| 可复用性 | 按项目 | 跨项目 | 需在代码中重复 | 需在代码中重复 |
| 管理方式 | 文件系统 | CLI + 文件 | 代码中 | 代码中 |
| 默认工具 | 保留 | 保留 | 保留 | 丢失(除非自行包含) |
| 内置安全性 | 维持 | 维持 | 维持 | 需自行添加 |
| 环境上下文 | 自动 | 自动 | 自动 | 需自行提供 |
| 定制程度 | 仅追加 | 替换或扩展默认 | 仅追加 | 完全控制 |
| 版本控制 | 随项目 | 是 | 随代码 | 随代码 |
| 作用范围 | 项目专属 | 用户级或项目级 | 代码会话 | 代码会话 |
「带 append」指的是使用 systemPrompt: { type: "preset", preset: "claude_code", append: "..." }(TypeScript)或 system_prompt={"type": "preset", "preset": "claude_code", "append": "..."}(Python)。CLAUDE.md 本身不会改变系统提示词:SDK 会将其内容作为项目上下文注入对话。
组合使用
以上方式可以组合使用。持久化的输出样式或 CLAUDE.md 设定长期行为,append 则在其之上叠加会话特定的指令,而不改动已保存的配置。
将输出样式与会话特定的追加内容结合
以下示例假设「Code Reviewer」输出样式已经启用。append 部分在该人设之上叠加了本次会话的关注重点,使单次审查会话可以优先关注 OAuth 与 token 存储,而无需修改已保存的输出样式:
import { query } from "@anthropic-ai/claude-agent-sdk";
// Assuming "Code Reviewer" output style is active (via /config or settings)
// Add session-specific focus areas
const messages = [];
for await (const message of query({
prompt: "Review this authentication module",
options: {
systemPrompt: {
type: "preset",
preset: "claude_code",
append: `
For this review, prioritize:
- OAuth 2.0 compliance
- Token storage security
- Session management
`
}
}
})) {
messages.push(message);
}
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions
# Assuming "Code Reviewer" output style is active (via /config or settings)
# Add session-specific focus areas
messages = []
async def main():
async for message in query(
prompt="Review this authentication module",
options=ClaudeAgentOptions(
system_prompt={
"type": "preset",
"preset": "claude_code",
"append": """
For this review, prioritize:
- OAuth 2.0 compliance
- Token storage security
- Session management
""",
}
),
):
messages.append(message)
asyncio.run(main())
另请参阅
- Output styles:创建、管理和共享 CLI 输出样式,包括文件格式与存储位置
- How Claude remembers your project:CLAUDE.md 应写什么、放在哪里,以及如何编写有效的项目指令
- TypeScript SDK reference:完整的
Options类型,包括systemPrompt、settingSources、settings - Python SDK reference:完整的
ClaudeAgentOptions类型,包括system_prompt与setting_sources - Settings:
settings.json参考文档,包括输出样式等配置的存储位置