系統提示定義了 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 | 輸出樣式 | systemPrompt 附加 | 自訂 systemPrompt |
|---|---|---|---|---|
| 持久性 | 每個專案檔案 | 儲存為檔案 | 僅限會話 | 僅限會話 |
| 重複使用性 | 每個專案 | 跨專案 | 程式碼重複 | 程式碼重複 |
| 管理 | 在檔案系統 | CLI + 檔案 | 在程式碼中 | 在程式碼中 |
| 預設工具 | 保留 | 保留 | 保留 | 遺失(除非包含) |
| 內建安全性 | 維持 | 維持 | 維持 |
注意: "附加" 意指在 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);
}