交接文件：代理在工作階段間的記憶傳承

2026年3月21日，我的正式環境網站在快取清除後暴露出效能瓶頸，頁面載入時間長達14秒。我跨越兩個工作階段調查根本原因，找出緩慢的程式碼路徑，草擬了修正計畫，並將一切記錄在交接文件中。

交接文件將診斷跨越工作階段的邊界傳遞，使實作的代理能繼承已修正的理解，而不必重新推導相同的錯誤結論。與僅說明要做什麼的工單不同，交接記錄了嘗試過什麼、哪裡出錯、以及先前的做法為何失敗。市場頁面的交接在四天內經歷三次修正仍屹立不搖，並指引實作將頁面載入時間從14秒縮短至108毫秒。

該交接的第一版草稿是錯的。它鎖定了錯誤的程式碼路徑。一次程式碼審查發現，實測的緩慢頁面是由market_hub()提供，而非交接所假設的_fetch_market_data()。於是交接被修訂。

第二版草稿提議為Apple Maps和分級計數加上不必要的HTMX部分內容。審查發現Apple Maps是在本地簽署URL（沒有可延後的對外請求），而分級計數應透過單一聚合查詢取得。交接再次被修訂。

第三版草稿提議將天氣端點改為非同步，但並未說明現有的同步HTTP用戶端即使放在HTMX後面，仍會阻塞事件迴圈。交接第三度被修訂。

四天後，另一個工作階段讀取了這份經過三次修訂的交接並實作了修正。Austin從14,290毫秒降至108毫秒。實作鎖定了正確的程式碼路徑，採用了正確的查詢方式，並略過了不必要的HTMX部分內容。三次審查的每一項修正都已被納入。

這份交接文件將診斷跨越四天與多個工作階段傳遞。若少了它，實作的工作階段就得從零開始，做出相同的錯誤假設，提出相同的多餘最佳化，並需要相同的修正。交接將四天的調查壓縮成一份實作代理只需數秒即可讀完的文件。這正是脈絡視窗管理應用於具體問題的實例：如何在跨越工作階段邊界時傳遞診斷，而不遺失使其精確的那些修正。

交接文件包含什麼

交接文件不是工單。工單說明要做什麼。交接則說明已嘗試過什麼、學到什麼、哪裡出錯、以及接下來要做什麼。差別在於制度化記憶。

市場頁面的交接包含：

診斷結果。六個市場頁面的冷渲染TTFB測量值，從381毫秒（東京，小型市場）到14,290毫秒（Austin，500多家公司）不等。測量結果證明問題的規模與公司數量成正比，這指向查詢結構才是瓶頸。

根本原因，依影響排序。四個根本原因按影響排序：查詢結構（主要）、阻塞性的天氣API（次要）、另一條程式碼路徑上的全表掃描（第三）、以及缺少快取標頭（已部分處理）。每個根本原因都附上檔案路徑、行號，以及造成緩慢的特定程式碼模式。

走錯的岔路。第一版草稿鎖定了_fetch_market_data()而非market_hub()。交接記下了這個錯誤與修正，讓實作的工作階段不會重新推導出相同的錯誤結論。它也記下了被捨棄的HTMX部分內容以及捨棄的原因：Apple Maps沒有對外請求，分級計數應納入聚合查詢。

實作計畫。五個步驟，附SQL範例、驗收標準與驗證指示。步驟1：用資料庫查詢取代Python端分頁。步驟2：以非同步用戶端新增HTMX天氣部分內容。步驟3：為次要程式碼路徑加上快取。步驟4：加入邊緣快取標頭。步驟5：重新測量相同的六個URL。

脈絡視窗管理一文解釋了為何這種細緻度如此重要：交接中的每一處模糊，都是實作代理必須重新推導的決策，這會消耗脈絡預算，並冒著得出相同錯誤結論的風險。

脈絡地雷。共用的模板脈絡在每個頁面都會進行經過驗證的金幣餘額查詢，即使是從不渲染它的頁面也一樣。交接將此標記為快取正確性的隱憂：沒有正確Vary標頭的s-maxage，可能對匿名使用者提供過時的驗證資料。

為何工單會失敗

同樣工作的工單會寫成：「市場頁面很慢。請最佳化market hub查詢。」實作的工作階段就得：

1. 找出哪條程式碼路徑負責市場頁面（不讀路由器並不明顯）
2. 分析程式碼路徑以找出瓶頸
3. 考量各種最佳化方法
4. 實作其中一種
5. 發現該方法有副作用（驗證資料的快取正確性問題）
6. 修改方法

