修改系统提示词

在 claude_code 预设和自定义系统提示词之间进行选择，并通过 CLAUDE.md、输出样式、追加或完全自定义提示词来自定义行为。

系统提示词定义了 Claude 的行为、能力和响应风格。从用于 CLI 或 IDE 类编码工具的 claude_code 预设开始，其中人类观察并指导工作。为具有不同界面、身份或权限模型的代理编写自己的提示词。

系统提示词的工作原理

系统提示词是初始指令集，它塑造了 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 Code 给 Claude 的每个响应的指令。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 读取 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 提示词，也有你的项目约定：

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" // 使用 Claude Code 的系统提示词
},
settingSources: ["project"] // 从项目加载 CLAUDE.md
}
})) {
messages.push(message);
}

// 现在 Claude 可以访问来自 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",  # 使用 Claude Code 的系统提示词
},
setting_sources=["project"],  # 从项目加载 CLAUDE.md
),
):
messages.append(message)


asyncio.run(main())

# 现在 Claude 可以访问来自 CLAUDE.md 的项目指南

当你运行任一示例时，SDK 会在 Claude 工作时流式传输消息：系统初始化消息、助手消息、携带工具结果的用户消息，以及包含会话结果的最终结果消息。

CLAUDE.md 在项目的所有会话中持久存在，通过 git 与你的团队共享，并自动发现而无需代码更改。如果你传递空的 settingSources 数组，则不会加载。

输出样式用于持久配置

输出样式是保存的指令集，可以改变 Claude 的角色、语气和输出格式。它们存储为 markdown 文件，可以在会话和项目中重复使用。

创建输出样式

输出样式是一个 markdown 文件，其 frontmatter 中有元数据，后面是提示词内容。将其保存到 ~/.claude/output-styles/ 以获得在每个项目中可用的用户级样式，或保存到你的存储库中的 .claude/output-styles/ 以获得可以提交和与你的团队共享的项目级样式。

自定义输出样式会省略 claude_code 预设的软件工程指令，并使用你自己的。要保留它们并在其基础上分层你的指令，请在 frontmatter 中设置 keep-coding-instructions: true。这些指令仅在 Claude Code 的完整系统提示词中，因此该设置在较短系统提示词的会话中无效，你可以通过 CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT 打开或关闭该提示词。当你的 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：运行 /output-style <style>，例如 /output-style concise，或运行 /config 并选择一个。/output-style 命令需要 Claude Code v2.1.269 或更高版本。

• 设置：在 .claude/settings.local.json 中设置 outputStyle

• TypeScript SDK：在传递给 query() 的内联 settings 对象内设置 outputStyle，或将 settings 指向设置它的设置文件。outputStyle 不是顶级 Options 字段：

  const options = { settings: { outputStyle: "Explanatory" } };
  

在 Python SDK 中，通过 settings 选项设置 outputStyle，该选项接受 JSON 字符串（如 '{"outputStyle": "Explanatory"}'）或设置它的设置文件的路径。

SDK 用户注意： 当你在选项中包含 settingSources: ['user'] 或 settingSources: ['project']（TypeScript）/ setting_sources=["user"] 或 setting_sources=["project"]（Python）时，输出样式会被加载。

追加到 `claude_code` 预设

你可以使用带有 append 属性的 Claude Code 预设来添加自定义指令，同时保留所有内置功能。

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())

改进跨用户和机器的提示词缓存

默认情况下，两个使用相同 claude_code 预设和 append 文本的会话，如果从不同的工作目录运行，仍然无法共享提示词缓存条目。这是因为预设在你的 append 文本之前在系统提示词中嵌入了每个会话的上下文：工作目录、它是否是 git 存储库、平台、活跃的 shell、操作系统版本和自动记忆路径。该上下文中的任何差异都会产生不同的系统提示词和缓存未命中。CLAUDE.md 内容不会影响系统提示词缓存，因为 SDK 将其注入到对话中，而不是系统提示词。

要使系统提示词在会话中相同，请在 TypeScript 中设置 excludeDynamicSections: true，或在 Python 中设置 "exclude_dynamic_sections": True。每个会话的上下文移动到第一条用户消息中，只在系统提示词中保留静态预设和你的 append 文本，以便相同的配置在用户和机器之间共享缓存条目。

以下示例将共享的 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、操作系统版本和自动记忆路径仍然会到达 Claude，但作为第一条用户消息的一部分，而不是系统提示词。用户消息中的指令比系统提示词中的相同文本的权重略低，因此在推理当前目录或自动记忆路径时，Claude 可能会更少地依赖它们。当跨会话缓存重复使用比最大化权威环境上下文更重要时，启用此选项。

对于非交互式 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。请参阅 SystemPromptFile 了解平台阈值和 Windows 行为。

缓存自定义提示词的静态部分

在 TypeScript SDK 中，你可以将自定义提示词作为字符串数组而不是一个字符串传递，在静态部分和其余部分之间使用 SYSTEM_PROMPT_DYNAMIC_BOUNDARY 标记。当你的提示词结合每个请求都相同的指令与每个请求都改变的上下文（例如 agent 处理的客户或工单）时，使用此方法。当你将两个部分作为一个字符串传递时，对每个请求部分的更改会改变整个系统提示词，因此静态指令也会错过缓存。此形式在 Python SDK 中不可用；ClaudeAgentOptions 列出了 system_prompt 接受的形式。

