少即是多，我連砍了三刀

出生就過重#

看起來 multi-agent，不等於有隔離說到架構立住了。現在回頭看看這個專案出生那天的體檢報告，也就是第一個 commit 的 git show --stat（節錄）：

 CLAUDE.md   | 232 +++++++
 README.md   | 143 +++++
 USAGE.md    | 757 +++++++++++++++++++++++
 setup.sh    | 135 ++++
 12 files changed, 2167 insertions(+)

757 行的使用說明，加上 240 行的導入指南（沒擠進節錄的那位），再加上 README 和給 AI 的專案指示：說明文件合計 1,372 行，佔整包 2,167 行的六成三，功能本體反而是配角。那條 757 的加號長龍，就是「文件先行」的心電圖。

一個還沒有任何使用者的專案，替每一種想像中的使用情境寫好了操作手冊。典型的文件先行：預想了所有情境，然後沒有一種真的發生。真實的痛點要等部署出去才會來敲門，而它們敲門的樣子，跟手冊裡預想的沒有一項對得上。

「少即是多」這句老話，後來在這個專案裡連砍了三刀。有趣的是每一刀的對象都不同。

第一刀：實作（上一篇砍完了）#

自製的 1600 多行協作管線被官方 plugin 做掉、光榮退役，帳算過了不重算。這一刀砍的是重複的實作：官方做得比你好的，不要自己養。

第二刀：介面#

架構穩定之後，我原本預期的脆弱點在執行階段：任務分類誤判、額度、長 session 漂移。但實戰的結果完全相反。執行段最穩（隔離承重牆站得住），真正磨人的是兩端：

• 進場：每開一個專案，都要手動搬檔、填設定；
• 介面：757 行的 USAGE，沒人（包括寫它的我）真的照著用。

兩者的共通點是「人的認知負載」，不是 AI 的能力。這條後來成為文件裡的教訓：架構設計容易過度關注 AI 怎麼做事，低估人怎麼啟動和驅動這套系統。

於是 6 月 3 日出現了這個 repo 最痛快的一個 commit，--stat 的形狀跟出生那天剛好相反（節錄）：

 ADOPTION.md  | 275 --------
 PROMPTING.md |  81 +++
 USAGE.md     | 757 -----------------------
 init.sh      | 153 +++++
 setup.sh     | 135 ----
 12 files changed, 662 insertions(+), 1564 deletions(-)

757 行的使用說明整包蒸發。順帶一提，導入指南死前還從 240 行長胖到 275 行：文件的預設運動方向就是變厚，不砍它，它不會自己瘦。同一波動作把介面修成三個樣子：

• 環境變數取代分岔。受限環境需要一個降級檔位，直覺是維護兩份設定檔，但那會讓我變成兩份檔案的人肉同步器。改用一個 per-machine 環境變數切換之後，同一份 repo，drift（兩份設定各自演化、越差越遠）從結構上不可能發生。
• 選擇性安裝取代整包複製。原本把整個 kit 複製進專案，連 kit 自己的文件都被拖進去，連我自己都分不清哪些能改。改成 kit 是「留在原地的工具」，安裝只吐出安裝層。於是專案裡只剩「該填的」跟「別碰的」兩種檔案。
• 參數化速查取代情境手冊。USAGE 失敗的診斷很具體：它把一個小小的控制文法攤平成六個情境範本，你永遠在找「最像我現在情況」的範例，而不是套公式。收斂成一頁參數化的速查卡。

插曲：連速查卡自己也退役了#

那頁速查卡活了不到一個版本。幾輪專案跑下來，控制文法就那幾條，內化一次之後就記住了，速查卡再也沒人翻開。死亡證明是一條 commit 訊息（逐字）：

docs: sync kit docs for v3.2, retire PROMPTING.md

出生到退役，相隔一個月。它的殘值（回來複習的那句 prompt、更新指令）被併進專案 README 的「叫 AI 接手」段，因為那是我本來就會回去看的地方。

這是「使用者文件」教訓的完整版：文件不只要存在，還要符合使用時的形態。手冊太重，人在當下要的是速查卡；再後來，連速查卡都太重。教學任務完成的文件，就該功成身退。文件跟程式碼一樣有生命週期，寫下來不是永久合約。

第三刀：所有權#

砍完行數，最深的一層問題才露出來。kit 鋪進多個專案之後，kit repo 更新了，已部署的專案拿不到：規則埋在各專案設定檔的段落裡，沒有回流機制，只能人工比對貼過去。又一種形式的人肉同步器。

當時的折衷是段落級約定：設定檔上半使用者填、下半 kit 塞，靠人自律不去動下半段。但沒有工具能執行的約定，就不是約定，是祈禱。更新腳本無從得知使用者是否手滑改了下半段、該不該覆蓋。

我的解法是把所有權從「檔案內的段落」升格成「檔案本身」：

• kit-owned（規則、hooks、skills）：真理源在 kit repo，更新時直接覆蓋、不心疼；
• user-owned（專案設定、權限清單）：kit 永不碰，最多印個 diff 供我手動合併。

所有權以檔案為單位劃清楚之後，--update 才終於可以放心執行。回流機制缺的最後一塊拼圖，不是程式碼，是產權。

三刀擺在一起看才看得出章法：第一刀砍實作、第二刀砍介面、第三刀砍所有權的模糊。同一句「少即是多」，砍的是三種不同的「多」——多餘的程式、多餘的認知負載、多餘的模糊地帶。

下一篇#

這一篇講完了三刀「少即是多」：砍掉重複的實作、砍掉壓在人身上的認知負載、砍掉所有權的模糊地帶。最後那刀換來的產權劃分（kit-owned 覆蓋不心疼、user-owned 永不碰），是整個機隊能整批升級的地基。

屋子清爽了，但同一個屋簷下還住著一位嗓門很大的房客。它在每個 session 開頭用最高優先級宣告「只要有 1% 的可能適用，就必須呼叫我」。下一篇：superpowers 是個強勢房客，以及為什麼弱模型每次都聽它的。