為代理而生的深模組

資料來源#

• Full Walkthrough: Workflow for AI Coding — Matt Pocock

摘要#

John Ousterhout 的《A Philosophy of Software Design》區分了深模組（介面小、行為大）與淺模組（介面小、行為少，但數量眾多）。Matt Pocock 將這項區分套用到對代理友善的程式碼庫：代理之所以在深模組的程式碼庫中如魚得水，是因為測試邊界清楚、相依圖淺，而且開發者可以把實作委派出去，同時仍把介面放在心上。淺模組的蔓生則是 AI 在你不加以反制時的預設產物，而它會生出無法審查、無法測試的程式碼庫。

深模組與淺模組#

• 淺模組： 大量小檔案，每個都暴露許多小函式，彼此之間相依圖稠密。測試邊界並不清楚——你要 mock 每一個鄰居嗎？把單元孤立起來測試，卻漏掉整合層級的錯誤？AI 看不到全貌，也無從判斷抽象該落在哪裡。
• 深模組： 一個較大的模組，搭配小巧的公開介面與大量內部邏輯。只有一條自然的測試邊界：公開介面。AI 無須遍歷相依關係就能看出這個模組做了什麼。實作之所以可以委派，是因為介面就是契約。

為什麼代理特別受益#

1. 要遍歷的相依跳轉更少。 smart zone 預算（見 Context Window Smart Zone）得以節省。
2. 測試邊界顯而易見。 審查代理可以在介面層級驗證行為，而不必去微管理內部細節。
3. 實作可以委派。 Pocock 的「gray box」模式——介面自己設計，實作交給代理。你保留了對「做什麼」的認知模型，而無須把注意力燒在「怎麼做」上。
4. 模組地圖是有限的。 一份寫著「修改 gamification service、dashboard route、lesson route」的 PRD 是具體的；同一份 PRD 放到淺模組的程式碼庫，就會變成「修改 47 個檔案」。

風險：代理會往淺模組漂移#

Pocock 的觀察：

「如果你不仔細盯著 AI，它就會生出一個看起來像〔淺模組〕的程式碼庫。所以當你在指揮它時，必須非常、非常小心。」

代理往淺模組漂移的原因：

• 每項任務都很小；代理會做出能動的最小變更
• 沒有全域的模組地圖，代理就不知道該擴充哪個既有模組，於是另起一個新的
• 「單一職責原則」被誤用——代理把每一個輔助函式都包進它自己的檔案

修正之道有二：

1. 把模組地圖留在 PRD 裡（見 Design Concept Grilling），讓代理知道該擴充什麼。
2. 定期跑一輪重構，把淺模組整併成深模組。Pocock 有一個專門做這件事的 skill：improve-code-base-architecture——它會掃描程式碼庫，找出「架構改善候選」（一群相關、可以加深的模組），並為每一個列出引數與相依類別。

推送式與拉取式指令#

一個微妙卻高槓桿的架構選擇：該如何把編碼規範與架構規則傳遞給代理。

模式	機制	何時使用
Push（推送）	永遠在脈絡中（CLAUDE.md、系統提示）	審查代理——它們需要知道規範，才能拿來與程式碼對照
Pull（拉取）	按需透過 skill 取得（代理在相關時才抓取）	實作代理——拉取可避免把 smart zone 預算燒在用不上的規則上

這也是為什麼乾淨的審查者比同脈絡的審查者更聰明：實作者可以按需拉取規則；而審查者既受惠於規則被推送進來，又擁有一個乾淨的 smart zone 視窗去真正評估程式碼。

於全新脈絡中審查#

如果實作用掉了 80K token 的 smart zone，那麼同脈絡的審查者就是在 dumb zone 裡讀這份 diff。清掉脈絡、在全新狀態下跑審查，能讓 smart zone 的推理能力復原。Pocock 把這一點與模型選擇搭配在一起：實作用 Sonnet，審查用 Opus——「那時候我才需要那份聰明。」

Sandcastle 三代理模式#

Pocock 的平行化函式庫把深模組的紀律烤進了它的架構裡：

1. Planner（規劃者）——從待辦清單中挑出 N 個可平行處理的 issue
2. N 個實作者——一個 issue 一個，各自待在自己的 git worktree ＋ Docker 沙箱裡；編碼規範透過拉取式 skill 取得
3. Reviewer（審查者）——針對每個實作者的 diff，在全新脈絡中執行；編碼規範被推送進它的系統提示
4. Merger（合併者）——把所有已核准的分支調和起來，修掉型別／測試的衝突

每個代理都在自己的 smart zone 裡運作。每一處模組層級的變更，都是在介面而非實作上被審查。

為什麼「大模型＝不需要設計」是錯的#

那個誘人的論點：「現在的模型夠聰明，足以在任何程式碼庫裡導航，設計無所謂。」Pocock 的反駁：

「爛的程式碼庫造就爛的代理。如果你有一個垃圾程式碼庫，那麼在那個程式碼庫裡工作的代理，吐出來的也會是垃圾。」

smart zone 的限制（見 Context Window Smart Zone）是結構性的，不只是模型大小的函數。讓代理工作更困難的架構選擇，會耗掉更好的架構本可省下的 smart zone 預算。

相關連結#

• Interaction / Background Model Split——非同步的背景模型就是一個深模組，把推理藏在一道薄薄的介面之後
• Model Introspection Feedback——內省探測模組邊界，找出 harness 在哪裡是淺的
• Matt Pocock——最主要的論述者
• Context Window Smart Zone——深模組節省 smart zone 預算
• Vertical Slice Tracer Bullets——切片在介面處切穿深模組，演練那條自然的測試邊界
• Design Concept Grilling——PRD 裡的模組地圖讓深模組紀律在規劃階段就落地執行
• Agent Loop Pattern——於全新脈絡中審查，正好契合迴圈「清空再重啟」的節奏
• Agent Harness Engineering——「強制不變量，而非實作」是同一原則在編排層的展現
• Claude Code Best Practices——CLAUDE.md 裡的模組地圖屬於同一家族
• Agentic Technical Debt——深模組＋持久的 CLAUDE.md 脈絡合在一起，正是抵禦那份創辦人手冊所點名的複利式債務失效模式的架構防線
• Evals as Product Spec——Pocock 在深模組邊界處的整合測試，是 Cat Wu「十個好 eval」的工程化實例；兩者都是介面處可長可久的驗證產物
• Verification as the New Bottleneck——於全新脈絡中、在模組介面處審查，正是對 Fiona Fung「當驗證成為瓶頸後，由誰來審查」這個問題的具體回答

待解決的問題#

• 「夠深」到底是多深？Pocock 舉的範例模組是數百行；Ousterhout 教科書裡的例子更大。中間有一個甜蜜點；只是沒被講清楚。
• 對於 ports／adapters 風格的程式碼庫，深模組這套建議能否乾淨地轉移過去？「小介面」是 port；「大行為」是 adapter。大概可以，但原始來源沒有實際操演過。
• 重構的成本與效益：在一個運作中的 repo 上跑「improve-code-base-architecture」，什麼時候才划算？

資料來源#

• Full Walkthrough: Workflow for AI Coding — Matt Pocock