修改系统提示词

学习如何通过三种方法修改系统提示词来自定义Claude的行为 - 输出样式、带append的systemPrompt和自定义系统提示词。

系统提示词定义了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.md文件（项目级指令）

CLAUDE.md文件提供项目特定的上下文和指令，当Agent SDK在目录中运行时会自动读取。它们作为项目的持久”记忆”。

​

CLAUDE.md如何与SDK配合工作

位置和发现：

• 项目级： 工作目录中的CLAUDE.md或.claude/CLAUDE.md
• 用户级： ~/.claude/CLAUDE.md用于所有项目的全局指令

重要： SDK只有在您明确配置settingSources（TypeScript）或setting_sources（Python）时才会读取CLAUDE.md文件：

• 包含'project'以加载项目级CLAUDE.md
• 包含'user'以加载用户级CLAUDE.md（~/.claude/CLAUDE.md）

claude_code系统提示词预设不会自动加载CLAUDE.md - 您还必须指定设置源。

内容格式： CLAUDE.md文件使用纯markdown，可以包含：

• 编码指南和标准
• 项目特定上下文
• 常用命令或工作流程
• API约定
• 测试要求

​

CLAUDE.md示例

# 项目指南

## 代码风格

- 使用TypeScript严格模式
- 在React中优先使用函数组件
- 始终为公共API包含JSDoc注释

## 测试

- 提交前运行`npm test`
- 保持>80%的代码覆盖率
- 使用jest进行单元测试，playwright进行E2E测试

## 命令

- 构建：`npm run build`
- 开发服务器：`npm run dev`
- 类型检查：`npm run typecheck`

​

在SDK中使用CLAUDE.md

TypeScript

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

// 重要：您必须指定settingSources来加载CLAUDE.md
// 仅claude_code预设不会加载CLAUDE.md文件
const messages = [];

for await (const message of query({
  prompt: "为用户配置文件添加一个新的React组件",
  options: {
    systemPrompt: {
      type: "preset",
      preset: "claude_code", // 使用Claude Code的系统提示词
    },
    settingSources: ["project"], // 从项目加载CLAUDE.md所必需
  },
})) {
  messages.push(message);
}

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

​

何时使用CLAUDE.md

最适合：

• 团队共享上下文 - 每个人都应该遵循的指南
• 项目约定 - 编码标准、文件结构、命名模式
• 常用命令 - 特定于您项目的构建、测试、部署命令
• 长期记忆 - 应该在所有会话中持续存在的上下文
• 版本控制指令 - 提交到git以便团队保持同步

关键特征：

• ✅ 在项目的所有会话中持续存在
• ✅ 通过git与团队共享
• ✅ 自动发现（无需代码更改）
• ⚠️ 需要通过settingSources加载设置

​

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

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

​

创建输出样式

TypeScript

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",
  "彻底的代码审查助手",
  `您是一位专业的代码审查员。

对于每个代码提交：
1. 检查错误和安全问题
2. 评估性能
3. 建议改进
4. 评估代码质量（1-10分）`
);

​

使用输出样式

创建后，通过以下方式激活输出样式：

• CLI：/output-style [style-name]
• 设置：.claude/settings.local.json
• 创建新的：/output-style:new [description]

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

​

方法3：使用带append的systemPrompt

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

TypeScript

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

const messages = [];

for await (const message of query({
  prompt: "帮我写一个计算斐波那契数列的Python函数",
  options: {
    systemPrompt: {
      type: "preset",
      preset: "claude_code",
      append:
        "在Python代码中始终包含详细的文档字符串和类型提示。",
    },
  },
})) {
  messages.push(message);
  if (message.type === "assistant") {
    console.log(message.message.content);
  }
}

​

方法4：自定义系统提示词

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

TypeScript

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

const customPrompt = `您是一位Python编码专家。
遵循以下指南：
- 编写干净、文档完善的代码
- 为所有函数使用类型提示
- 包含全面的文档字符串
- 在适当时优先使用函数式编程模式
- 始终解释您的代码选择`;

const messages = [];

for await (const message of query({
  prompt: "创建一个数据处理管道",
  options: {
    systemPrompt: customPrompt,
  },
})) {
  messages.push(message);
  if (message.type === "assistant") {
    console.log(message.message.content);
  }
}

​

所有四种方法的比较

功能	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使用的指令

示例：

• “所有API端点都应该使用async/await模式”
• “提交前运行npm run lint:fix”
• “数据库迁移在migrations/目录中”

重要： 要加载CLAUDE.md文件，您必须明确设置settingSources: ['project']（TypeScript）或setting_sources=["project"]（Python）。没有此设置，claude_code系统提示词预设不会自动加载CLAUDE.md。

​

何时使用输出样式

最适合：

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

示例：

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

​

何时使用带append的systemPrompt

最适合：

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

​

何时使用自定义systemPrompt

最适合：

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

​

组合方法

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

​

示例：带会话特定添加的输出样式

TypeScript

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

// 假设"Code Reviewer"输出样式已激活（通过/output-style）
// 添加会话特定的关注领域
const messages = [];

for await (const message of query({
  prompt: "审查这个身份验证模块",
  options: {
    systemPrompt: {
      type: "preset",
      preset: "claude_code",
      append: `
        对于此次审查，优先考虑：
        - OAuth 2.0合规性
        - 令牌存储安全性
        - 会话管理
      `,
    },
  },
})) {
  messages.push(message);
}

​

另请参阅

• 输出样式 - 完整的输出样式文档
• TypeScript SDK指南 - 完整的SDK使用指南
• TypeScript SDK参考 - 完整的API文档
• 配置指南 - 通用配置选项