撰寫 AI Agent 系統提示詞完整指南 —— 逆向工程 Claude Code 的實戰心得

我反編譯了 Claude Code 的系統提示詞，研究了 DeepAgents 的原始碼，並從零打造了自己的 AI Agent。市面上多數的提示詞指南，說穿了都只是憑感覺的「玄學」。

現在的 AI 圈正陷入一場集體幻覺。

每一篇教學都在教你怎麼寫系統提示詞（System Prompts），搞得像在念咒語一樣——彷彿只要找到正確的咒文，模型就會乖乖聽話。「你是一位『極度優秀』的資深工程師，擁有 20 年的經驗...」聽起來很耳熟對吧？

過去幾個月，我一直在打造 VibeCom（一個能進行深度市場研究並產出創投等級分析的 AI 新創顧問）。在這個過程中，我逆向工程了 Claude Code 的系統提示詞，翻閱了 DeepAgents 的中介軟體原始碼，並且燒掉了多到我不想承認的 API 額度。最大的體悟是什麼？大家認為系統提示詞裡最重要的東西，其實大多無關緊要。而真正關鍵的細節，卻幾乎沒人討論。

這篇文章是一份完整的實戰手冊——不是那種 5 分鐘的概覽，而是我在開始這一切之前，多希望有人能告訴我的所有心法。去倒杯咖啡吧，我們準備開始。

1. 設計哲學：信任模型

"An agent is a model. Not a framework. Not a prompt chain." （Agent 是一個模型。不是一個框架，也不是一串提示詞鏈。） — shareAI-lab/learn-claude-code

這個觀念改變了我的一切。LLM 已經知道如何推理、計畫和執行。你的系統提示詞不是在「教」它怎麼思考——而是在為它建立一個可以好好工作的環境。

把這想像成你在招募一位資深工程師。你不會給他們一份包含 20 個步驟的死板清單來完成每個任務。你會告訴他們：我們是誰、我們的邊界在哪裡、怎樣的成果才算優秀。然後，你就放手讓他們去做。

你的系統提示詞只有四個任務：

告訴它它是誰 — 角色與身份
告訴它牆在哪裡 — 安全限制與邊界
告訴它怎樣才算做得好 — 品質標準
給它工具 — 能力與知識

就這樣。其他的一切都是雜音。

Harness（控制框架）思維

Harness = 知識 + 工具 + 觀察 + 行動介面 + 權限

你的系統提示詞就是這個控制框架的操作手冊。你不是在設計一條僵化的流水線——你是在設計一個讓模型能自主發揮最佳表現的環境。

不要把系統提示詞寫得像流程圖。模型自己會決定執行的順序。

2. 提示詞結構與區塊順序

為什麼順序很重要？

LLM 有著「U 型注意力曲線」——它們對提示詞的開頭和結尾最為關注，而在中間部分容易恍神。這就是著名的「迷失在中間（Lost in the Middle）」效應，且已被廣泛證實。

身份與安全放在最上面：模型會優先建立角色和邊界（首因效應）。
核心工作流放在中上段：這是你最重要的區塊——定義 Agent 如何工作。
工具定義會在你的提示詞之後由系統注入：Claude Code 的工具定義吃掉了約 11,438 個 Token。這意味著你自訂的內容實際上會比你想像的更靠近開頭——這反而有助於模型遵守指示。
提醒事項放在最下面：利用近因效應（Recency bias）來強化關鍵規則。

3. 撰寫各個區塊

3.1 身份 (Identity) — 這個 Agent 是誰？

目標： 用 1-3 句話錨定模型的角色。

You are Claude Code, Anthropic's official CLI for Claude.
You are an interactive agent that helps users with software engineering tasks.

準則：

保持簡潔 — 最多 1-3 句話。
明確說出角色名稱（有助於模型區分不同的脈絡）。
說明核心職責（「協助處理 X」），而不是模糊的「你是一個有用的助手」。
如果適用，提及 SDK/平台（「建立在 Anthropic 的 Claude Agent SDK 之上」）。

避坑指南（Anti-patterns）：

