進階：Middleware、State、Observability

中級讓 agent「會做」，進階讓系統「可追、可修、可優化」。這一層的工作，本質上更接近 DevEx、Platform、SRE、QA 的混合體。

情境：你的 agent 上禮拜跑得很順，這禮拜開始亂掉

你的 AGENTS.md 已經寫了三個月。上禮拜的 solve rate 都還不錯。這禮拜突然發現：

有三個任務在同一個 tool 呼叫上卡住，錯誤訊息看起來不一樣但其實是同一個問題。
你想比較「用新版 prompt」vs「舊版 prompt」哪個成功率高，但你沒有數據。
你懷疑是 context window 溢出導致 agent 忘了規則，但你沒辦法證明。
你想回去看上禮拜那個成功案例到底做對了什麼，但trace 已經被蓋掉了。

這就是中級天花板的標準訊號：你會做 agent，但你開始追不上、修不動、優化不了。進階要解的就是這三個問題。

一、進階的三大主軸

主軸	核心問題	代表產物
Middleware	怎麼在 model 與 tool 之間插控制點	pre-tool hook、post-tool hook
State management	怎麼讓 agent 跨 session 不失憶	plans/、decision-log/、known-issues.md
Observability	怎麼從 trace 看出優化方向	task_id、tool_name、retry_count、token_cost

二、Middleware：在 model 與 tool 之間插控制點

Middleware 是 agent 系統裡最容易被低估的設計點。它是你在 model 呼叫 tool 的前後插入驗證、補 context、格式化結果的地方。

常見 hook 類型：

Hook 類型	插在哪裡	典型用途
Pre-task hook	任務開始前	補入任務模板、repo 規則、當前上下文
Pre-tool hook	tool 呼叫前	檢查權限、參數格式、危險操作
Post-tool hook	tool 執行後	驗證輸出、補錯誤訊息、轉結構化資料
Pre-completion hook	宣告完成前	比對 task spec、確認 done 定義
Failure hook	失敗發生時	累積失敗資料、決定 retry 或 escalation

一個實戰例子：pre-tool hook 攔截危險操作

當 agent 想執行 tool:shell 且命令包含 rm / drop / truncate / force / --no-verify:
  1. 不要執行
  2. 回 agent 一段結構化訊息：「此命令屬於 destructive 類別，請改為提出 approval request」
  3. 寫入 audit log

這種 hook 看似小，但它把一次「全自動災難」變成了一次「可見的 approval 請求」。2026 的真實事故裡，有非常大比例是缺少這種 hook 造成的。

Pre-task hook 的另一個關鍵用途

很多團隊會在 pre-task hook 做「上下文預熱」：

自動塞入目前的 AGENTS.md。
自動塞入最近 7 天的 known-issues.md。
自動塞入相關 decision-log/ 檔案。

這樣 agent 一開始就知道：哪些路踩過、為什麼這樣設計、哪些是最近的地雷。

三、State management：讓計畫變成一級工件

長任務（半小時以上、跨多步驟）最常見的失敗模式是 context window 滾動導致 agent 漂移 — 跑到第 30 輪時，它已經忘了第 1 輪談過什麼。

OpenAI 的 2026 實戰給了一個關鍵洞見：

Plans are treated as first-class artifacts. 計畫本身就是 agent 的工作介面，不只是人類用來開會的東西。

進階層常見的 state 結構：

plans/
├── active/
│   ├── 2026-04-05-orders-empty-cart.md
│   └── 2026-04-05-product-description-rewrite.md
├── completed/
│   └── 2026-04-04-checkout-retry.md
decision-log/
├── 2026-03-20-payment-provider-switch.md
└── 2026-03-28-idempotency-strategy.md
known-issues.md
tech-debt.md
artifacts/
└── trace-summary-2026-04-05.json

每個檔案都有明確的角色：

plans/active/ — 進行中的任務計畫，agent 每輪都會先讀這個。
plans/completed/ — 完成的任務工件，是未來任務的參考資料。
decision-log/ — 重大取捨與原因（為什麼不做 A，改做 B）。
known-issues.md — 已知地雷，避免 agent 重複踩。
tech-debt.md — 故意沒修的東西，防止 agent 自作聰明去修。
artifacts/ — 結構化的執行摘要、trace 快照。

