官方文件沒寫的，才是 AI 開發的真正規格
開發 AI 工具，你是否也曾困惑為何模型行為與文件描述大相徑庭？這篇文章將揭露，官方文件僅是冰山一角。真正的 AI 規格，藏在每一次的實測與失敗紀錄中。深入了解如何透過「經驗規格」的建立，將不確定性轉化為可預測性，打造穩定可靠的 AI 應用，避開那些文件從未提及的隱藏陷阱。
開發 AI 工具時，單純依賴官方文件遠遠不足，因為許多關鍵的系統行為與限制，文件上從未提及。真正的挑戰與價值，在於透過系統性的實測、失敗紀錄與版本比較，建立一套獨特的「經驗規格」（empirical specification）。這不僅是避開陷阱的關鍵，更是打造穩定、可預測 AI 應用的核心工程方法。我們必須從 API 的「使用者」轉變為系統行為的「研究者」，將每一次的實驗數據，轉化為可操作的知識，才能在不斷演進的 AI 世界中，繪製出屬於自己的精確地圖。
這個體悟，源於一個具體的開發專案。近期，我參考了一篇日本開發者的實作，為 Anthropic 的程式碼輔助模型 Claude Code 打造了名為 sui-memory 的本地記憶體工具。目標很單純：讓模型能記憶整個專案脈絡，而非僅限於當前對話。然而，從設計到實作，大量官方文件與社群文章都未曾提及的「隱藏規格」浮現。這清楚表明，當代 AI 系統開發已無法單純依賴文檔，而更像是一門實驗科學。
為什麼官方文件與真實世界存在巨大落差？
傳統軟體開發中，API 文件通常是開發者與系統之間的契約，行為應當是明確且可預測的。但在大型語言模型（LLM）的世界裡，這份契約變得模糊不清。原因有三：
- 行為的湧現性（Emergent Behavior）：LLM 的許多能力並非來自於明確的程式碼指令，而是從龐大數據中學習到的湧現能力。這些能力很難被事前窮舉並寫入文件，其表現往往帶有機率性。
- 快速的版本迭代：模型與 API 的更新速度極快。例如，在我們測試的
Claude Code v2.1.4版本中觀察到的行為，可能在下一個版本就被微調或修正。文件更新的速度，往往跟不上模型的演化。 - 脈絡的複雜性：模型的反應高度依賴輸入的脈絡（context），包含提示詞（prompt）、對話歷史、甚至是格式的微小差異。這些變因的組合是天文數字，不可能在文件中完全涵蓋。
因此，當我們試圖在 Claude Code 上實作記憶體機制時，遇到的問題已非「bug」，而更像是探索一個未知系統的物理特性。官方文件像是地圖，但真正的地形，需要親自踏勘才能繪製出來。
如何透過實測，建立自己的經驗規格？
將「踩坑」的被動心態，轉化為主動建立「經驗規格」的工程方法，是提升開發效率與系統穩定性的關鍵。這意味著我們需要將每一次的意外、失敗與不一致，都視為一次數據採集。以 sui-memory 專案為例，我們發現了幾種僅能透過實驗得知的行為模式：
- Token 計算的隱藏成本：官方文件會提供 token 的基本定義，但實際運行時，特定字元組合或程式碼語法的 token 消耗可能超出預期。我們必須透過反覆測試，才能找出最經濟的資料表示方式，避免 context window 提早溢位。
- 指令遵循的機率性衰減：當提供的脈絡變得非常長（例如超過 50K tokens），即使仍在模型的官方限制內，它對系統提示（system prompt）中某些指令的遵循度會開始下降。這種衰減不是線性的，且難以預測，只能透過建立評估基準（benchmark）來監控。
- 格式敏感性與延遲：我們發現，傳遞給模型的檔案結構與格式，會顯著影響回應延遲。例如，將多個小型程式碼檔案合併為一個巨大的 JSON 物件，其處理時間可能遠高於將它們作為獨立文本區塊傳入。這種效能特性，在任何官方 API 文件中都找不到。
這些發現無法從任何地方「讀到」，只能「測出來」。建立經驗規格庫，意味著系統性地記錄這些觀察，包含輸入、輸出、模型版本、延遲、token 數等參數，並將其內化為團隊的開發準則。
我們必須從 API 的「使用者」，轉變為系統行為的「研究者」。每一次 API 呼叫都是一次實驗，每一次失敗都是一篇待發表的論文。
我們該如何將經驗規格，轉化為具體的開發實踐？
將這種研究精神制度化，才能真正發揮其價值。這不只是單一開發者的職責，而應成為團隊的基礎建設。具體做法可以包含：
首先，建立一個共享的「行為日誌」或內部知識庫。當團隊成員發現任何與文件不符或出乎意料的模型行為時，應立即記錄下來，並附上可重現的最小範例。這份日誌會成為比官方文件更寶貴的資產。
其次，將關鍵互動模式「測試案例化」。如同傳統軟體的單元測試，我們應該為那些依賴模型特定行為的功能撰寫自動化測試。例如，驗證模型在長脈絡下是否仍能準確提取關鍵資訊的測試。這有助於在模型版本更新時，快速捕捉行為變化，避免模型漂移（model drift）帶來的隱性破壞。
最後，擁抱實驗文化。在設計新功能時，應保留時間與資源進行小規模的 A/B 測試，探索不同提示策略或資料結構對模型表現的影響。正如Andrej Karpathy 所指出，與 LLM 的互動更像是與人溝通，需要不斷嘗試與調整。
總結來說，開發先進的 AI 工具，是一場在不斷變化的地圖上尋路的旅程。官方文件為我們指明了大致方向，但路徑上的每一塊石頭、每一條溪流，都需要我們親自去丈量與標記。這份由無數次實驗累積而成的經驗規格地圖，才是確保我們能夠安全、高效抵達終點的唯一保證。
延伸閱讀
- 原案例參考：Claude Codeにプロジェクト単位のローカル記憶を持たせるツールを実装して見えた知見
- Anthropic Claude 官方文件
- Wei, Jason, et al. "Emergent abilities of large language models." arXiv preprint arXiv:2206.07682 (2022).
我是江中喬，專注於 AI Agent Architecture、Memory Governance 與 Cognitive Diversity，持續研究如何打造能夠長期協作、可信任且可治理的 AI 系統。