「你是一個有用、無害且誠實的 AI 助手」——太過通用，沒有角色錨點。
寫了一整段的背景故事和世界觀——浪費 Token，模型不需要角色發展。

3.2 安全與防護 (Security & Safety) — 絕對邊界

目標： 設定不可打破的行為限制。

IMPORTANT: Assist with defensive security tasks only.
Refuse to create, modify, or improve code that may be used maliciously.
IMPORTANT: You must NEVER generate or guess URLs for the user.

準則：

使用 IMPORTANT: 前綴 — Claude 的指令層級訓練會給予這個前綴額外的權重。
使用絕對語氣：NEVER（絕不）、MUST NOT（禁止）、Refuse to（拒絕）。
同時說明允許做什麼「以及」禁止做什麼（雙向約束會更清晰）。
放在最頂端，不要埋在中間。
在結尾重複關鍵的安全規則 — Claude Code 就是這麼做的。

為什麼要重複？ 首因效應（開頭）+ 近因效應（結尾）= 雙重強化。Claude Code 的安全聲明在提示詞的開頭和結尾都有出現。這不是因為工程師健忘——而是因為他們深諳 U 型注意力曲線的道理。

3.3 語氣與風格 (Tone & Style) — 控制輸出

目標： 控制輸出格式與口吻。

## Tone and style

- Your responses should be short and concise.
- Only use emojis if the user explicitly requests it.
- Use Github-flavored markdown for formatting.
- NEVER create files unless absolutely necessary.

準則：

列出具體的行為，而不是模糊的「保持專業」。
每條規則都應該是可以用 True/False 來測試的（「簡短扼要」vs.「盡量簡短」）。
包含輸出格式要求（Markdown？JSON？純文字？）。
包含「不要做什麼」——許多風格問題其實是需要禁止某些行為。

Claude Code 的神來之筆 — 專業客觀性：

Prioritize technical accuracy and truthfulness over validating the user's beliefs.
Focus on facts and problem-solving, providing direct, objective technical info
without any unnecessary superlatives, praise, or emotional validation.

這段話至關重要：它阻斷了模型的「迎合傾向」（Sycophancy）。如果你的 Agent 需要給出客觀的判斷（程式碼審查、點子評估、架構決策），你絕對需要加上類似的條款。

3.4 核心工作流 (Core Workflow) — 最重要的一個區塊

目標： 教導模型如何工作——給予方法論，而不是死板的程序。

這是最難寫好的一個區塊，但一旦寫對了，影響力也最大。

核心原則：給予原則，而不是死板的程序。

告訴 LLM 好的輸出長什麼樣子，以及為什麼它很好——讓它自己想辦法達成。避免規定確切的欄位數量、步驟順序或格式，除非這些輸出是要給下游的機器讀取的。

Claude Code 的做法：

## Doing tasks

The user will primarily request software engineering tasks.
For these tasks the following steps are recommended:

- Use the TodoWrite tool to plan the task if required

注意 "recommended"（建議）這個詞——而不是「你必須嚴格遵循這些步驟」。這個單字給了模型適應不同情況的空間。

一個好的工作流定義：

1. 先理解 — 在修改之前先閱讀現有的程式碼
2. 先計畫 — 在執行之前將複雜的任務拆解成多個步驟
3. 最小化改動 — 只修改必要的部分，不要「順便重構」
4. 驗證 — 確認你的改動有效（執行測試、lint 等）

每條規則都有一個隱含的「為什麼」——模型能理解背後的意圖，並將其泛化到新的情境中。

避坑指南：

僵化的 20 步程序——模型會機械化地執行，並在遇到預期外的輸入時卡死。
「先做 A，再做 B，然後做 C」——那是一串提示詞鏈，不是 Agent 提示詞。
過度指導 LLM 已經很擅長的事情——浪費 Token。

這是我在開發 VibeCom 時痛定思痛學到的教訓。早期的版本有一個 10 步驟的研究工作流。即使步驟 3 已經回答了使用者的問題，模型還是會盡責地執行完所有 10 個步驟。當我切換到原則導向（「持續研究直到你有足夠的證據，然後進行綜合分析」）時，品質提升了，Token 成本也下降了。

