理解系統提示
系統提示是塑造 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:使用 systemPrompt 附加
您可以使用 Claude Code 預設與 append 屬性來新增您的自訂指令,同時保留所有內建功能。
方法 4:自訂系統提示
您可以提供自訂字串作為systemPrompt,完全用您自己的指令替換預設值。
四種方法的比較
| 功能 | CLAUDE.md | 輸出樣式 | 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 最佳化助手
- 建立專注於安全性的程式碼審查員
- 開發具有特定教學法的教學助手
何時使用 systemPrompt 附加
最適合:
- 新增特定的編碼標準或偏好
- 自訂輸出格式
- 新增領域特定知識
- 修改回應詳細程度
- 在不失去工具指令的情況下增強 Claude Code 的預設行為
何時使用自訂 systemPrompt
最適合:
- 完全控制 Claude 的行為
- 專業的單一會話任務
- 測試新的提示策略
- 不需要預設工具的情況
- 建立具有獨特行為的專業代理
結合方法
您可以結合這些方法以獲得最大靈活性:範例:輸出樣式與會話特定新增
另請參閱
- 輸出樣式 - 完整的輸出樣式文件
- TypeScript SDK 指南 - 完整的 SDK 使用指南
- TypeScript SDK 參考 - 完整的 API 文件
- 配置指南 - 一般配置選項