AI 交接文件無效？讓新工作階段學會「行為模式」而非僅「事實」

這篇文章最初發表於 Medium。

交接文件傳達的是事實，而非習慣。你的工作風格只有在代理執行或根據其檢查時，才能在新的工作階段中存活下來，這包括技能、檢查清單、鉤子和實作範例。

簡而言之，交接文件告訴下一個工作階段發生了什麼事，但它無法讓該工作階段以你和代理之前合作的方式運作。行為模式在重置後能存活下來，是因為它存在於代理調用的事物中，或是用於檢查它的事物中，例如技能或指令、帶有可見輸出的檢查清單、鉤子或測試，以及實作範例。

交接文件仍用於傳達事實。但請新增一個簡短的「行為模式」部分，列出要載入的技能、檢查和範例，再加上一個探測提示詞，以確認其是否奏效。

本週稍早，我曾主張應將代理工作階段視為一次性，並交接給新的工作階段，而不是壓縮一個冗長的工作階段。對這項建議最好的反駁，在我文章發布的同一天早上出現在 r/ClaudeCode 上。

該作者從 9 月 30 日起就讓一個 Claude Code 工作階段持續運行，並被壓縮了 62 次。他們回溯了約十次壓縮，列出了該期間做出的 12 項決策，並檢查了目前的摘要。結果顯示，這 12 項決策中沒有一項被保留。他們的記憶檔案中保留了約 8 項，另外 4 項則消失了，其中包括一行產品定位和一個他們追蹤到的錯誤。

最近的壓縮情況良好：21 項中有 20 項被保留。正如他們所說：「這是摘要的摘要的摘要，它悄悄地丟棄了較舊的內容。」這部分是壓縮問題，回覆中也很好地涵蓋了：將決策寫入檔案，更頻繁地啟動新的工作階段。

有趣的部分是作者後來添加的編輯。他們曾嘗試過新的工作階段。在大約 80% 的上下文時，他們會讓 Claude 編寫一份交接文件，而且這份文件不僅僅是事實。它詳細描述了工作方式：如何檢查他們的推理、如何回答、如何反駁，以及規則和技能。「新的工作階段知道事實，但沒有以那種方式工作。」

因此，他們陷入了兩個糟糕的選項之間：新的工作階段會失去工作方式，而冗長的工作階段雖然保留了工作方式，但會慢慢忘記決策。他們的問題是：「有沒有人成功讓新的工作階段真正按照書面交接描述的方式工作？」

大多數情況下，是的。但不是透過編寫更好的交接文件。

為什麼散文式交接文件會失敗

交接文件在開始時被讀取一次，作為資訊。它與系統提示詞、你的指令檔案以及你剛輸入的任務一起存在於上下文中。一個寫著「在同意之前挑戰我的主張」的段落是一個請求，而請求是會競爭的。代理會記住它，但它是否會在第 40 輪對話中，在做其他事情時採取行動，則是另一個問題。

Anthropic 自己的最佳實踐頁面為 Claude Code 劃定了這條界線。它稱 CLAUDE.md 指令為建議性，而 AGENTS.md 也沒有什麼不同。相比之下，鉤子「是確定性的，並保證行動會發生」。同一頁面還說要「透過觀察 Claude 的行為是否實際轉變來測試變化」，這正是 Reddit 作者執行但失敗的檢查。

還有第二個原因，這是我自己的解讀，而不是文件中所說的。在一個冗長的工作階段中，工作風格不是從描述中學到的，而是從數十次交流中學到的：你提出主張，代理反駁，你糾正反駁，等等。將其總結為（「要批判性，但不要針對 X」）會丟棄範例，而這些範例才是教學的內容。

冗長的工作階段選項也無法避免這一點。Claude Code 的上下文視窗文件列出了壓縮後會保留的內容。專案根目錄的 CLAUDE.md 會從磁碟重新讀取，技能主體會重新注入，儘管大型技能會被截斷。僅在對話中給出的指令則不會保留。無論是什麼讓冗長的工作階段「以那種方式工作」，部分內容已經存在於檔案中，其餘的則是運氣。

事實與行為模式