例外情況： 當輸出是要給下游機器讀取時（Agent 間的通訊、API 回應格式），你應該定義嚴格的格式。原則是用來規範行為的；Schema 是用來定義介面的。

3.5 工具使用策略 (Tool Usage Policy) — 消除歧義

目標： 當多個工具可以做到同一件事時，告訴模型該優先使用哪一個。

## Tool usage policy

- Use specialized tools instead of bash commands:
  - Read for reading files instead of cat/head/tail
  - Edit for editing instead of sed/awk
  - Grep for searching instead of grep/rg
- You can call multiple tools in a single response. If independent, call in parallel.
- Use the Task tool for file search to reduce context usage.

準則：

使用 "instead of" 來表達優先順序（用 A 代替 B）。
解釋為什麼要偏好某些工具（「提供更好的使用者體驗」、「減少脈絡使用量」）。
定義平行處理策略（獨立任務 → 平行呼叫，相依任務 → 循序呼叫）。
列出工具使用的安全限制（路徑驗證、權限檢查）。

工具與提示詞之間的關鍵關係：

工具定義通常是由系統注入的，你無法直接編輯。Claude Code 的工具定義大約有 11,438 個 Token。這意味著：

不要重複已經寫在工具定義裡的資訊。
使用系統提示詞來提供策略性的指導：何時使用哪個工具、為什麼偏好某個工具、優先順序是什麼。
工具定義的品質直接影響 Agent 的效能——如果你在打造自己的 Agent，請花時間寫出優秀的工具描述。

3.6 領域知識 (Domain Knowledge) — 隨需載入，而非預先載入

目標： 提供模型訓練資料中可能缺乏的專業知識。

關鍵原則：漸進式揭露，而不是知識大傾倒。

❌ 把 200 個 API 端點全部貼到系統提示詞裡 → Token 爆炸
✅ 給模型一個查詢工具 → 「需要時再去載入知識」

這個策略在 Claude Code 的 Skills 系統和 DeepAgents 的漸進式揭露（Progressive Disclosure）中介軟體中都有被使用。兩者都是透過工具呼叫來隨需載入知識，而不是一開始就把所有東西塞進去。

實作方法：

在系統提示詞中放置指標：「需要時，使用 get_api_docs 工具來獲取文件」。
使用 CLAUDE.md / AGENTS.md 來提供專案脈絡 — 在執行時期載入，而不是寫死在程式裡。
使用 Skills / SKILL.md 來探索能力 — 模型會看到一個可用技能的選單，並在需要時抓取完整的規格說明。

3.7 環境資訊 (Environment Info) — 執行時期脈絡

目標： 讓模型意識到它所處的執行環境。

<env>
Working directory: /Users/fengliu/Desktop/tfm/vibecom
Is directory a git repo: true
Platform: darwin
Today's date: 2026-03-21
</env>
You are powered by the model named Claude Opus 4.6.

準則：

動態產生，絕對不要寫死。
包含：工作目錄、作業系統平台、日期、模型名稱、Git 狀態。
使用結構化格式（XML 標籤或程式碼區塊）以便於解析。
日期很重要——模型需要知道「現在」是什麼時候，才能判斷資訊的新舊。

3.8 提醒事項 (Reminders) — 最後的強化

目標： 在提示詞的最後重申最關鍵的規則。

Claude Code 在最底部重複了它的安全限制和 TodoWrite 要求：

IMPORTANT: Assist with defensive security tasks only. [重複]
IMPORTANT: Always use the TodoWrite tool to plan and track tasks. [重複]

準則：

只重複 2-3 條最關鍵的規則——不要把所有東西都複製一遍。
利用近因效應——模型對最近看到的內容記憶最深刻。
最佳候選：安全限制、最常被違反的規則、核心工作流提醒。

4. Token 預算與脈絡管理

預算分配參考

