Was this page helpful?
系統提示詞定義了 Claude 的行為、能力和回應風格。Claude Agent SDK 提供三種自訂系統提示詞的方式:使用輸出樣式(持久性、基於檔案的配置)、附加到 Claude Code 的提示詞,或使用完全自訂的提示詞。
系統提示詞是塑造 Claude 在整個對話中行為方式的初始指令集。
預設行為: Agent SDK 預設使用最小系統提示詞。它僅包含基本的工具指令,但省略了 Claude Code 的編碼指南、回應風格和專案上下文。要包含完整的 Claude Code 系統提示詞,請在 TypeScript 中指定 systemPrompt: { preset: "claude_code" },或在 Python 中指定 system_prompt={"type": "preset", "preset": "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,可以包含:
# Project Guidelines
## Code Style
- Use TypeScript strict mode
- Prefer functional components in React
- Always include JSDoc comments for public APIs
## Testing
- Run `npm test` before committing
- Maintain >80% code coverage
- Use jest for unit tests, playwright for E2E
## Commands
- Build: `npm run build`
- Dev server: `npm run dev`
- Type check: `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: "Add a new React component for user profiles",
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",
"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)`
);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);
}
}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);
}
}| 維持 |
| 必須自行添加 |
| 環境上下文 | 自動 | 自動 | 自動 | 必須自行提供 |
| 自訂程度 | 僅限添加 | 替換預設 | 僅限添加 | 完全控制 |
| 版本控制 | 隨專案 | 是 | 隨程式碼 | 隨程式碼 |
| 範圍 | 專案特定 | 使用者或專案 | 程式碼工作階段 | 程式碼工作階段 |
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);
}