團隊原本只有一份 Runbook。

內容很簡單。

這個能力可以做什麼
什麼情況適合使用
使用者需要提供哪些資訊

後來 Agent 開始使用同一份文件。

大家覺得很合理。

既然人和 AI 做的是同一份工作，維護兩套文件只是增加成本。

一開始確實很省事。

但 Agent 第一次走錯路後，文件裡多了一段：

Trigger
Non-trigger

第二次 Handoff 漏掉 Target，又補上：

Routing
Handoff Context

之後還有：

Evidence Policy
Write Boundary
Answer Contract

幾個月後，一位新使用者打開 Runbook。

翻了兩頁還找不到自己最想知道的東西：

我到底什麼時候該用這個能力？

另一位維護者於是把技術細節刪掉一半。

文件變好讀了。

下一次 Agent 卻又把一個 Read Request 走成了 Write Path。

同一份文件，開始在兩種 Reader 之間來回拉扯。

共用內容，不代表必須共用同一個 Surface

人類使用者真正需要的通常是：

有哪些能力？
什麼情況使用？
我要怎麼描述需求？

Agent Runtime 需要的則是另一組東西：

什麼時候 Trigger？
什麼情況不要 Trigger？
要 Route 給誰？
Handoff 要保留什麼？
哪些 Evidence 可以用？
什麼 Action 不可以做？

兩邊都在描述同一份工作。

但用途不一樣。

如果硬把兩種需求塞進同一份 Surface，通常只剩兩個選擇：

對人太複雜。

或：

對 Agent 不夠精確。

這也是 Source 裡明確區分：

Human-facing catalog
≠
Agent-facing execution contract

的原因。

分成兩份，不代表要維護兩套真相

這裡最容易出現另一個誤解。

既然人和 Agent 需要不同文件，那就各寫各的。

很快又會變成：

Human 文件說能力支援 A、B、C
Agent Contract 只 Route A、B

或者：

Human 文件說 Read-only
Agent Contract 還保留 Write Action

所以真正該共用的不是文字排版。

而是底下那份 Work Meaning 和 Boundary。

同一個能力可以有不同 Surface。

但不能有兩套互相矛盾的工作定義。

他們最後真的拆成兩份

Human-facing 文件重新變短。

只保留：

Capability
When to use
How to ask
Expected result

Agent-facing Contract 則保存：

trigger / non-trigger
routing
ownership
handoff
evidence policy
action boundary
answer contract

兩邊都指向同一個 Capability。

使用者不再被要求看懂 Routing Rule。

Agent 也不再靠一段寫給人的簡短說明猜 Execution Boundary。

下一次修改，兩邊都沒有再互相妥協

幾週後，團隊新增了一個使用情境。

Human Catalog 多了一行：

適用於 X 類工作。

Agent Contract 同時更新 Trigger Scope。

文件長得完全不同。

但兩邊表達的是同一件事。

新使用者打開 Runbook，第一頁就知道怎麼用。

Agent 執行時，也仍然有完整的 Boundary。

團隊沒有找到一份「人和 AI 都最適合閱讀的完美文件」。

他們只是接受了一件事：

同一份工作的真相可以共用。

但人和 Agent，不必因此被迫看同一張紙。