系统提示定义了Claude的行为、能力和响应风格。Claude Agent SDK提供了三种自定义系统提示的方法：使用输出样式（持久的、基于文件的配置）、附加到Claude Code的提示，或使用完全自定义的提示。

​
理解系统提示

系统提示是塑造Claude在整个对话过程中行为的初始指令集。
默认行为： Agent SDK默认使用空系统提示以获得最大灵活性。要使用Claude Code的系统提示（工具指令、代码指南等），请在TypeScript中指定systemPrompt: { preset: "claude_code" }或在Python中指定system_prompt="claude_code"。
Claude Code的系统提示包括：
  • 工具使用指令和可用工具
  • 代码风格和格式指南
  • 响应语调和详细程度设置
  • 安全和安全指令
  • 关于当前工作目录和环境的上下文

​
修改方法

​
方法1：输出样式（持久配置）

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

​
创建输出样式

import { writeFile, mkdir } from 'fs/promises'
import { join } from 'path'
import { homedir } from 'os'

async function createOutputStyle(name: string, description: string, prompt: string) {
  // 用户级别：~/.claude/output-styles
  // 项目级别：.claude/output-styles
  const outputStylesDir = join(homedir(), '.claude', 'output-styles')
  
  await mkdir(outputStylesDir, { recursive: true })
  
  const content = `---
name: ${name}
description: ${description}
---

${prompt}`
  
  const filePath = join(outputStylesDir, `${name.toLowerCase().replace(/\s+/g, '-')}.md`)
  await writeFile(filePath, content, 'utf-8')
}

// 示例：创建代码审查专家
await createOutputStyle(
  'Code Reviewer',
  'Thorough code review assistant',
  `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-name]
  • 设置：.claude/settings.local.json
  • 创建新的：/output-style:new [description]

​
方法2：使用带append的systemPrompt

您可以使用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)
  }
}

​
方法3：自定义系统提示

您可以提供自定义字符串作为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)
  }
}

​
三种方法的比较

功能输出样式带append的systemPrompt自定义systemPrompt
持久性✅ 保存为文件❌ 仅限会话❌ 仅限会话
可重用性✅ 跨项目❌ 代码重复❌ 代码重复
管理✅ CLI + 文件⚠️ 在代码中⚠️ 在代码中
默认工具✅ 保留✅ 保留❌ 丢失（除非包含）
内置安全✅ 维护✅ 维护❌ 必须添加
环境上下文✅ 自动✅ 自动❌ 必须提供
自定义级别⚠️ 替换默认⚠️ 仅添加✅ 完全控制
版本控制✅ 是✅ 与代码一起✅ 与代码一起
发现✅ /output-style❌ 不可发现❌ 不可发现
注意： “带append”是指在TypeScript中使用systemPrompt: { type: "preset", preset: "claude_code", append: "..." }或在Python中使用system_prompt={"type": "preset", "preset": "claude_code", "append": "..."}。

​
用例和最佳实践

​
何时使用输出样式

最适合：
  • 跨会话的持久行为更改
  • 团队共享配置
  • 专门的助手（代码审查员、数据科学家、DevOps）
  • 需要版本控制的复杂提示修改
示例：
  • 创建专门的SQL优化助手
  • 构建专注于安全的代码审查员
  • 开发具有特定教学法的教学助手

​
何时使用带append的systemPrompt

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

​
何时使用自定义systemPrompt

最适合：
  • 完全控制Claude的行为
  • 专门的单会话任务
  • 测试新的提示策略
  • 不需要默认工具的情况
  • 构建具有独特行为的专门代理

​
组合方法

您可以组合这些方法以获得最大灵活性：

​
示例：输出样式与会话特定添加

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

// 假设"Code Reviewer"输出样式已激活（通过/output-style）
// 添加会话特定的关注领域
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)
}

​
另请参阅