理解系统提示词
系统提示词是塑造Claude在整个对话过程中行为的初始指令集。默认行为: Agent SDK默认使用空系统提示词以获得最大灵活性。要使用Claude Code的系统提示词(工具指令、代码指南等),请在TypeScript中指定
systemPrompt: { preset: "claude_code" }或在Python中指定system_prompt="claude_code"。- 工具使用指令和可用工具
- 代码风格和格式指南
- 响应语调和详细程度设置
- 安全和安全指令
- 关于当前工作目录和环境的上下文
修改方法
方法1:CLAUDE.md文件(项目级指令)
CLAUDE.md文件提供项目特定的上下文和指令,当Agent SDK在目录中运行时会自动读取。它们作为项目的持久”记忆”。CLAUDE.md如何与SDK配合工作
位置和发现:- 项目级: 工作目录中的
CLAUDE.md或.claude/CLAUDE.md - 用户级:
~/.claude/CLAUDE.md用于所有项目的全局指令
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示例
在SDK中使用CLAUDE.md
何时使用CLAUDE.md
最适合:- 团队共享上下文 - 每个人都应该遵循的指南
- 项目约定 - 编码标准、文件结构、命名模式
- 常用命令 - 特定于您项目的构建、测试、部署命令
- 长期记忆 - 应该在所有会话中持续存在的上下文
- 版本控制指令 - 提交到git以便团队保持同步
- ✅ 在项目的所有会话中持续存在
- ✅ 通过git与团队共享
- ✅ 自动发现(无需代码更改)
- ⚠️ 需要通过
settingSources加载设置
方法2:输出样式(持久配置)
输出样式是修改Claude系统提示词的保存配置。它们存储为markdown文件,可以在会话和项目之间重复使用。创建输出样式
使用输出样式
创建后,通过以下方式激活输出样式:- CLI:
/output-style [style-name] - 设置:
.claude/settings.local.json - 创建新的:
/output-style:new [description]
settingSources: ['user']或settingSources: ['project'](TypeScript)/setting_sources=["user"]或setting_sources=["project"](Python)时,输出样式会被加载。
方法3:使用带append的systemPrompt
您可以使用Claude Code预设和append属性来添加您的自定义指令,同时保留所有内置功能。
方法4:自定义系统提示词
您可以提供自定义字符串作为systemPrompt,用您自己的指令完全替换默认设置。
所有四种方法的比较
| 功能 | CLAUDE.md | 输出样式 | 带append的systemPrompt | 自定义systemPrompt |
|---|---|---|---|---|
| 持久性 | 每个项目文件 | 保存为文件 | 仅会话 | 仅会话 |
| 可重用性 | 每个项目 | 跨项目 | 代码重复 | 代码重复 |
| 管理 | 在文件系统上 | CLI + 文件 | 在代码中 | 在代码中 |
| 默认工具 | 保留 | 保留 | 保留 | 丢失(除非包含) |
| 内置安全性 | 维护 | 维护 | 维护 | 必须添加 |
| 环境上下文 | 自动 | 自动 | 自动 | 必须提供 |
| 自定义级别 | 仅添加 | 替换默认 | 仅添加 | 完全控制 |
| 版本控制 | 与项目一起 | 是 | 与代码一起 | 与代码一起 |
| 范围 | 项目特定 | 用户或项目 | 代码会话 | 代码会话 |
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/目录中”
settingSources: ['project'](TypeScript)或setting_sources=["project"](Python)。没有此设置,claude_code系统提示词预设不会自动加载CLAUDE.md。
何时使用输出样式
最适合:- 跨会话的持久行为更改
- 团队共享配置
- 专门的助手(代码审查员、数据科学家、DevOps)
- 需要版本控制的复杂提示词修改
- 创建专门的SQL优化助手
- 构建专注于安全的代码审查员
- 开发具有特定教学法的教学助手
何时使用带append的systemPrompt
最适合:
- 添加特定的编码标准或偏好
- 自定义输出格式
- 添加领域特定知识
- 修改响应详细程度
- 在不丢失工具指令的情况下增强Claude Code的默认行为
何时使用自定义systemPrompt
最适合:
- 完全控制Claude的行为
- 专门的单会话任务
- 测试新的提示词策略
- 不需要默认工具的情况
- 构建具有独特行为的专门代理
组合方法
您可以组合这些方法以获得最大的灵活性:示例:带会话特定添加的输出样式
另请参阅
- 输出样式 - 完整的输出样式文档
- TypeScript SDK指南 - 完整的SDK使用指南
- TypeScript SDK参考 - 完整的API文档
- 配置指南 - 通用配置选项