自定义 Agent 系统提示词时，使用 claude_code 预设能完整保留 Claude Code 的工具指导、代码风格和安全规则；若要追加自定指令，用 append 属性最安全，不会丢失任何预设内容。输出样式（output styles）以 Markdown 文件形式持久保存并可跨项目复用，但 Python SDK 不支持程序化选择输出样式，只能通过 append 或自定义字符串替代。启用 excludeDynamicSections 可让不同工作目录的会话共享提示缓存，但环境上下文会移入首条用户消息，权重略低。

Claude Code Agent SDK 系统提示词配置：预设、自定义与 combine 方法

系统提示词定义了 Claude 的行为、能力和回复风格。Agent SDK 提供三个起点：claude_code 预设（适合终端或 IDE 类编码助手）、自定义字符串（适合不同交互界面、身份或权限模型的 Agent）、以及最小默认（只包含工具调用）。

本页内容：

系统提示词如何工作：配置选择决策表
自定义 Agent 行为：CLAUDE.md、输出样式、append 和自定义字符串
四种方法对比：持久性、作用域和保留内容
组合使用：将多种定制方法迭加

系统提示词如何工作

系统提示词是初始指令集，决定 Claude 在整个对话中的行为。Agent SDK 有三种起点：

最小默认：TypeScript 不传 systemPrompt 或 Python 不传 system_prompt 时，SDK 使用仅覆盖工具调用的极简提示，不会包含 Claude Code 的编码指南、回复风格和项目上下文。这与 claude -p 的行为不同（CLI 默认使用完整 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 只发送你提供的内容。

如何选择起点

判断依据是你的 Agent 与 Claude Code 的相似程度：如果是运行在代码仓库中、有人类观看流式输出并指导工作的编码 Agent，直接用预设。产品差异越大，越需要自己编写自定义提示词。

你正在构建的场景	推荐方式	获得的内容
终端或 IDE 类编码工具，有人类观看和指导，Claude Code 的默认就是你要的	`claude_code` 预设	完整 Claude Code 提示：工具指导、安全规则、终端友好的回复、仓库惯例意识
同上，但需要添加产品特定的规则（编码标准、输出格式、领域上下文）	`claude_code` 预设 + `append`	上述所有 + 追加在末尾的自定义指令。风险最低，不会丢失任何预设内容
不同交互界面、不同身份、不同权限模型的 Agent，或非编码 Agent	自定义字符串	只包含你写的内容。你需要负责补充 Agent 仍然需要的工具指导和安全指令
极简的工具调用循环，没有 Agent 人格，所有行为由用户提示提供	不设置 `systemPrompt`	最小默认：只支持工具调用，无其他内容

“不同于 Claude Code” 通常表现为以下之一：

不同交互界面：输出不是由触发者在终端中阅读。聊天界面、结构化输出消费者、非编码自动化每种都需要匹配其输出渲染和审查方式的提示。无监督编码自动化（如 CI 修复 lint 错误或审查 diff）仍然适合预设，因为预设就是为“编码工作”本身设计的。
不同身份：Agent 不应该把自己介绍成 Claude Code。支持机器人、数据分析助手或任何领域专用的 Agent 需要自己的名称、范围和人格。
不同权限模型：Agent 自主运行，无需人类每步审批，或者操作资源范围狭窄。Claude Code 的提示假设有人类在环且拥有完整工具集。
非编码任务：Claude Code 的大部分提示是编码指导。对于研究、内容或运维类 Agent，这些指导会与你需要的真实指令竞争。

对比表显示了每种定制方法保留了预设的哪些部分。

自定义 Agent 行为

输出样式、append 和自定义字符串直接修改系统提示词。CLAUDE.md 走不同路径：SDK 读取它并将内容注入到对话中作为项目上下文，而不是注入到系统提示词，因此它可以与任何系统提示词配置配合使用。技能、钩子和权限也影响系统提示词之外的行为，由各自文档覆盖。

CLAUDE.md：项目级指令

CLAUDE.md 文件为 Claude 提供持久的项目上下文和指令。SDK 将其内容注入对话（而非系统提示词），因此可与任何系统提示词配置配合使用。关于 CLAUDE.md 写什么、放哪里、怎么写有效指令，参考 Claude 如何记住你的项目。本节只介绍 SDK 特定的部分：CLAUDE.md 如何加载。

当匹配的设置源（setting source）启用时，SDK 读取 CLAUDE.md：'project' 加载工作目录下的 CLAUDE.md 或 .claude/CLAUDE.md；'user' 加载 ~/.claude/CLAUDE.md。默认 query() 选项启用两个源，因此 CLAUDE.md 会自动加载。如果你显式设置了 settingSources（TypeScript）或 setting_sources（Python），请确保包含你需要的源。CLAUDE.md 加载由设置源控制，与 claude_code 预设无关。

