系统提示词定义了Claude的行为、能力和响应风格。Claude Agent SDK提供了三种自定义系统提示词的方法:使用输出样式(持久的、基于文件的配置)、附加到Claude Code的提示词,或使用完全自定义的提示词。
系统提示词是塑造Claude在整个对话过程中行为的初始指令集。
默认行为: Agent SDK默认使用空系统提示词以获得最大灵活性。要使用Claude Code的系统提示词(工具指令、代码指南等),请在TypeScript中指定systemPrompt: { preset: "claude_code" }或在Python中指定system_prompt="claude_code"。
Claude Code的系统提示词包括:
CLAUDE.md文件提供项目特定的上下文和指令,当Agent 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,可以包含:
# 项目指南
## 代码风格
- 使用TypeScript严格模式
- 在React中优先使用函数组件
- 始终为公共API包含JSDoc注释
## 测试
- 提交前运行`npm test`
- 保持>80%的代码覆盖率
- 使用jest进行单元测试,playwright进行E2E测试
## 命令
- 构建:`npm run build`
- 开发服务器:`npm run dev`
- 类型检查:`npm run typecheck`最适合:
关键特征:
settingSources加载设置输出样式是修改Claude系统提示词的保存配置。它们存储为markdown文件,可以在会话和项目之间重复使用。
创建后,通过以下方式激活输出样式:
/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)时,输出样式会被加载。
systemPrompt您可以使用Claude Code预设和append属性来添加您的自定义指令,同时保留所有内置功能。
您可以提供自定义字符串作为systemPrompt,用您自己的指令完全替换默认设置。
| 功能 | CLAUDE.md | 输出样式 | 带append的systemPrompt | 自定义systemPrompt |
|---|---|---|---|---|
| 持久性 | 每个项目文件 | 保存为文件 | 仅会话 | 仅会话 |
| 可重用性 | 每个项目 | 跨项目 | 代码重复 | 代码重复 |
| 管理 | 在文件系统上 | CLI + 文件 | 在代码中 | 在代码中 |
| 默认工具 | 保留 | 保留 | 保留 | 丢失(除非包含) |
| 内置安全性 | 维护 | 维护 | 维护 |
注意: "带append"是指在TypeScript中使用systemPrompt: { type: "preset", preset: "claude_code", append: "..." }或在Python中使用system_prompt={"type": "preset", "preset": "claude_code", "append": "..."}。
最适合:
示例:
npm run lint:fix"migrations/目录中"重要: 要加载CLAUDE.md文件,您必须明确设置settingSources: ['project'](TypeScript)或setting_sources=["project"](Python)。没有此设置,claude_code系统提示词预设不会自动加载CLAUDE.md。
最适合:
示例:
systemPrompt最适合:
systemPrompt最适合:
您可以组合这些方法以获得最大的灵活性:
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的项目指南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分)`
);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);
}
}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);
}
}| 必须添加 |
| 环境上下文 | 自动 | 自动 | 自动 | 必须提供 |
| 自定义级别 | 仅添加 | 替换默认 | 仅添加 | 完全控制 |
| 版本控制 | 与项目一起 | 是 | 与代码一起 | 与代码一起 |
| 范围 | 项目特定 | 用户或项目 | 代码会话 | 代码会话 |
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);
}