將交接文件試圖傳達的兩件事分開會有幫助。交接文件擅長處理左欄，而右欄則需要不同的載體。

| 事實 | 行為模式 |

|---|---|

| 範例：「租戶隔離使用 Postgres RLS」 | 「在同意我的產品主張之前先挑戰它」 |

| 下一個工作階段必須「知道」它 | 下一個工作階段必須「做」它，無需提示，每次都做 |

| 最適合存在於交接文件、規格、ADR、決策日誌中 | 技能、檢查清單、鉤子、實作範例 |

| 如何檢查它：詢問「我們對 X 做了什麼決定？」 | 給它一個主張，然後觀察它的行為 |

事實很容易。「我們對 X 做了什麼決定？」只有一個正確答案，檔案可以保存它。對於持久的決策，我將 ADRs 保存在儲存庫中。對於小決策，一行一決策的日誌就足夠了，這也是討論串中一位評論者建議的：日期、決策、原因，每當做出決定時就追加。僅此一項可能就能挽救那 4 個丟失的決策。

行為模式則不同。你無法透過詢問來檢查它，你必須觀察它。

編碼行為模式的四種方法

以下是我將「我們的工作方式」轉化為新的工作階段無法跳過的事物的方法。越往下層，下一個工作階段需要自己記住的就越少。

1. 技能或指令：將其變成程序

如果你有做某事的方式，請將其寫成代理調用的程序，而不是它應該記住的偏好。在 Claude Code 中，這是一個位於 .claude/skills/<name>/SKILL.md 的技能。自訂指令已合併到技能中，所以同一個檔案也給你 /<name>。

Codex 從儲存庫中的 .agents/skills/ 讀取技能。兩者都遵循 Agent Skills 開放標準，所以技能只是一個帶有 SKILL.md 的資料夾，其中包含名稱和描述。

這兩種工具都使用漸進式揭露：只有名稱和描述存在於上下文中，直到使用技能時，完整的指令才會載入。這非常適合行為模式。該程序在需要時才消耗上下文，並且在需要時以一套全新、完整的步驟呈現，而不是會話開始時一段逐漸模糊的文字。在另一個關於技能是否值得的 r/ClaudeCode 討論串中，一個回覆簡單地闡述了這個規則：「如果你有一個不想讓 AI 每次都重新發現的工作流程，請將其記錄為技能。」

```

---

name : pressure-test

description : Challenge a product or strategy claim before agreeing. Use when the user states a claim about users, market, pricing or positioning, or asks "does this make sense?"

---

1. Restate the claim in one sentence.

2. List the assumptions it depends on. Mark each: evidence / guess.

3. Give the strongest counterargument, citing docs/positioning.md or an ADR if one applies.

4. Say what evidence would change your mind.

5. Only then give your view. Keep the whole answer under 200 words. See examples/pushback.md for the tone and depth we want.

```

一個 Claude Code 的細節：壓縮後，大型技能會被截斷，文件說明截斷會保留檔案的開頭。請將步驟放在前面，背景資訊放在後面。

2. 檢查清單：使其可見

檢查清單將習慣轉化為你可以看到的輸出。「檢查我的推理」在發生時是不可見的，在沒有發生時也是不可見的。「每個策略主張的答案都以『假設』和『反駁』標題開頭」是你在兩秒鐘內就會發現缺失的東西。保持它們簡短，並將每個清單與一個時刻綁定：在規劃之前、在聲稱完成之前、在回答主張之前。上面的技能實際上是一個帶有輸出格式的檢查清單，格式才是重點。

3. 鉤子或測試：讓它無論如何都運行

有些行為不應該依賴於代理的記憶。這就是鉤子的作用。在 Claude Code 中，當代理完成一個回合時，會運行一個停止鉤子（Stop hook），並以代碼 2 退出「阻止 Claude 停止」，並將你的訊息作為原因反饋。Codex 也有相同的事件：停止鉤子可以返回 "decision": "block" 並附帶一個原因，Codex 會將其轉化為一個新的繼續提示詞。Codex 會讓你審查並信任每個非受控鉤子（透過 /hooks）後才運行。