在 SDK 中加载 CLAUDE.md

设置 settingSources 为你的 CLAUDE.md 所在级别。以下示例加载项目级 CLAUDE.md 同时使用 claude_code 预设，使 Claude 同时拥有完整编码 Agent 提示和项目惯例：

typescript

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 中的项目指南

python

from claude_agent_sdk import query, ClaudeAgentOptions

messages = []

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)

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

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：

markdown

---
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 并选择一个输出样式
设置：在 .claude/settings.local.json 中设置 outputStyle
TypeScript SDK：在传给 query() 的内联 settings 对象中设置 outputStyle，或让 settings 指向设置了该字段的配置文件。outputStyle 不是顶层 Options 字段

Python SDK 没有程序化选择输出样式的选项。对于无法写入 .claude/settings.local.json 的仅代码部署，请改用 append 或自定义字符串。

SDK 用户注意： 输出样式只有在 settingSources 包含 'user' 或 'project' 时才会加载。

追加到 `claude_code` 预设

使用 append 属性在保留所有内置功能的同时追加自定义指令：

typescript

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);
  }
}

python

from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage

messages = []

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)

提高跨用户和跨机器的提示缓存命中率

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

要使系统提示词在不同会话间完全一致，设置 excludeDynamicSections: true（TypeScript）或 "exclude_dynamic_sections": True（Python）。会话上下文会移到首条用户消息中，系统提示词只包含静态预设和 append 文本，因此相同配置的不同用户和机器可共享一个缓存条目。

excludeDynamicSections 需要 TypeScript 版 @anthropic-ai/claude-agent-sdk v0.2.98 或更高版本，Python 版 claude-agent-sdk v0.1.58 或更高版本。它只适用于预设对象形式，当 systemPrompt 为字符串时无效。

以下示例将共享的 append 块与 excludeDynamicSections 配对，使从不同目录运行的一组 Agent 可以复用相同的缓存系统提示：

typescript

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
    }
  }
})) {
  // ...
}

python

from claude_agent_sdk import query, ClaudeAgentOptions

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,
        },
    ),
):
    ...

权衡： 工作目录、git 仓库标志、平台、激活的 shell、OS 版本、自动记忆路径仍然会到达 Claude，但作为首条用户消息的一部分，而非系统提示词。首条用户消息中的指令权重略低于系统提示词中相同的文本，因此 Claude 在推理当前目录或自动记忆路径时可能不那么严格遵守。当跨会话缓存复用比最大限度权威的环境上下文更重要时启用此选项。

非交互式 CLI 模式的对应标志参见 --exclude-dynamic-system-prompt-sections。

自定义系统提示词

提供一个自定义字符串作为 systemPrompt，完全替换默认提示：

typescript

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);
  }
}

python

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

四种方法对比

