我翻了 300 筆 Agent 失敗日誌，問題從來不是 Prompt

三百筆 agent 失敗日誌。我花了兩個星期逐一翻閱，替每一筆標記根本原因。結果出乎我意料：prompt 問題大概只佔 12%，其餘的失敗，不是 context 遭到汙染、就是溢出，或是根本缺少必要資訊。換模型沒用，換工具也沒用，這個規律每次都成立。

我研究 context engineering 已經有一段時間了，所以當一個叫做 Agent Skills for Context Engineering 的開源專案出現、並快速突破 10,000 個 GitHub 星時，我馬上注意到它。這個專案採用 MIT 授權，作者是一位叫做 Muratcan Koylan 的 context engineer，而且已被北京大學 AI 實驗室的論文引用。最後這點讓我真的把它 clone 下來研究。

較小的 context window 反而更準確

我原本以為塞越多 token 進 context 就越好，結果我錯了。這個技能集教的第一個原則是「資訊密度，而非資訊量」。

隨著 context 越來越長，模型會開始遺忘中間的內容。這就是所謂的 U 形曲線效應：模型對開頭和結尾的掌握度高，中間的部分卻一帶而過。我自己做了測試，把 context 填到 128K token，再把相同的資訊壓縮到 32K。壓縮版在準確度上的表現反而更好。

處理成本並非隨 token 數量線性增長，而是指數級攀升。把 context 砍半，response 延遲縮短了 40 到 60%。就算有 prefix caching，長輸入依然昂貴。一句話總結：在固定的 token 預算內，能塞進多少有用的資訊，才是真正重要的事。

Tool 描述決定了 agent 80% 的表現

Prompt 寫得再完美，如果 tool 描述寫得很馬虎，agent 還是會選錯工具。這個技能集的說法很精準：「Tools 是給 LLM 讀的合約，不是給人看的。」我的團隊在建 MCP server 時，照著這份指南重寫了所有 tool 描述，工具選錯的情況明顯減少了。

每個 tool 描述都要說清楚：什麼時候用、會回傳什麼。當兩個工具功能重疊，人會搞混，agent 更會搞混。一個功能完整的工具，通常比好幾個功能細分的工具更管用。而且錯誤訊息要告訴 agent 下一步該怎麼做，不只是說哪裡出錯。

Multi-agent 系統要先有架構，再有 agent

隨便開幾個 agent、期待它們自動協作，只是一廂情願。這個 repo 清楚定義了三種模式：由 orchestrator 指揮下屬 agent、peer-to-peer 讓 agent 平等溝通，以及階層式的任務委派鏈。

我在 production 環境三種都試過，orchestrator 模式最可預測，也最容易 debug。下屬 agent 透過檔案系統傳遞結果。Peer-to-peer 模式在創意類任務表現較好，但有無限迴圈的風險。結構化查詢用共享檔案比向量搜尋更可靠。實際跑下來，我發現三個 agent 是穩定性的上限。

向量搜尋一個人撐不起 memory

向量搜尋可以輕鬆找到「客戶 X 在某日購買了產品 Y」，但它沒辦法回答「買了產品 Y 的客戶還買了什麼？」關聯性資訊在 embedding 過程中會流失。

這個技能集提出了四層記憶架構：context window 內的工作記憶、session 內的短期記憶、跨 session 的長期記憶，以及作為封存的永久記憶。其中最實用的是「以檔案系統作為 memory」這個模式。你用 ls 和 grep 來瀏覽 context，而不是下 embedding 查詢。把 tool 的執行結果丟進暫存檔，可以省下可觀的 context window 空間。

Evaluation 是最被低估的 agent 技能

這個章節我差點跳過，結果它是最有價值的一段。Repo 裡附了一套 TypeScript evaluation 框架，以 LLM 作為評審，還能自動產生評分標準。

最讓我印象深刻的是位置偏誤的處理方式。在比較兩個回答時，框架會把順序互換、評估兩次，藉此抵消「先出現的答案比較容易拿高分」的傾向。它同時支援直接評分和成對比較。有了 evaluation pipeline，我終於能實際量測 prompt 修改是否真的改善了表現，而不是靠直覺猜。

有一點這個 repo 沒有解決：評分標準還是需要人工校準。自動產生的標準給了合理的起點，但在我自己的領域裡，我必須調整評分權重，結果才變得可信。

當你的 agent 出錯時，先檢查 context，再去怪模型。Repo 在這裡。