重點：這些檔案跟 code 住在同一個 repo，版本化、可 diff、可 blame。這才是所謂「repo 作為 control plane」的實際長相。

四、Observability：沒有觀測，就沒有優化

這一句放到 agent 系統上依然成立。進階層至少要能收這些欄位：

欄位	用途
`task_id`	對應一次完整任務
`model`	比較不同模型表現
`tool_name`	看哪個工具最常出錯
`retry_count`	看哪裡容易卡住
`latency`	看哪裡太慢
`token_cost`	看成本
`error_type`	做錯誤分類
`completion_status`	成功、失敗、升級

LangChain 2026 把 trace analysis 直接做成一項 skill，就是因為優化 harness 靠的不是感覺，是 traces 與 failure pattern。

把失敗分型：不要只記「失敗了」

不要只記「這個任務失敗了」，要分成：

規則不清 — Rules 寫得模糊，agent 自由發揮。
Context 不足 — agent 沒拿到該拿到的檔案或歷史決策。
Tool 選錯 — agent 挑了錯的工具完成任務。
權限過寬或過窄 — 權限表設計有問題。
驗證不夠 — post-tool hook 沒攔截到顯而易見的錯誤。
狀態遺失 — plans / decision-log 沒讀到。
模型本身誤判 — 真的就是模型的 spiky intelligence 問題。

這七種失敗類型對應七種不同的修法。 不分類就修，通常會修到錯的地方。

Solve rate 是核心指標

Philschmid 與多篇 2026 社群文章都強調，要能在真實 use case 下比較不同模型與不同 harness，誰的 solve rate 更高。

如果你只有「好像比較順」這種感覺，那還不算進階工程。

五、Build to delete：最反直覺的一條原則

Philschmid 在 2026 的文章特別提醒一件事：

新模型一出來，很多你昨天寫的控制流程都會變成負擔，所以 harness 架構要模組化，準備好把「聰明但脆弱的控制邏輯」刪掉。

這跟一般「累積」的直覺完全相反。harness 要像積木，不是像石雕：

積木式 harness：每個 hook、每條 rule 都可以獨立開關。
石雕式 harness：規則層層疊疊、互相依賴，刪一條就壞一片。

2026 的共識是：模型越強，harness 通常應該越簡，不是越複雜。

六、進階常見誤區

只顧 guardrails，不顧 developer ergonomics — 最後團隊自己都不想用。
把所有邏輯硬編排進流程 — 讓模型失去利用能力的空間。
沒有 log schema — 後面根本無法分析成功率與失敗型態。
每次失敗都 patch 一條規則 — 最後長成不可維護的規則森林。

特別要警惕第 4 點：「規則森林」是進階層最常見的死法。每次失敗都加一條規則，半年後你有 300 條規則，互相衝突、沒人敢動、新人看了就想離職。

正確的做法是：每次 patch 規則之前，先問「這是規則問題還是設計問題」。很多時候你該改的是 middleware 或 tool，不是再疊一條 rule。

AI 協作：學了這個，跟 AI 怎麼配合？

進階層的工作很多時候是「看 trace 找 pattern」。這正是 AI 擅長的事 — 它可以在 30 秒內讀完 500 條 log，比你自己瞄快 100 倍。

你的人類優勢：

你知道哪些 pattern 是「真問題」、哪些只是「正常變異」。
你知道修 A 會不會影響 B，AI 看 trace 看不到這個因果。

可以這樣跟 AI 說：

我有過去 7 天的 agent trace log（欄位包含 task_id、tool_name、retry_count、error_type、latency）。請幫我做三件事：(1) 統計失敗分型分布、(2) 找出 retry_count > 3 的 top 3 tool、(3) 針對每個問題提出「最小修改」的 middleware 或 rule 調整建議（而不是疊新規則）。

練習題

本堂重點回顧

Middleware 把控制點放在 model 與 tool 之間，是進階層的安全網。
State 是一級工件：plans / decision-log / known-issues 必須跟 code 住在同一個 repo。
Observability 先於優化：沒有 trace 與 solve rate，就不算進階工程。
Build to delete：模型越強，harness 越應該簡化；當心規則森林。

下堂課：深入 — 當你要支撐團隊或產品級的 agent 系統，你需要的已經不是更多 rule，而是一個可版本化、可評估、可治理成本的 harness 平台。