Claude Code Prompt Caching：長任務 Agent 的成本與延遲工程
Anthropic 這篇 Claude Code 工程筆記的重點很務實：長時間 agent 產品能不能跑得快、跑得久、又不把成本燒穿，關鍵不只是模型能力，而是 prompt cache hit rate。Claude Code 的 harness 從第一天就圍繞 prompt caching 設計，甚至把 cache hit rate 當成需要警示與處理的營運指標。
快取不是自動魔法，而是 prompt 排版問題
文章最重要的工程約束，是 prompt caching 以請求開頭的相同前綴作為命中基礎。因此 prompt 的順序非常關鍵：越穩定、越多人共用的內容越應該放在前面；越常變動、越接近使用者當下狀態的內容越應該放在後面。
對 Claude Code 來說，穩定系統提示與工具定義放在最前面，接著才是專案中的 CLAUDE.md、session context，最後才是一路成長的對話訊息。這個設計讓不同 session 仍有機會共享前綴快取，也讓同一個 session 的新回合只需要承擔尾端新增內容。
靜態在前，動態在後
時間戳、臨時狀態、工具輸出與使用者對話不要污染最前面的共享區塊。
工具順序要穩定
即使內容語義相同，非決定性的工具排序或參數變動，也可能讓快取前綴斷掉。
命中率要監控
快取命中率降低會直接影響成本、延遲與訂閱方案能提供的 rate limit。
不要用改 system prompt 或換工具清單來表達狀態
很多 agent 產品會直覺地在使用者進入不同模式時改 system prompt，或依當下需求移除不需要的工具。Anthropic 的經驗是，這會讓快取成本變得很高，因為 system prompt、工具 schema 與模型本身都屬於快取前綴的一部分。
Claude Code 的 Plan Mode 是很好的案例。比較直覺但傷快取的做法，是進入 plan mode 時只提供唯讀工具；實際設計則是保留同一組工具，把進入與離開 plan mode 做成工具事件，再用訊息告訴模型目前的行為限制。工具定義沒有變，cache prefix 也就保持穩定。
用訊息承載會變的資訊
日期、檔案變更、模式切換等更新，優先放進下一輪 user message 或工具結果中的系統提醒，而不是修改最前面的 prompt。
同一段長對話不要隨便換模型
快取和模型綁定。長 session 中途換成便宜模型，可能反而要重新建立大量快取，總成本不一定下降。
不要中途新增或移除工具
工具定義是前綴的一部分。用工具表達模式轉換，比實際替換工具集合更符合快取設計。
用 tool search 延後載入完整 schema
大量 MCP 工具可以先以穩定 stub 存在，真的需要時再透過搜尋載入完整定義，兼顧前綴穩定與 token 成本。
模型切換用 handoff，而不是硬切 session
需要不同模型時，可以讓原模型準備交接訊息，再由 subagent 處理局部任務，避免破壞主 session 的快取脈絡。
Context 快滿時，摘要也要沿用父對話的前綴
長任務 agent 早晚會遇到 context window 快滿的問題。文章提醒，最容易踩的成本陷阱，是另外開一個「只負責摘要」的請求，使用新的 system prompt、沒有工具，然後把整段對話丟進去。這個請求從第一個 token 就和主對話不同，因此幾乎吃不到既有快取。
Claude Code 的做法是 cache-safe fork：用和父對話相同的 system prompt、使用者上下文、系統上下文與工具定義，先重放父對話的訊息，再把 compaction prompt 作為最後的新 user message。這樣 API 看到的前綴幾乎和父 session 上一輪相同，只有壓縮指令本身是新 token。
容易失效的摘要方式
- 另外開一個不同 system prompt 的摘要請求。
- 移除工具定義，讓前綴從開頭就分岔。
- 長對話越長，未命中的輸入成本越高。
Cache-safe fork
- 沿用父 session 的 prompt、上下文與工具定義。
- 把 compaction 指令放在訊息尾端。
- 預留 compaction buffer，讓摘要輸入與輸出有足夠空間。
把 prompt caching 當成 agent harness 的設計介面
這篇文章值得反覆回看的地方，在於它把 prompt caching 從 API 最佳化，拉高成 agent 產品架構問題。只要你的系統會長時間對話、呼叫工具、切模式、壓縮上下文或啟動 subagents，就必須先設計快取邊界，否則每個功能都可能變成 cache break。
一句話總結
- 01長時間 agent 的 prompt 不是一包文字，而是一個要被快取、監控與保護的資料結構。
- 02穩定前綴、固定工具、固定模型與 cache-safe compaction，是讓 Claude Code 這類產品能大規模運作的基本工程條件。
- 03當功能設計和快取設計衝突時，通常應該重塑功能介面，而不是接受每輪 cache miss。