要拆分提示词，从 @anthropic-ai/claude-agent-sdk 导入 SYSTEM_PROMPT_DYNAMIC_BOUNDARY 并将其作为自己的数组元素在两个部分之间传递。SDK 将标记之前的字符串作为一个文本块发送，将标记之后的字符串作为第二个块发送，每个块都有自己的缓存断点。在下面的示例中，支持 agent 从文件加载其分类指令，并在每个请求上接收一个工单的详细信息，因此指令保持缓存而工单详细信息改变：

import { readFile } from "node:fs/promises";
import { query, SYSTEM_PROMPT_DYNAMIC_BOUNDARY } from "@anthropic-ai/claude-agent-sdk";

// 在每个请求上相同
const instructions = await readFile("triage-instructions.md", "utf8");
// 在每个请求上不同
const ticketContext = "Customer plan: Enterprise. Other open tickets from this customer: 3.";

for await (const message of query({
  prompt: "Triage ticket 4821",
  options: {
    systemPrompt: [instructions, SYSTEM_PROMPT_DYNAMIC_BOUNDARY, ticketContext]
  }
})) {
  // ...
}

Track cache tokens 描述了每个结果消息上的 cache_creation_input_tokens 和 cache_read_input_tokens 字段。

SDK 从数组中组装块如下：

• SDK 将标记两侧的字符串与它们之间的空行连接，并删除标记本身，因此标记文本不会到达 Claude。
• 如果你多次包含标记，第一个是拆分，SDK 删除其他的。
• 如果你省略标记，SDK 将所有字符串连接到一个块中，与传递一个字符串相同。

改变现有会话的提示词

默认情况下，如果你在使用 resume 或 continue 返回会话时传递不同的 append 或自定义提示词，Claude 在下一个转折点不会看到它。Claude Code 在会话的第一个请求时记录系统提示词，并在会话被压缩之前重复使用该记录。新文本在压缩后或在新会话中生效。

在会话中期更新 Claude 的指令

如果你在系统提示词中放置的指令需要在会话运行时改变，例如因为你的用户将 agent 切换到只读模式或在你的应用中编辑其配置，请在对话中发送新指令，而不是改变 systemPrompt：

• 在你的下一条消息中：在你发送的下一条用户消息中包含新指令。
• 从 hook 中：从 UserPromptSubmit 或 PostToolUse hook 回调 返回 additionalContext，写成事实陈述，例如"工作区现在是只读的"。SDK 在 hook 触发的点将文本插入到对话中，因此记录的提示词保持不变。

在迭代措辞时关闭记录

当你迭代提示词措辞并希望每次编辑都到达你恢复的会话时，在系统提示词的对象形式上设置 snapshot 为 false。Claude Code 然后在每个请求上重建提示词。该字段在 TypeScript 中的 systemPrompt 的预设和自定义形式上可用，在 Python 中的 system_prompt 上可用，并需要 @anthropic-ai/claude-agent-sdk v0.3.257 或更高版本，或 claude-agent-sdk v0.2.153 或更高版本。

在生产中保持记录打开。关闭记录时，恢复的会话上的不同 append 或自定义提示词在下一个转折点到达 Claude，该请求无法重复使用会话的 prompt cache。在 API 强制执行 preserved thinking 的地方，Claude 也会失去其早期转折点的思考。

在 cloud sessions 之外，如果你通过 extraArgs 传递 --bare 或设置 CLAUDE_CODE_SIMPLE=1 在 bare mode 中启动 Claude Code，记录保持关闭，除非你设置 snapshot: true。

默认情况下记录 append 或自定义提示词需要 Claude Code v2.1.265 或更高版本，TypeScript Agent SDK 从 v0.3.265 捆绑，Python Agent SDK 从 v0.2.153 捆绑。在 Claude Code v2.1.268 之前，不 fetch feature flags 的会话，包括 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上的会话，在每个请求上重建提示词，snapshot 无效。

比较四种方法

这四种自定义方法在存储位置、共享方式以及从 claude_code 预设保留的内容方面有所不同。

"带有追加"是指在 TypeScript 中使用 systemPrompt: { type: "preset", preset: "claude_code", append: "..." }，或在 Python 中使用 system_prompt={"type": "preset", "preset": "claude_code", "append": "..."}。CLAUDE.md 不会改变系统提示本身：SDK 将其内容作为项目上下文注入到对话中。

组合方法

这些方法可以组合使用。持久化的输出样式或 CLAUDE.md 设置长期行为，而 append 在不触及保存配置的情况下在顶部分层会话特定的指令。

将输出样式与会话特定的添加内容组合

下面的示例假设已经激活了代码审查员输出样式。append 块在角色的基础上分层会话特定的关注领域，因此单个审查会话可以优先考虑 OAuth 和令牌存储，而无需更改保存的输出样式：

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())

另请参阅

• 输出样式：为 CLI 创建、管理和共享输出样式，包括文件格式和存储位置
• Claude 如何记住您的项目：CLAUDE.md 中应放入的内容、放置位置以及如何编写有效的项目说明
• TypeScript SDK 参考：完整的 Options 类型，包括 systemPrompt、settingSources 和 settings
• Python SDK 参考：完整的 ClaudeAgentOptions 类型，包括 system_prompt 和 setting_sources
• Settings：settings.json 参考，包括输出样式和其他配置的存储位置