先別急著查怎麼設定。先問一個更基本的問題：當你在終端機打一句話給 Claude，它按下 Enter 那一刻，腦袋裡到底裝了哪些字？

多數人以為就一層——我打的那句話。其實至少有三層，而且它們的地位天差地遠。搞懂這三層各在哪，你才會明白為什麼「每次都要重講一遍」這件事這麼煩，以及它其實有解。

拆開來看：一次對話，Claude 讀到的三層字

想像 Claude 是一個新報到的員工。它上工那天，手上會有三種東西。

第一種是員工手冊。這是公司印好、每個人都一樣、你上工前就塞進你腦子的東西——怎麼用公司的工具、講話要多正式、哪些事絕對不能做（安全規範）、現在人在哪個辦公室（工作目錄、環境資訊）。在 Claude 的世界裡，這本手冊就叫 system prompt。它是最底層、地位最高的一層，Claude 做任何判斷都以它為準。

第二種是你當面交代的話。「幫我加一個使用者資料的 React 元件」——這是 user message，是你這次要它做的事。

第三種比較特別，是貼在辦公桌上的專案便利貼。這就是 CLAUDE.md。這裡要先破除一個超多人搞錯的觀念：CLAUDE.md 的內容不是被寫進員工手冊的。官方文件講得很清楚，SDK 是把 CLAUDE.md 當成「專案脈絡」注入到對話裡，不是塞進 system prompt。換句話說，它比較像便利貼，不是手冊本身。這個區別等一下會變得很重要。

好，現在關鍵問題來了：你每天在對話裡碎念的那些話——「記得用 TypeScript」「Python 函式都給我加上 type hints」「回答簡短一點」——它們是第幾層？

第二層。你當面交代的話。這代表什麼？代表下一次對話，它全部忘光。你等於每天早上都要把同樣的叮嚀對這位員工再講一遍。煩的根源就在這：你一直在用「臨時交代」處理一件「應該寫進手冊」的事。

那就改手冊本身：四個 CLI 旗標

既然問題是「這些話該進手冊卻只停在便利貼」，解法就很直覺了——把它們寫進 system prompt。Claude Code 的 CLI 給了四個旗標來動這本手冊，官方文件說得很明確：這四個在互動模式和非互動模式都能用。

最常用、也最安全的是在手冊尾端加一頁：

1
claude --append-system-prompt "Always use TypeScript"

--append-system-prompt 做的事，就是把你的話接在預設手冊的最後面，一個字都不刪。內建的工具說明、安全規範、程式碼風格規則全部留著，你只是多補一條。九成的日常需求用這個就對了——想讓它永遠記得某個習慣，加一句話進去，收工。

如果你想更狠，直接把整本手冊換掉：

1
claude --system-prompt "You are a Python expert"

--system-prompt 是完全取代。注意「完全」兩個字，等一下會回來算這筆帳。手冊太長想寫成檔案管理？有對應的旗標：

1
claude --system-prompt-file ./custom-prompt.txt

--system-prompt-file 從檔案載入，一樣是取代預設。

第四個旗標最不起眼，但如果你在跑多人、多機器的自動化任務，它會幫你省錢。先賣個關子，等我們把 SDK 講完再回來拆它，因為它的價值要先懂 prompt cache 才看得出來。

在程式裡動手冊：SDK 的三個起點

換到用 Agent SDK 寫應用程式的場景，動手冊的方式更講究，因為你得自己決定一件 CLI 幫你決定好的事：要不要繼承 Claude Code 那本厚厚的原廠手冊。官方給了三個起點。

第一個起點：沿用原廠手冊。你明講「我要 Claude Code 的完整 system prompt」：

1
2
3
4
5
6
7
8
9
10
11
12
13
import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Add a new React component for user profiles",
  options: {
    systemPrompt: {
      type: "preset",
      preset: "claude_code" // 用 Claude Code 的完整系統提示
    }
  }
})) {
  // ...
}

Python 幾乎一樣，只是換成 snake_case：

1
2
3
4
5
6
7
8
9
10
11
12
from claude_agent_sdk import query, ClaudeAgentOptions

async for message in query(
    prompt="Add a new React component for user profiles",
    options=ClaudeAgentOptions(
        system_prompt={
            "type": "preset",
            "preset": "claude_code",
        },
    ),
):
    ...

第二個起點，也是實務上最推薦的：原廠手冊 + 你自己加的一頁。這就是 CLI 那個 --append-system-prompt 在程式裡的樣子——在 preset 物件裡塞一個 append：

1
2
3
4
5
systemPrompt: {
  type: "preset",
  preset: "claude_code",
  append: "Always include detailed docstrings and type hints in Python code."
}

工具說明、安全規範、程式碼慣例全部保留，你只在尾端疊加自訂指令。風險最低，這是官方也建議的預設選擇。

第三個起點：整本自己寫。直接丟一個字串進去：

1
2
3
4
5
6
7
8
9
10
11
custom_prompt = """You are a Python coding specialist.
Follow these guidelines:
- Write clean, well-documented code
- Use type hints for all functions
- Include comprehensive docstrings"""

async for message in query(
    prompt="Create a data processing pipeline",
    options=ClaudeAgentOptions(system_prompt=custom_prompt),
):
    ...

看起來很爽，完全掌控。但這裡藏著全篇最大的一顆地雷。

換整本手冊之前，先算這筆帳

回到剛才 CLI 那個「完全取代」，還有 SDK 這個「整本自己寫」。它們有個共同的、很容易被忽略的代價，官方比較表把它攤得清清楚楚。

當你完全取代 system prompt，你不只換掉了風格指示，你連內建的工具使用說明弄丟了、連內建的安全規範也一起弄丟了。用官方表格的原話：內建工具是 Lost (unless included)，安全規範是 Must be added。