特性	CLAUDE.md	输出样式	`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

用于应该适用于项目中每个会话的指令，无论会话使用什么系统提示词：编码标准、常用命令、架构上下文、团队惯例。CLAUDE.md 提交到仓库，因此与它所描述的代码保持同步。完整指导参见何时添加到 CLAUDE.md。

CLAUDE.md 在 project 设置源启用时加载——默认 query() 选项已启用。如果显式设置了 settingSources，请包含 'project' 以继续加载项目级 CLAUDE.md。

何时使用输出样式

输出样式适用于在 CLI 和 SDK 之间复用而不更改应用代码的人格。因为它们以文件形式存在于 .claude/output-styles，同一个人格可以通过 CLI 的 /config 和任何加载了匹配设置源的 SDK 会话使用。

最适合：

跨会话持久的行为更改
团队共享配置
专用助手（代码审查、数据科学家、DevOps 助手）
需要版本控制的复杂提示修改

示例：

创建专门的 SQL 优化助手
构建安全审查员
开发具有特定教学法的教学助手

何时使用 `systemPrompt` + append

当 claude_code 预设已经适合你的产品，只需要叠加额外指令时使用 append。可以保留预设的工具指导、安全规则和编码惯例，无需重新实现。

最适合：

添加特定编码标准或偏好
自定义输出格式
添加领域特定知识
修改回复详细程度
增强 Claude Code 默认行为而不丢失工具指令

何时使用自定义 `systemPrompt`

当 Agent 的交互界面、身份或权限模型与 Claude Code 不同时（如如何选择起点所述），使用自定义提示。你定义完整的指令集，包括 Agent 需要的任何工具指导和安全规则。

最适合：

完全控制 Claude 的行为
专门的单会话任务
测试新的提示策略
不需要默认工具的场景
构建具有独特行为的专用 Agent

组合使用

这些方法可以组合。持久化的输出样式或 CLAUDE.md 设置长期行为，append 在不触碰已保存配置的情况下叠加密令级指令。

组合输出样式与会话级追加

以下示例假设 Code Reviewer 输出样式已激活。append 块叠加密令级关注点，使单个审查会话可以优先考虑 OAuth 和令牌存储，而不更改已保存的输出样式：

typescript

import { query } from "@anthropic-ai/claude-agent-sdk";

// 假设 "Code Reviewer" 输出样式已激活（通过 /config 或设置）
// 添加会话级关注点
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);
}

python

from claude_agent_sdk import query, ClaudeAgentOptions

# 假设 "Code Reviewer" 输出样式已激活（通过 /config 或设置）
# 添加会话级关注点
messages = []

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)

参见

输出样式：创建、管理和共享 CLI 的输出样式，包括文件格式和存储位置
Claude 如何记住你的项目：CLAUDE.md 写什么、放哪里、怎么写有效项目指令
TypeScript SDK 参考：完整 Options 类型，包括 systemPrompt、settingSources 和 settings
Python SDK 参考：完整 ClaudeAgentOptions 类型，包括 system_prompt 和 setting_sources
设置：settings.json 参考，包括输出样式和其他配置的存储位置

常见问题

如何给 Claude Agent 添加项目级别的持久指令？

在项目根目录创建 CLAUDE.md 文件，SDK 会在默认设置源下自动加载。指令会作为项目上下文注入对话，不修改系统提示词，且提交到 git 后团队共享。需要显式控制时，确保 settingSources 包含 'project'。

append 和 CLAUDE.md 有什么区别？

append 直接将文本追加到 claude_code 预设的末尾，属于系统提示词的一部分，仅影响当前会话。CLAUDE.md 的内容被注入到对话（而非系统提示词），并且跨所有会话持久存在、随仓库版本控制。两者可以同时使用。

输出样式在 Python SDK 中怎么激活？

Python SDK 不支持程序化选择输出样式。如果无法写入 .claude/settings.local.json，请改用 system_prompt 的 append 参数或写一个自定义字符串。输出样式在 TypeScript SDK 中可通过内联 settings 对象设置。

`excludeDynamicSections` 有什么副作用？

工作目录、git 仓库状态、平台等信息会从系统提示词移到首条用户消息中，权重略低。Claude 在推理环境时可能不如原本严格遵守。仅在跨会话缓存复用收益大于环境指令权威性的场景启用。

Claude Code Agent SDK 系统提示词配置：预设、自定义与 combine 方法 ​

系统提示词如何工作 ​

如何选择起点 ​

自定义 Agent 行为 ​

CLAUDE.md：项目级指令 ​

在 SDK 中加载 CLAUDE.md ​

输出样式：持久化配置 ​

创建输出样式 ​

激活输出样式 ​

追加到 claude_code 预设 ​

提高跨用户和跨机器的提示缓存命中率 ​

自定义系统提示词 ​

四种方法对比 ​

使用场景与最佳实践 ​

何时使用 CLAUDE.md ​

何时使用输出样式 ​

何时使用 systemPrompt + append ​

何时使用自定义 systemPrompt ​

组合使用 ​

组合输出样式与会话级追加 ​

参见 ​

常见问题 ​

如何给 Claude Agent 添加项目级别的持久指令？ ​

append 和 CLAUDE.md 有什么区别？ ​

输出样式在 Python SDK 中怎么激活？ ​

excludeDynamicSections 有什么副作用？ ​

Claude Code Agent SDK 系统提示词配置：预设、自定义与 combine 方法

系统提示词如何工作

如何选择起点

自定义 Agent 行为

CLAUDE.md：项目级指令

在 SDK 中加载 CLAUDE.md

输出样式：持久化配置

创建输出样式

激活输出样式

追加到 `claude_code` 预设

提高跨用户和跨机器的提示缓存命中率

自定义系统提示词

四种方法对比

使用场景与最佳实践

何时使用 CLAUDE.md

何时使用输出样式

何时使用 `systemPrompt` + append

何时使用自定义 `systemPrompt`

组合使用

组合输出样式与会话级追加

参见

常见问题

如何给 Claude Agent 添加项目级别的持久指令？

append 和 CLAUDE.md 有什么区别？

输出样式在 Python SDK 中怎么激活？

`excludeDynamicSections` 有什么副作用？