{/* TRANSLATED — 已翻译为中文 */}

> ## 文档索引
> 在此获取完整文档索引: https://code.claude.com/docs/llms.txt
> 使用此文件发现所有可用页面，然后再进一步探索。

# 修改系统提示

> 在 `claude_code` 预设和自定义系统提示之间选择，并使用 CLAUDE.md、输出样式、append 或完全自定义提示来自定义行为。

系统提示定义了 Claude 的行为、能力和响应风格。从 `claude_code` 预设开始，适用于人类观看和引导工作的 CLI 或 IDE 类编码工具。为具有不同界面、身份或权限模型的智能体编写自己的提示。

本页涵盖：

* [系统提示的工作原理](#how-system-prompts-work)，包含在预设、带 `append` 的预设和自定义提示之间选择的决策表
* [自定义智能体行为](#customize-agent-behavior)，使用 CLAUDE.md 文件、输出样式、`append` 或自定义字符串
* [比较四种方法](#compare-the-four-approaches)，按持久性、作用域和保留内容
* [组合方法](#combine-approaches)以叠加自定义方法

## 系统提示的工作原理

系统提示是塑造 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 的相似程度：在仓库中运行的编码智能体，有人类观看流式输出并引导工作。您的产品距离越远，您就越需要编写自己的提示。

| 您正在构建的内容                                                                                             | 使用                                   | 获得的内容                                                                                                                  |
| :----------------------------------------------------------------------------------------------------------- | :------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------- |
| CLI 或 IDE 类编码工具，人类观看和引导，Claude Code 的默认值是您想要的                                        | `claude_code` 预设                     | 完整的 Claude Code 提示：工具指导、安全规则、终端友好的响应、仓库规范感知                                                    |
| 同类工具，加上产品特定规则，如编码标准、输出格式或领域上下文                                                 | 带 `append` 的 `claude_code` 预设      | 以上所有内容，加上您的指令追加在预设之后。不移除任何内容，因此这是最低风险的自定义                                          |
| 具有不同界面、身份或权限模型的智能体，或非编码智能体                                                         | 自定义提示字符串                       | 仅您编写的内容。您负责替换智能体仍然需要的工具指导和安全指令                                                                |
| 无智能体人格的薄工具调用循环，您在用户提示中提供所有行为                                                     | 无 `systemPrompt` 选项                | 最小默认值：仅工具调用支持                                                                                                  |

"与 Claude Code 不同"通常意味着以下之一：

* **不同界面**：输出不是在终端中由触发它的人读取。聊天 UI、结构化输出消费者和非编码自动化各自需要匹配其输出渲染和审查方式的提示。无人值守的编码自动化（如修复 lint 错误或审查差异的 CI 作业）仍然适合预设，因为工作本身就是预设所编写的内容。
* **不同身份**：智能体不应将自己呈现为 Claude Code。支持机器人、数据分析助手或任何特定领域的智能体需要自己的名称、范围和角色。
* **不同权限模型**：智能体在没有人类批准每一步的情况下自主运行，或在狭窄的资源集上运行。Claude Code 的提示假设有人类在环中并有权访问完整工具集。
* **非编码任务**：Claude Code 的大部分提示是编码指导。对于研究、内容或操作智能体，该指导与您实际需要的指令竞争。

[比较表](#compare-the-four-approaches)展示了每种自定义方法保留的内容。

## 自定义智能体行为

输出样式、`append` 和自定义提示字符串各自直接更改系统提示。CLAUDE.md 采用不同的路径：SDK 读取它并将其内容作为项目上下文注入对话中，而不是注入系统提示，因此它与您选择的任何系统提示一起塑造行为。[技能](/en/agent-sdk/skills)、[钩子](/en/agent-sdk/hooks)和[权限](/en/agent-sdk/permissions)也在系统提示之外塑造行为，并在其各自的页面上介绍。

### CLAUDE.md 文件用于项目级指令

CLAUDE.md 文件为 Claude 提供持久的项目上下文和指令。SDK 将其内容注入对话中，而不是注入系统提示，因此它们与任何系统提示配置配合使用。有关在 CLAUDE.md 中放置什么、放在哪里以及如何编写有效指令，请参阅 [Claude 如何记住您的项目](/en/memory)。本节介绍 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_code` 预设旁边加载项目级 CLAUDE.md，因此 Claude 既有完整的编码智能体提示，也有您的项目规范：

<CodeGroup>
  ```typescript TypeScript theme={null}
  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
  ```

  ```python Python theme={null}
  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",  # Use Claude Code's system prompt
          },
          setting_sources=["project"],  # Loads CLAUDE.md from project
      ),
  ):
      messages.append(message)

  # Now Claude has access to your project guidelines from CLAUDE.md
  ```
</CodeGroup>

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

### 输出样式用于持久配置

输出样式是修改 Claude 系统提示的保存配置。它们存储为 markdown 文件，可以在会话和项目之间复用。

#### 创建输出样式

输出样式是一个带有[前置元数据](/en/output-styles#frontmatter)的 markdown 文件，后跟提示内容。将其保存到 `~/.claude/output-styles/` 以创建用户级样式（在每个项目中可用），或保存到仓库中的 `.claude/output-styles/` 以创建项目级样式（可以提交并与团队共享）。

默认情况下，自定义输出样式用您自己的替换 `claude_code` 预设的软件工程指令。要保留它们并将您的指令叠加在上面，请在前置元数据中设置 `keep-coding-instructions: true`。当您的智能体仍在进行软件工程工作时保留它们。当您完全替换角色时省略它们。

下面的示例定义了一个保留编码指令的代码审查角色，因为审查代码仍然受益于 Claude Code 的安全性和代码质量指导。将其保存为 `~/.claude/output-styles/code-reviewer.md` 以在项目间可用：

```markdown ~/.claude/output-styles/code-reviewer.md theme={null}
---
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']` 或 `settingSources: ['project']`（TypeScript）/ `setting_sources=["user"]` 或 `setting_sources=["project"]`（Python）时，输出样式会被加载。

### 追加到 `claude_code` 预设

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

<CodeGroup>
  ```typescript TypeScript theme={null}
  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 Python theme={null}
  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)
  ```
</CodeGroup>

#### 改善跨用户和机器的提示缓存

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

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

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

以下示例将共享的 `append` 块与 `excludeDynamicSections` 配合使用，以便从不同目录运行的智能体群可以复用相同的缓存系统提示：

<CodeGroup>
  ```typescript TypeScript theme={null}
  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 Python theme={null}
  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,
          },
      ),
  ):
      ...
  ```
</CodeGroup>

**权衡：** 工作目录、git 仓库标志、平台、活动 shell、操作系统版本和自动记忆路径仍然到达 Claude，但作为第一条用户消息的一部分而不是系统提示。用户消息中的指令比系统提示中的相同文本具有略低的权重，因此 Claude 在推理当前目录或自动记忆路径时可能依赖它们的程度较低。当跨会话缓存复用比最大化权威环境上下文更重要时启用此选项。

有关非交互式 CLI 模式中的等效标志，请参阅 [`--exclude-dynamic-system-prompt-sections`](/en/cli-reference)。

### 自定义系统提示

您可以提供自定义字符串作为 `systemPrompt`，用自己的指令完全替换默认值。

<CodeGroup>
  ```typescript TypeScript theme={null}
  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 Python theme={null}
  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)
  ```
</CodeGroup>

## 比较四种方法

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

| 功能                 | CLAUDE.md        | 输出样式                  | 带 append 的 `systemPrompt` | 自定义 `systemPrompt`  |
| -------------------- | ---------------- | ------------------------- | --------------------------- | ---------------------- |
| **持久性**           | 每个项目文件     | 保存为文件                | 仅会话                      | 仅会话                 |
| **可复用性**         | 每个项目         | 跨项目                    | 代码复制                    | 代码复制               |
| **管理方式**         | 在文件系统上     | CLI + 文件                | 在代码中                    | 在代码中               |
| **默认工具**         | 保留             | 保留                      | 保留                        | 丢失（除非包含）       |
| **内置安全**         | 维持             | 维持                      | 维持                        | 必须添加               |
| **环境上下文**       | 自动             | 自动                      | 自动                        | 必须提供               |
| **自定义级别**       | 仅添加           | 替换或扩展默认值          | 仅添加                      | 完全控制               |
| **版本控制**         | 随项目           | 是                        | 随代码                      | 随代码                 |
| **作用域**           | 项目特定         | 用户或项目                | 代码会话                    | 代码会话               |

"带 append"意味着在 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](/en/memory#when-to-add-to-claude-md)。

当 `project` 设置源启用时（默认 `query()` 选项会启用），CLAUDE.md 文件会加载。如果您在 TypeScript 中显式设置了 `settingSources` 或在 Python 中设置了 `setting_sources`，请包含 `'project'` 以继续加载项目级 CLAUDE.md。

### 何时使用输出样式

输出样式用于您想要在 CLI 和 SDK 之间复用而无需更改应用程序代码的角色。因为它们作为文件存储在 `.claude/output-styles` 中，同一角色可从 CLI 的 `/config` 和任何加载匹配设置源的 SDK 会话中使用。

**最适合：**

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

**示例：**

* 创建专用的 SQL 优化助手
* 构建以安全为中心的代码审查员
* 开发具有特定教学法的教学助手

### 何时使用带 append 的 `systemPrompt`

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

**最适合：**

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

### 何时使用自定义 `systemPrompt`

当您的智能体的界面、身份或权限模型与 Claude Code 不同时使用自定义提示，如[决定起点](#decide-on-a-starting-point)中所述。您定义完整的指令集，包括智能体需要的任何工具指导和安全规则。

**最适合：**

* 完全控制 Claude 的行为
* 专门的单会话任务
* 测试新的提示策略
* 不需要默认工具的情况
* 构建具有独特行为的专门智能体

## 组合方法

这些方法可以组合。持久的输出样式或 CLAUDE.md 设置长期行为，`append` 在不触及保存配置的情况下叠加特定于会话的指令。

### 组合输出样式和特定于会话的添加

下面的示例假设代码审查员输出样式已激活。`append` 块在角色之上叠加特定于会话的重点领域，因此单个审查会话可以优先处理 OAuth 和令牌存储，而无需更改保存的输出样式：

<CodeGroup>
  ```typescript TypeScript theme={null}
  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);
  }
  ```

  ```python Python theme={null}
  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 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)
  ```
</CodeGroup>

## 另请参阅

* [输出样式](/en/output-styles)：创建、管理和共享 CLI 的输出样式，包括文件格式和存储位置
* [Claude 如何记住您的项目](/en/memory)：在 CLAUDE.md 中放置什么、放在哪里以及如何编写有效的项目指令
* [TypeScript SDK 参考](/en/agent-sdk/typescript)：完整的 `Options` 类型，包括 `systemPrompt`、`settingSources` 和 `settings`
* [Python SDK 参考](/en/agent-sdk/python)：完整的 `ClaudeAgentOptions` 类型，包括 `system_prompt` 和 `setting_sources`
* [设置](/en/settings)：`settings.json` 参考，包括输出样式和其他配置的存储位置