翻成白話：你把新員工的員工手冊整本抽走、換成你手寫的一張紙，結果他不但不知道公司的安全守則，連怎麼用公司的影印機都不會了——因為那些說明本來也印在原廠手冊裡，被你一起丟了。

所以判斷很簡單，記住一個問句就好：我只是想多交代幾件事，還是我真的要一個完全不同的東西？

只是想多交代——用 append（preset + append 或 CLI 的 --append-system-prompt）。你保留所有原廠能力，只加自己的規則，這是絕大多數人該走的路。

真的要一個完全不同的 agent——它的身分、權限模型、任務類型都跟 Claude Code 不一樣，甚至根本不是寫程式的 agent——這時才用完全自訂字串。但你得心裡有數：工具指引、安全規範，全部得自己補回去。這不是設定，這是自己蓋一本新手冊。

那 CLAUDE.md 和 Output Styles 又是什麼位置

講到這你可能會問：那我平常寫的 CLAUDE.md、還有 Output Styles，跟這些又是什麼關係？這正是官方那張四手段比較表要回答的。用一句話各自定位：

CLAUDE.md 是跟著專案走的便利貼——存在 repo 裡、隨版控走、每個開這個專案的人都適用。它管的是「這個專案的規矩」（coding 標準、常用指令、架構脈絡）。它不動手冊，只貼便利貼，所以也不會影響手冊的快取。

Output Styles 是可以重複用的人格檔——存成 markdown 檔（~/.claude/output-styles/ 或專案的 .claude/output-styles/），CLI 和 SDK 都能套，換一個就換一種說話方式（code reviewer、資料科學家、DevOps 助手）。它跟 --append-system-prompt 的差別在「持久性」：Output Styles 存成檔案、跨專案可重用；append 是這次 session 用完就沒，下次得在程式碼裡再寫一遍。

把四個並排，選擇其實一點都不難：

  • 這個習慣只屬於某個專案、想隨 repo 傳給隊友 → 寫進 CLAUDE.md。
  • 這個人格想跨專案重複用、不想改程式碼 → 做成 Output Style。
  • 這次任務臨時要加幾條規則、寫在程式裡 → preset + append。
  • 要一個跟 Claude Code 完全不同的 agent → 完全自訂字串（記得補安全規範）。

那個省錢的旗標：讓不同人共用同一份快取

現在回來拆我們賣關子的第四個旗標，還有它在 SDK 裡的雙胞胎 excludeDynamicSections。

要懂它為什麼有用，得先知道一件事：那本原廠手冊裡，其實混了一些「每台機器都不一樣」的內容——你現在的工作目錄、是不是 git repo、作業系統版本、auto-memory 的路徑。這些東西會被排在你的 append 文字前面。

問題就出在這。prompt cache 的規則是「前面一模一樣才能重用」。只要你的工作目錄跟同事不同，手冊開頭就不一樣，快取就 miss，這次呼叫等於重新算一遍、重新付一次錢。你們明明在跑同一個任務，卻因為「我在 /home/me、他在 /home/you」這種小事，各燒各的 token。

excludeDynamicSections 解決的就是這件事。把它設成 true，這些「每台機器不同」的環境資訊會被搬到第一則 user message 去，手冊本身只剩下「靜態的原廠內容 + 你的 append」。於是不同使用者、不同機器、不同目錄，只要任務設定一樣，就能共用同一份快取：

1
2
3
4
5
6
system_prompt={
    "type": "preset",
    "preset": "claude_code",
    "append": "You operate Acme's internal triage workflow.",
    "exclude_dynamic_sections": True,
}

CLI 在非互動模式的對應寫法是這個旗標（通常搭 -p 跑腳本）：

1
claude -p --exclude-dynamic-system-prompt-sections "query"

有幾個前提要記住，這些都是官方文件白紙黑字寫的，不要自己腦補。它需要夠新的 SDK 版本——TypeScript 的 @anthropic-ai/claude-agent-sdk 要 v0.2.98 以上，Python 的 claude-agent-sdk 要 v0.1.58 以上。它只對 preset 物件形式生效，你要是傳純字串它就沒作用。而 CLI 那個旗標只在用預設手冊時有效，一旦你用了 --system-prompt 或 --system-prompt-file 把手冊換掉，它就被忽略。

也別忘了它的代價：環境資訊還是會傳給 Claude，只是從「地位最高的手冊」降到「地位次一等的 user message」。Claude 對「我現在在哪個目錄」的感知會稍微弱一點。所以這是個取捨——當「大家共用快取省錢」比「環境資訊最權威」更值錢時才開，不是無腦全開。

回到最開始那個新員工

繞了一圈，回到開頭那三層字。你會發現「怎麼客製 Claude」這個問題，其實從來不是在問「用哪個旗標」，而是在問一件更前面的事：我要交代的這件事，該寫在哪一層？

臨時的、這次才需要的——留在對話裡就好。屬於這個專案、要傳給隊友的——寫進 CLAUDE.md 那張便利貼。屬於你自己、跨專案的工作習慣——做成 Output Style。而那些「我希望它從第一秒就內建、每次都記得」的東西，才值得動到手冊本身，用 append 加一頁進去。真正需要撕掉整本手冊重寫的場合，其實很少，少到你每次想這樣做之前，都該先停下來問一句：我是不是只要加一頁就夠了？

挑一個你這禮拜對 Claude 講到膩的叮嚀，把它從你的嘴巴，搬進 --append-system-prompt 裡。你會發現，最好的交代，是那種你再也不用交代第二次的。

本文技術細節整理自 Claude Code 官方文件：Modifying system prompts（Agent SDK）、CLI reference。程式碼範例引自官方文件。