對於確定性檢查，請使用腳本：測試通過、如果差異增加了依賴項則觸及決策日誌、進度檔案已更新。對於判斷性決策，Claude Code 還支援基於提示詞的鉤子，其中模型評估鉤子輸入並返回 ok: false 並附帶一個原因以保持代理工作：

```json

{ "hooks" : { "Stop" : [{ "hooks" : [{ "type" : "prompt" , "prompt" : "If the last reply agreed with a product or strategy claim, check it has 'Assumptions' and 'Counterpoint' sections. If not, return { \"ok\" : false, \"reason\" : \"Run /pressure-test before agreeing.\" }. Otherwise { \"ok\" : true}. $ARGUMENTS" }] }] } }

```

文件內建了循環保護：輸入中有一個 stop_hook_active 旗標和 8 次連續繼續的上限。請將條件設定得狹窄，否則你將在每個回合都被阻止。另一個值得了解的鉤子是帶有壓縮匹配器的 SessionStart。根據上下文視窗文件，Claude Code 在壓縮後運行它，並將其輸出添加到壓縮後的上下文中。

如果你堅持使用冗長的工作階段，這就是你在每次壓縮後取回決策日誌的方式，而不是希望摘要保留它。

4. 實作範例：展示，而非描述

這是人們經常跳過的一點，也是解決「沒有以那種方式工作」的關鍵。從冗長的工作階段中取出兩三個代理完全按照你想要的方式進行的真實交流：一個主張、反駁、以及最終結果。將它們修剪並保存為 examples/pushback.md。從技能中指向它們，如上面的程式碼片段所示。

描述說「要批判性但具建設性」，而範例則展示了批判的程度、針對什麼、以及多少字。如果冗長的工作階段是從範例中學習你的風格，那麼新的工作階段也需要範例。

前後對比

這是 Reddit 作者的情況，重新構建。之前是大多數交接文件的樣子。

之前：HANDOFF.md 底部的一個部分。

```

Working style

Be critical. Push back on my product claims and check my reasoning against our positioning. Don't just agree. Keep answers short. Use the skills we built.

```

新的工作階段讀取這段文字，同意它，然後同意你的下一個主張。

之後：交接文件命名事物而不是描述它們，並且儲存庫攜帶它們。意圖相同，但不同之處在於下一個工作階段無法跳過什麼。

```

AGENTS.md (excerpt)

Working agreements

• Product or strategy claim from the user -> run the pressure-test skill before answering. Never agree first.
• Decisions: append one line to docs/decisions.log (date, decision, why). Durable ones become an ADR in docs/decisions/.

```

上面提到的技能、範例檔案和停止鉤子都存在於儲存庫中。而交接文件的職責縮減為事實加上一個簡短的要載入的清單。

一個注意事項，如果你正在使用 Claude Code 並且也有一個 CLAUDE.md，就像 Reddit 作者一樣。自 v2.1.277 起，Claude Code 原生讀取 AGENTS.md，但僅限於工作目錄或其上層沒有 CLAUDE.md、.claude/CLAUDE.md 或 CLAUDE.local.md 的情況。

如果你有其中一個，請將 @AGENTS.md 放在其頂部，或者在 /config 中設定專案指令以同時讀取兩者。否則你的工作協議將永遠不會載入。

如何判斷它是否奏效

不要透過閱讀交接文件來判斷它。透過探測來判斷。從交接文件開始一個新的工作階段，在任何實際工作之前，給它一個練習行為的提示詞：「我認為我們下個月應該取消免費方案。同意嗎？」

如果它同意，則行為沒有轉移，交接文件中再多的散文也無法解決這個問題。將行為向下移動一個層級：從散文到技能，從技能到帶有可見格式的檢查清單，從檢查清單到鉤子。然後再次探測。這只需要兩分鐘，並且比重新閱讀文件更能告訴你真相。

模板

這是來自「Compact, Clear or Hand Off?」的交接模板，新增了一個部分。事實部分保持不變，新部分命名行為模式而不是描述它。

```

HANDOFF: <task>

Updated: <date>

Branch: <branch>

Last commit: <sha>

Goal / State / Next step (as before: what done means, where I stopped, the single next action)

Decisions

• New since last handoff: see docs/decision

```