系统提示定义了Claude的行为、能力和响应风格。Claude Code SDK提供了三种自定义系统提示的方法:使用输出样式(持久的、基于文件的配置)、附加到默认提示或完全替换它。

理解系统提示

系统提示是塑造Claude在整个对话过程中行为的初始指令集。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:使用appendSystemPrompt

appendSystemPrompt选项将您的自定义指令添加到默认系统提示中,同时保留所有内置功能。

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

const messages = []

for await (const message of query({
  prompt: "Help me write a Python function to calculate fibonacci numbers",
  options: {
    appendSystemPrompt: "Always include detailed docstrings and type hints in Python code."
  }
})) {
  messages.push(message)
  if (message.type === 'assistant') {
    console.log(message.message.content)
  }
}

方法3:使用customSystemPrompt

customSystemPrompt选项用您的自定义指令完全替换默认系统提示。

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

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: {
    customSystemPrompt: customPrompt
  }
})) {
  messages.push(message)
  if (message.type === 'assistant') {
    console.log(message.message.content)
  }
}

三种方法的比较

特性输出样式appendSystemPromptcustomSystemPrompt
持久性✅ 保存为文件❌ 仅限会话❌ 仅限会话
可重用性✅ 跨项目❌ 代码重复❌ 代码重复
管理✅ CLI + 文件⚠️ 在代码中⚠️ 在代码中
默认工具✅ 保留✅ 保留❌ 丢失(除非包含)
内置安全性✅ 维护✅ 维护❌ 必须添加
环境上下文✅ 自动✅ 自动❌ 必须提供
自定义级别⚠️ 替换默认⚠️ 仅添加✅ 完全控制
版本控制✅ 是✅ 与代码一起✅ 与代码一起
发现性/output-style❌ 不可发现❌ 不可发现

用例和最佳实践

何时使用输出样式

最适合:

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

示例:

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

何时使用appendSystemPrompt

最适合:

  • 添加特定的编码标准或偏好
  • 自定义输出格式
  • 添加领域特定知识
  • 修改响应详细程度

何时使用customSystemPrompt

最适合:

  • 完全控制Claude的行为
  • 专门的单会话任务
  • 测试新的提示策略
  • 不需要默认工具的情况

组合方法

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

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

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

// 假设"Code Reviewer"输出样式已激活(通过/output-style)
// 添加会话特定的重点领域
const messages = []

for await (const message of query({
  prompt: "Review this authentication module",
  options: {
    appendSystemPrompt: `
      For this review, prioritize:
      - OAuth 2.0 compliance
      - Token storage security
      - Session management
    `
  }
})) {
  messages.push(message)
}

另请参阅