90 秒總覽
Claude Code 的提示並非一整塊靜態文字，而是由多層控制面組成的架構。最外層是系統提示組裝（system prompt assembly），定義基線行為與動態注入區段；中間層包含工具提示、技能指令與記憶注入，各自在特定時機觸發；最內層是側查詢（side-query）與子代理提示，執行高度聚焦的分析任務。整體共有 8 大提示家族，涵蓋從全域行為到單一工具的完整控制範圍。理解這套分層結構，才能在對的層級做對的調校，避免提示之間互相衝突。
執行路徑（主骨架）
當使用者輸入一個回合後，提示系統會按照以下路徑組裝並執行：
input: 使用者訊息
1. 組裝系統提示（靜態基線 + 動態注入）
2. 注入記憶與指令（CLAUDE.md、相關記憶篩選）
3. 送入主模型執行
4. 主模型依需求觸發：
a. 工具提示 → 工具呼叫
b. 側查詢 → 聚焦分析（分類、摘要、風險評估）
c. 技能/指令 → 多階段工作流程
d. 子代理 → 專責代理執行flowchart LR A[使用者回合] --> B[系統提示組裝] B --> C[主模型執行] C --> D[工具提示與工具呼叫] C --> E[側查詢：聚焦提示] C --> F[技能/指令提示擴展] C --> G[專責子代理]
每一個分支都有獨立的提示控制面，不會與系統提示混在一起。
8 大提示家族
flowchart TD P[提示系統] --> P1[系統提示組裝] P --> P2[記憶與指令注入] P --> P3[壓縮/摘要提示] P --> P4[建議與工作階段提示] P --> P5[工具行為提示] P --> P6[側查詢提示] P --> P7[指令與技能提示] P --> P8[代理特化提示]
路徑判讀重點
- 系統提示是所有下游提示品質的基礎，必須精確且無衝突。
- 工具提示在工具 schema 暴露與呼叫決策時執行，是操作護欄。
- 側查詢提示是任務專用的，精確度與輸出格式比創意更重要。
- 記憶注入在回合開始時執行，需篩選高訊號記憶避免雜訊。
關鍵決策（為什麼這樣設計）
決策 1：分層提示架構而非單一提示
原因：單一巨型提示會在不同職責之間產生衝突（例如安全規則與工具使用指引互相干擾），且難以局部更新。分層設計讓每一層各司其職：系統提示定義基線、工具提示嵌入護欄、側查詢提示聚焦單一任務。
代價：提示散佈在多個檔案中，需要清楚的命名慣例與文件說明才能追蹤。新增提示時必須確認不與其他層級衝突。
決策 2：靜態/動態分割策略
原因：系統提示使用 SYSTEM_PROMPT_DYNAMIC_BOUNDARY 將穩定指令文字（靜態區段）與會話/環境/功能開關相關內容（動態區段）分離。靜態區段可被 API 快取重複使用，大幅減少 token 消耗與延遲。
代價：開發者必須判斷新增內容屬於靜態或動態，分類錯誤會導致快取失效或指令過時。
決策 3：工具提示嵌入操作護欄
原因：工具提示不只描述功能，還明確編碼使用契約與禁止行為（例如「不得使用 AskUserQuestion 來要求計畫核准，應使用 ExitPlanMode」）。這讓模型在工具選擇階段就受到約束，而非事後修正。
代價：工具提示的文字量較大，每次工具 schema 暴露都會消耗額外 token。護欄措辭不夠強時容易被模型忽略。
替代方案與取捨
| 方案 | 優點 | 缺點 | 為何未採用/何時可採用 |
|---|---|---|---|
| 單一巨型提示（所有指令合併為一塊） | 簡單直覺，所有規則集中管理 | 職責衝突、難以局部更新、快取效率差 | 適合極簡應用；Claude Code 的複雜度已超過此方案上限 |
| 硬編碼注入（所有指令寫死在程式碼中） | 無需動態組裝邏輯，行為完全可預測 | 無法依環境/功能調整，每次修改需重新部署 | 適合行為固定的工具；Claude Code 需要依會話/環境動態調整 |
| 自由格式輸出（不強制輸出結構） | 模型回應更自然，不受格式約束 | 下游程式碼無法可靠解析，錯誤難以偵測 | 適合面向人類的對話；機器消費路徑必須使用結構化輸出 |
| 抽象指導語（「請謹慎行事」） | 撰寫簡單，適用範圍廣 | 模型解讀不一致，行為不可測試 | 適合低風險場景；高精度任務需要操作性語言（精確命令、判定標準） |
失敗路徑與防護
Failure 1：權限邊界模糊
症狀：提示在應該只做驗證的路徑上編輯了檔案，或在唯讀分析中觸發了寫入操作。
防護：在提示中明確使用「MUST NOT」約束與禁止工具清單，讓模型在決策階段就被限制，而非依賴事後檢查。
Failure 2：輸出格式鬆散
症狀：預期收到 JSON 或判定行（如 VERDICT: PASS|FAIL），模型卻回傳散文式回應，導致下游解析失敗。
防護：強制要求嚴格的 JSON schema 或精確的行格式，並在提示中加入輸出範例。在驗證、會話標題（由 SESSION_TITLE_PROMPT 產生的短標題）、記憶篩選等機器消費路徑上必須落實。
Failure 3：記憶選擇過於廣泛
症狀：記憶召回充滿低訊號雜訊，模型被不相關的歷史記憶干擾，導致回應品質下降。
防護：在記憶篩選提示中設定選擇性標準，明確接受空列表（「寧可不選，也不要選錯」），並限制召回數量上限。
Failure 4：工作流程分支混淆
症狀：模型透過錯誤的工具請求計畫核准（例如用 AskUserQuestion 取代 ExitPlanMode）。
防護：在工具提示中編碼明確的路由規則：「不得使用 X 來執行 Y」，讓模型在工具選擇時就被導正。
Failure 5：長工作階段摘要偏移
症狀：壓縮輸出遺漏了近期使用者意圖，模型在恢復時失去脈絡。
防護：使用「僅近期」變體提示，並要求結構化區段（如 <summary>）確保關鍵資訊不被省略。
實作驗證（你改完要怎麼確認）
合併前檢查
- 此提示是否掛載在明確命名的執行路徑上？
- 若輸出由程式碼消費，輸出格式是否為確定性格式（JSON / 判定行 / 結構化區段）？
- 禁止行為是否已明確寫出（MUST NOT / 禁止工具清單）？
- 已知的失敗模式是否已在提示文字中記載？
- 是否與其他層級已有的規則重複？
- 措辭是否足夠精簡以減少 token 膨脹？
合併後驗證
- 在真實流程中驗證觸發條件是否正確。
- 驗證輸出解析在成功與失敗案例上都能正常運作。
- 抽查提示中聲稱處理的邊界案例是否確實被覆蓋。
這份清單對應漸進式提示設計模板（Progressive Prompt Design Template）的六個層級：目標（Objective）→ 觸發與範圍（Trigger & Scope）→ 程序（Procedure）→ 輸出契約（Output Contract）→ 失敗控制（Failure Controls）→ 證據標準（Evidence Standard）。新增或改寫提示時，按此順序由淺入深逐層填寫。