區塊	建議 Token 數	備註
身份與安全	200-500	簡潔但不可妥協
語氣與風格	300-800	規則必須具體，但不要囉嗦
核心工作流	500-2,000	最重要的區塊，值得投資
工具使用策略	300-1,000	取決於工具的數量
領域知識	0-1,000	偏好隨需載入
環境資訊	100-300	動態產生
提醒事項	100-300	只重複最核心的內容
你的總計	1,500-6,000
工具定義（系統注入）	5,000-15,000	不在你的控制範圍內

脈絡退化曲線 (Context Degradation Curve)

社群測試（Reddit u/CodeMonke_）描繪出了真實世界中的遵循度退化情況：

< 80K tokens：提示詞遵循度保持穩定。
80K - 120K tokens：指令遵循度開始下降。
> 120K tokens：顯著退化——模型會「忘記」早期的指令。
> 180K tokens：嚴重退化。

你的 200K 脈絡視窗 ≠ 200K 的「有效」脈絡。 請據此做好規劃。

緩解策略：

保持你的系統提示詞精簡（你負責的部分 < 6,000 tokens）。
使用摘要技術來壓縮對話歷史（DeepAgents 在約 80K 字元時觸發）。
將關鍵規則放在提示詞的兩端（U 型注意力曲線）。
在對話中途注入 <system-reminder> 標籤（詳見第 8 節）。

5. 寫作原則

5.1 給予原則，而不是程序

❌ "Step 1: Read the file. Step 2: Find the bug. Step 3: Fix it. Step 4: Run tests."
✅ "Always understand existing code before modifying it. Verify your changes work."

原則可以泛化。程序只能被機械化地遵循。當模型遇到你沒有預料到的情況時，原則能引導它做出正確的決定，但程序不行。

例外： 當輸出是給機器讀取時（Agent 間通訊、API 格式），請定義嚴格的 Schema。

5.2 對硬性限制使用絕對語氣

強度	語氣用詞	適用情境
絕對禁止	`NEVER`, `MUST NOT`	安全性、不可逆的操作
強烈要求	`ALWAYS`, `MUST`	核心工作流規則
建議	`recommended`, `prefer`	帶有例外的最佳實踐
提議	`consider`, `you may`	選擇性的最佳化

Claude Code 範例：

NEVER update the git config — 絕對禁止。
ALWAYS prefer editing an existing file — 強烈要求，但允許例外。
The following steps are recommended — 建議的工作流。

5.3 用範例代替解釋

## Code References

When referencing specific functions or pieces of code include
the pattern `file_path:line_number`.

<example>
user: Where are errors from the client handled?
assistant: Clients are marked as failed in the `connectToServer`
function in src/services/process.ts:712.
</example>

一個範例勝過 100 個字的解釋：

模型從範例中學習模式的可靠度，遠高於從抽象描述中學習。
用 <example> 標籤包裝，將其與規則分開。
同時提供正面（「這樣做」）和負面（「不要這樣做」）的範例。
使用真實、具體的範例——不要用 "foo/bar" 這種佔位符。

5.4 雙向約束

✅ "Use dedicated tools: Read for reading files, Edit for editing files."
✅ "Do NOT use bash for file operations (cat, head, tail, sed, awk)."

只說「這樣做」 → 模型不知道什麼時候「不該」這樣做。只說「不要這樣做」 → 模型不知道替代方案是什麼。雙向約束 → 清晰且毫無歧義。

5.5 解釋為什麼，而不只是做什麼

❌ "Don't use git commit --amend."
✅ "Avoid git commit --amend. ONLY use --amend when either
   (1) user explicitly requested amend OR
   (2) adding edits from pre-commit hook.
   Reason: amending may overwrite others' commits."

解釋為什麼，能讓模型在邊緣情況下做出正確的判斷。Claude Code 的 Git 安全協議堪稱大師級——每一條規則都暗示了其背後的理由。

5.6 結構勝於散文

