系統提示定義了 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 系統提示的已儲存配置。它們以 markdown 檔案形式儲存，可以在會話和專案間重複使用。

​
建立輸出樣式

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)`
)

​
使用輸出樣式

建立後，可透過以下方式啟用輸出樣式：
  • CLI：/output-style [style-name]
  • 設定：.claude/settings.local.json
  • 建立新樣式：/output-style:new [description]

​
方法 2：使用 systemPrompt 附加模式

您可以使用 Claude Code 預設配置搭配 append 屬性來新增自訂指令，同時保留所有內建功能。 
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)
  }
}

​
方法 3：自訂系統提示

您可以提供自訂字串作為 systemPrompt，完全用您自己的指令替換預設設定。 
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)
  }
}

​
三種方法的比較

功能輸出樣式systemPrompt 附加模式自訂 systemPrompt
持久性✅ 儲存為檔案❌ 僅限會話❌ 僅限會話
可重複使用性✅ 跨專案使用❌ 程式碼重複❌ 程式碼重複
管理✅ CLI + 檔案⚠️ 在程式碼中⚠️ 在程式碼中
預設工具✅ 保留✅ 保留❌ 遺失（除非包含）
內建安全性✅ 維持✅ 維持❌ 必須新增
環境上下文✅ 自動✅ 自動❌ 必須提供
自訂程度⚠️ 替換預設⚠️ 僅新增✅ 完全控制
版本控制✅ 是✅ 與程式碼一起✅ 與程式碼一起
可發現性✅ /output-style❌ 不可發現❌ 不可發現
注意：「附加模式」指在 TypeScript 中使用 systemPrompt: { type: "preset", preset: "claude_code", append: "..." }，或在 Python 中使用 system_prompt={"type": "preset", "preset": "claude_code", "append": "..."}。

​
使用案例和最佳實踐

​
何時使用輸出樣式

最適合：
  • 跨會話的持久行為變更
  • 團隊共享配置
  • 專業助手（程式碼審查員、資料科學家、DevOps）
  • 需要版本控制的複雜提示修改
範例：
  • 建立專門的 SQL 最佳化助手
  • 建構專注於安全的程式碼審查員
  • 開發具有特定教學法的教學助手

​
何時使用 systemPrompt 附加模式

最適合：
  • 新增特定的程式碼標準或偏好
  • 自訂輸出格式
  • 新增領域特定知識
  • 修改回應詳細程度
  • 在不失去工具指令的情況下增強 Claude Code 的預設行為

​
何時使用自訂 systemPrompt

最適合：
  • 完全控制 Claude 的行為
  • 專門的單次會話任務
  • 測試新的提示策略
  • 不需要預設工具的情況
  • 建構具有獨特行為的專業代理

​
組合方法

您可以組合這些方法以獲得最大靈活性：

​
範例：輸出樣式搭配會話特定新增

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)
}

​
另請參閱