步驟1至3在調查的工作階段中已經完成。交接將這些成果向前推進。工單卻把它們丟棄。

失敗模式不是懶惰。失敗模式是工作階段邊界造成的脈絡流失。AI代理的工作階段一開始脈絡視窗是空的。它不記得前一個工作階段發現了什麼。這正是脈絡即架構在系統層面所處理的問題：你放進脈絡視窗的內容決定了輸出的品質。工單提供目標。交接提供目標加上正確達成目標所需的累積理解。

修訂歷史的重要性

交接的修訂歷史與其當下內容同樣有價值。市場頁面的交接記錄了三次修訂，附有時間戳記與原因：

• 擷取：2026-03-21T17:24（原始調查）
• 修訂：2026-03-21T18:20（程式碼審查修正：錯誤的程式碼路徑、不必要的HTMX）
• 修訂：2026-03-25T06:30（實作完成，查詢修正已部署）

修訂歷史告訴實作的工作階段：「這份診斷曾被挑戰並被修正。目前版本已納入這些修正。」沒有任何修訂的交接可能是錯的。經過三次修訂的交接則已經通過壓力測試。

走錯的岔路本身就是價值的一部分。一份寫著「我們考慮過/_map HTMX但因Apple Maps在本地簽署URL而予以否決」的交接，可以省去實作的工作階段提出相同最佳化、讓它被審查、再被否決的循環。交接預先把否決搬到前面。

何時該撰寫交接

並非每項任務都需要交接。一個工作階段就能解決的錯誤修正，不需要跨階段的持續性。交接在以下情況才有價值：

調查成本高昂。分析效能瓶頸、追蹤安全性漏洞、除錯多系統互動。若調查花了可觀的心力，交接能保留這份心力。

實作將在不同的工作階段進行。若今天完成調查但明天才實作，交接能銜接這段空檔。少了它，明天的工作階段就得從零開始。

診斷並不顯而易見。若正確的修正需要理解為何三個看似合理的替代方案都是錯的，交接便能捕捉這份理解。複利脈絡系統解釋了交接如何融入更廣泛的專案知識累積。僅寫著「修正查詢」的工單，並不會說明為何該查詢需要特定的修正。

多人（或多個代理）可能會處理。交接是一份共享的理解文件。任何讀到它的工作階段都能繼承完整的調查脈絡。

交接作為複利脈絡

交接是複利脈絡系統中的一筆存款。每份交接都捕捉診斷時間，並將其轉化為可重複使用的資產。實作的工作階段以近乎零成本提取這份診斷。

隨著時間推移，交接累積成一部調查史。市場頁面的交接援引了快取清除事件、nightcheck測量、破壞性API防護，以及程式碼審查系統。這些本身都是先前工作階段的產物。交接將它們串聯成一則新工作階段可以循跡而行的敘事。

交接並不取代理解。實作的工作階段仍需閱讀程式碼、撰寫修正並驗證結果。交接取代的是重新發現。該工作階段不需要再去發現已知的事物。Ralph代理架構將交接作為其整夜執行迴圈的主要跨階段持續機制。AI工程中心記錄了交接如何融入更廣泛的鉤子、技能與記憶系統基礎設施，讓代理協助的開發能隨時間產生複利。

FAQ

交接應該多長？

長到足以涵蓋診斷、走錯的岔路與實作計畫。短到代理能在一次脈絡載入中讀完。市場頁面的交接為103行。大多數交接在50至150行之間。

交接儲存在哪裡？

在專案的記憶目錄：~/.claude/projects/{project}/memory/handoff-{topic}.md。記憶系統會依據frontmatter描述載入相關檔案，因此未來的工作階段無需明確引用也能發現交接。

交接會取代文件嗎？

不會。文件描述系統如何運作。交接描述關於特定問題學到了什麼，以及該如何處理。文件是永久的。交接在實作的工作階段消化後便成為歷史脈絡。

如果交接過時了怎麼辦？

交接的狀態欄位會追蹤這點。啟用中的交接標記為PLANNED或IN PROGRESS。已完成的交接標記為RESOLVED並附上實作的commit雜湊值。過時的交接仍以歷史脈絡的形式可見，但不再可執行。

資料來源

本文援引市場頁面效能交接（handoff-market-page-perf.md），該交接指引了2026年3月25日部署的查詢結構修正。這份交接在四天內歷經三輪修訂仍屹立不搖，並促成一項達到132倍效能提升的實作。相關引用見複利脈絡。