Markdown 標題 (##, ###) — 模型能識別層級結構。
條列式清單優於段落 — 每一條規則都可以獨立測試。
XML 標籤用於特殊內容：<example>, <env>, <system-reminder>。
表格用於比較和映射。
絕對不要傾倒非結構化的文字——在遵循度測試中，結構化的提示詞表現始終優於自然語言散文。

6. 浪費 Token 的避坑指南

披著 Agent 外皮的提示詞鏈

"First call tool A to get data.
Then call tool B with the result.
Then format the output as JSON.
Then save to file."

這不是 Agent 提示詞——這是一個腳本流水線。模型會機械化地執行，並失去其自主規劃的能力。

解法： 告訴模型目標和限制。讓它自己決定步驟。

拍馬屁工程 (Flattery Engineering)

"You are an EXTREMELY TALENTED and INCREDIBLY EXPERIENCED
senior software engineer with 20 years of experience..."

讚美和最高級形容詞不會提高輸出品質。模型沒有自我意識需要你去吹捧。把這 15 個 Token 省下來寫一條真正的規則吧。

知識大傾倒

"Here is the complete API documentation for our 200 endpoints..."

這會吞噬你的脈絡視窗，並加速脈絡腐敗。請替換為隨需載入：

"Use the get_api_docs tool to retrieve API documentation when needed."

重複工具描述

如果工具定義已經寫了「Read 工具會從檔案系統讀取檔案」，就不要在系統提示詞裡再說一次。只添加工具定義中沒有涵蓋的策略性指導——何時使用它、為什麼偏好它、優先順序為何。

缺乏失敗處理機制

如果沒有明確的指導，模型會在工具呼叫失敗時陷入無限重試的迴圈。請務必加上：

"If a tool call is denied, do not re-attempt the exact same call.
Think about why it was denied and adjust your approach."

忽視脈絡視窗的衰退

200K 脈絡視窗 ≠ 200K 的有效脈絡。真實世界的測試顯示，退化大約從 80K 開始。你需要一個摘要策略。

7. 注入點與優先順序

Claude Code 的三種客製化方法

方法	替換內容	放置位置	最適合用於
Output Styles	「Tone and style」+「Doing tasks」區塊	就在工具定義之前	改變互動風格
--append-system-prompt	無（附加性質）	在 Output style 之後，工具定義之前	新增特定行為
--system-prompt	整個系統提示詞	保留工具定義 + 一行身份宣告	完全客製化（核彈級選項）

如果你同時使用多個：Output Style → Append Prompt → Tool Definitions

指令層級 (Instruction Hierarchy)

Claude 在訓練時特別加入了指令層級的概念：

1. 使用者的明確指令 (CLAUDE.md, 直接請求)  ← 最高優先級
2. 自訂的系統提示詞附加內容                   ← 高
3. 預設的系統提示詞                           ← 中
4. 工具定義                                   ← 參考層級

這意味著：

CLAUDE.md 的規則會覆蓋預設的系統提示詞行為。
使用者的直接請求會覆蓋一切。
你的自訂提示詞會覆蓋預設提示詞。

動態注入機制

<system-reminder> — 在對話中途注入到任何訊息中，提醒模型關鍵規則。
CLAUDE.md / AGENTS.md — 在執行時期從檔案載入，附加到系統提示詞中。
Skills / SKILL.md — 透過工具呼叫隨需載入，零系統提示詞負擔。

8. 對話中途注入 —— 秘密武器

系統提示詞只會出現一次，就在訊息陣列（Messages array）的最開頭。但 LLM 接受的是完整的訊息陣列（交替的使用者 / 助手 / 工具訊息）作為輸入，而你也可以將提示詞注入到使用者訊息和工具結果中。 Claude Code 在正式環境中大量使用了這個技巧。

為什麼這很必要？

對抗脈絡腐敗 (Context rot)。 隨著對話變長，模型對系統提示詞指令的遵循度會下降（在 80K+ tokens 時會很明顯）。在對話中途注入提醒 = 利用近因效應來刷新規則。

心智模型：

系統提示詞 = 憲法（建立一次，具有長期權威性）
使用者訊息提醒 = 備忘錄（定期發送，維持執行力）

訊息陣列中的三個注入點

Messages Array:
┌─────────────────────────────────────┐
│ System Prompt (系統提示詞)           │ ← 只出現一次，首因效應
│   (身份, 安全, 工作流...)             │
├─────────────────────────────────────┤
│ User Message 1                      │
│ Assistant Message 1                 │
│ User Message 2 + <system-reminder>  │ ← 對話中途注入
│ Assistant Message 2                 │
│ Tool Result + <system-reminder>     │ ← 也可以注入到工具結果中
│ ...                                 │
│ User Message N + <system-reminder>  │ ← 最新訊息，最強的近因效應
└─────────────────────────────────────┘

位置	優點	缺點
系統提示詞	首因效應，最先讀取	只出現一次，在長對話中容易被「遺忘」
使用者訊息注入	近因效應，定期刷新	每次注入都會消耗 Token
工具結果注入	最自然的注入點	只有在呼叫工具時才能運作

Claude Code 實際上是如何使用的

先決條件 — 在系統提示詞中宣告標籤：

Tool results and user messages may include <system-reminder> tags.
<system-reminder> tags contain useful information and reminders.
They are automatically added by the system, and bear no direct
relation to the specific tool results or user messages in which they appear.

這個步驟很關鍵：它告訴模型這些標籤是系統注入的，而不是使用者說的話。

用法 1：行為提醒（定期刷新規則）

<system-reminder>
The task tools haven't been used recently. If you're working on tasks
that would benefit from tracking progress, consider using TaskCreate...
</system-reminder>

Claude Code 用這個來提醒模型使用 TodoWrite 進行計畫——因為模型常常會「忘記」計畫，直接開始寫程式碼。

用法 2：模式切換（計畫模式）

<system-reminder>
Plan mode is active. The user indicated that they do not want you to
execute yet -- you MUST NOT make any edits, run any non-readonly tools,
or otherwise make any changes to the system.
</system-reminder>

計畫模式（Plan mode）並沒有實作在系統提示詞中。它是一個注入到下一個使用者訊息中的標籤。這讓你可以動態切換模式，而無需修改系統提示詞。非常聰明。

用法 3：檔案變更通知

<system-reminder>
Note: /path/to/file.ts was modified, either by the user or by a linter.
This change was intentional, so make sure to take it into account.
</system-reminder>

當外部程序（Linter、Formatter、手動編輯）修改了檔案時，系統會透過提醒通知模型——防止它基於過時的檔案內容做出決策。

用法 4：動態脈絡（日期、專案規則）

<system-reminder>
Today's date is 2026-03-21.
Current branch: dev
claudeMd: [CLAUDE.md content injected here]
</system-reminder>

執行時期脈絡（日期、Git 狀態、專案規則）是透過使用者訊息注入的，而不是寫死在系統提示詞中。

提醒事項的寫作準則

用 XML 標籤包裝 (<system-reminder>) — 讓模型能區分系統注入和使用者發言。
在系統提示詞中預先宣告標籤 — 否則模型可能會試圖回覆這個提醒。
不要在每條訊息中都注入 — 每次注入都會消耗 Token，只在需要時注入。
保持簡短 — 提醒不是第二個系統提示詞，只需 1-2 條關鍵規則即可。
不要與系統提示詞矛盾 — 提醒是補充和強化的作用，不是用來覆蓋的。
用於動態切換 — 計畫模式、唯讀模式、功能開關（Feature flags）。

何時使用系統提示詞 vs. 使用者訊息提醒

情境	系統提示詞	使用者訊息提醒
角色定義	✅	❌
安全限制	✅ 首次宣告	✅ 定期重複
工作流方法論	✅	❌
模式切換（計畫模式）	❌	✅
檔案變更通知	❌	✅
日期 / 環境資訊	✅ 初始值	✅ 更新值
行為糾正	❌	✅
工具使用提醒	✅ 規則定義	✅ 執行推力 (Nudges)

9. 提示詞快取 (Prompt Cache) — 節省 90% 的重複 Token 成本

Anthropic 的提示詞快取允許你快取訊息陣列的靜態前綴。當後續的請求共享相同的前綴時，就會命中快取——既省錢又降低延遲。

對於 Agent 來說，這非常重要：因為你在同一個對話中的每一次 LLM 呼叫，都在重複發送系統提示詞 + 工具定義。

關鍵數字

指標	數值
快取命中成本	正常價格的 10%（節省 90%）
快取寫入成本	正常價格的 125%（首次寫入需付 25% 溢價）
存活時間 (TTL)	5 分鐘（若無請求則過期）
最小可快取長度	1,024 tokens (Claude 3.5+)
快取粒度	前綴比對 — 從開頭到標記的中斷點 (Breakpoint)
最大中斷點數量	4

這如何改變提示詞設計

核心原則：靜態內容放前面，動態內容放最後。

✅ 對快取友善的配置：
  系統提示詞 (靜態)            ← 快取中斷點 1
  工具定義 (靜態)              ← 快取中斷點 2
  CLAUDE.md / 專案規則         ← 快取中斷點 3 (偶爾變動)
  對話歷史                     ← 快取中斷點 4 (滾動視窗)

❌ 破壞快取的配置：
  系統提示詞
  動態時間戳記                 ← 每次請求都會變，後面的內容全部 = 快取未命中
  工具定義
  對話歷史

沒人警告過你的陷阱： 如果你在系統提示詞中間放了一個動態時間戳記，它後面的所有東西都會變成快取未命中（Cache miss）。每。一。次。請。求。都是如此。只要一個時間戳記放錯位置，你就要為數千個 Token 支付全額費用。

API 使用方式

const response = await anthropic.messages.create({
  model: "claude-sonnet-4-6",
  system: [
    {
      type: "text",
      text: "You are a startup advisor...",
      cache_control: { type: "ephemeral" }  // ← 標記一個快取中斷點
    }
  ],
  messages: [...]
});

多重中斷點策略

中斷點 1: 系統提示詞           ← 幾乎不變
中斷點 2: 工具定義             ← 幾乎不變
中斷點 3: 專案規則 / CLAUDE.md ← 偶爾變動
中斷點 4: 前 N 條歷史訊息      ← 滾動視窗快取

即使對話歷史發生變化，前 3 個中斷點依然會命中。一個 10 輪的對話大約可以節省 40-60% 的輸入 Token 成本。

設計建議

系統提示詞中不要有高頻變動的動態值 — 日期可以（每天才變一次），精確的時間戳記絕對不行。
將動態脈絡（Git 狀態等）放在使用者訊息注入中 — 不要放在系統提示詞裡，否則會破壞快取。
保持工具定義穩定 — 不要在執行時期動態新增/移除工具。
對對話歷史使用滾動視窗 — 快取前 N 條訊息，只有最新的訊息會是快取未命中。

10. 檢查清單

寫完系統提示詞後，請用這份清單檢查一遍：

結構

身份定義是否放在最頂端？
安全限制是否標記了 IMPORTANT 並在結尾重複？
是否使用標題清晰地分隔區塊？
範例是否用 <example> 標籤包裝？

Token 預算

你負責的部分是否 < 6,000 tokens？
是否沒有重複工具定義中已有的資訊？
領域知識是否隨需載入，而非預先載入？
是否沒有冗長的世界觀或角色背景故事？

規則品質

每條規則是否都能用 True/False 來測試？
硬性限制是否使用了絕對語氣（NEVER/MUST）？
軟性建議是否使用了建議語氣（recommended/prefer）？
關鍵規則是否解釋了為什麼，而不只是做什麼？
是否有雙向約束（這樣做 + 不要那樣做）？

Agent 行為

是否給予了原則，而不是僵化的循序步驟？
是否處理了「工具呼叫被拒絕」的情境？
是否處理了「遇到障礙」的策略（不要暴力重試）？
是否有脈絡管理策略（摘要閾值）？

絕對不要做的事

沒有拍馬屁或使用最高級形容詞？
沒有多餘的「你是一個有用的 AI」宣告？
不是寫成提示詞鏈的形式？
沒有過度工程（加了一堆沒人要的功能）？

如果我今天重新開始

這是我會採取的確切做法：

在前 3 行寫下身份 + 安全限制。 用兩句話說明 Agent 是誰。用 NEVER/MUST 設定硬性限制。在結尾重複安全規則。
將核心工作流寫成原則，而不是步驟。 最多 4-5 個條列項目。對軟性規則使用 "recommended" 和 "prefer"，對硬性規則使用 "NEVER" 和 "MUST"。
為你負責的部分編列 1,500-6,000 tokens 的預算。 工具定義會再增加 5,000-15,000 tokens。如果你超過了 6K，你可能是在傾倒那些應該隨需載入的知識。
結構化一切。 Markdown 標題、條列式清單、用 XML 標籤包裝範例。結構化的提示詞表現永遠勝過自然語言散文。
從第一天起就內建對話中途提醒機制。 在系統提示詞中宣告 <system-reminder>。為關鍵規則、模式切換和脈絡更新注入提醒。
為快取而設計。 靜態內容放前面，動態內容放最後。絕對不要在系統提示詞主體中放入會變動的值。

做了這麼多研究，最諷刺的是什麼？最好的系統提示詞其實都很短。Claude Code 的自訂指令（不含工具定義）出奇地簡潔。每一行都有它存在的價值。

我以前以為提示詞工程（Prompt Engineering）是在找尋巧妙的技巧。現在我認為它是一種紀律——說得更少、說得更精確，然後信任模型會搞定剩下的事。模型比你的提示詞更聰明。你該設計的是環境，而不是行為。

參考資料

來源	關鍵洞察
Claude Code v2.0.14 System Prompt	完整的正式環境 Agent 提示詞結構參考
Reddit: Understanding Claude Code's 3 System Prompt Methods	Output Styles / --append / --system-prompt 深度解析，脈絡腐敗的真實世界數據
shareAI-lab/learn-claude-code	「模型就是 Agent」哲學，Harness（控制框架）工程方法論
Anthropic Prompt Engineering Docs	官方提示詞最佳實踐
DeepAgents Framework	摘要中介軟體，技能漸進式揭露

撰寫 AI Agent 系統提示詞完整指南 —— 逆向工程 Claude Code 的實戰心得

1. 設計哲學：信任模型

Harness（控制框架）思維

2. 提示詞結構與區塊順序

推薦的版面配置（從 Claude Code v2.0.14 逆向工程而來）

為什麼順序很重要？

3. 撰寫各個區塊

3.1 身份 (Identity) — 這個 Agent 是誰？

3.2 安全與防護 (Security & Safety) — 絕對邊界

3.3 語氣與風格 (Tone & Style) — 控制輸出

3.4 核心工作流 (Core Workflow) — 最重要的一個區塊

3.5 工具使用策略 (Tool Usage Policy) — 消除歧義

3.6 領域知識 (Domain Knowledge) — 隨需載入，而非預先載入

3.7 環境資訊 (Environment Info) — 執行時期脈絡

3.8 提醒事項 (Reminders) — 最後的強化

4. Token 預算與脈絡管理

預算分配參考

脈絡退化曲線 (Context Degradation Curve)

5. 寫作原則

5.1 給予原則，而不是程序

5.2 對硬性限制使用絕對語氣

5.3 用範例代替解釋

5.4 雙向約束

5.5 解釋為什麼，而不只是做什麼

5.6 結構勝於散文

6. 浪費 Token 的避坑指南

披著 Agent 外皮的提示詞鏈

拍馬屁工程 (Flattery Engineering)

知識大傾倒

重複工具描述

缺乏失敗處理機制

忽視脈絡視窗的衰退

7. 注入點與優先順序

Claude Code 的三種客製化方法

指令層級 (Instruction Hierarchy)

動態注入機制

8. 對話中途注入 —— 秘密武器

為什麼這很必要？

訊息陣列中的三個注入點

Claude Code 實際上是如何使用的

提醒事項的寫作準則

何時使用系統提示詞 vs. 使用者訊息提醒

9. 提示詞快取 (Prompt Cache) — 節省 90% 的重複 Token 成本

關鍵數字

這如何改變提示詞設計

API 使用方式

多重中斷點策略

設計建議

10. 檢查清單

結構

Token 預算

規則品質

Agent 行為

絕對不要做的事

如果我今天重新開始

參考資料