適用於代理程式的深層模組

資料來源#

• Full Walkthrough: Workflow for AI Coding — Matt Pocock
• Uncle Bob on Software Fundamentals in the Age of AI

摘要#

John Ousterhout 在《A Philosophy of Software Design》中區分了深層模組（介面小、行為豐富）與淺層模組（介面小、行為少，但數量很多）。Matt Pocock 將這項區分應用於適合代理程式的程式碼庫：代理程式在深層模組程式碼庫中表現出色，因為測試邊界明確、相依圖淺，而且開發者可以在心中保留介面的前提下，委派實作工作。若不加以引導，AI 預設會產生淺層模組蔓延，結果就是難以審查、難以測試的程式碼庫。

深層與淺層#

• **淺層模組：**許多小檔案，各自公開許多小函式，彼此之間形成密集的相依圖。測試邊界不明確——每個相鄰模組都要模擬嗎？單獨測試各單元，卻漏掉整合錯誤嗎？AI 看不見全貌，也無從判斷抽象應該放在哪裡。
• **深層模組：**一個較大的模組，公開介面小，內部邏輯豐富。自然形成單一測試邊界：公開介面。AI 不必穿梭於相依項目，就能看懂模組的功能。實作可以委派，因為介面就是契約。

代理程式為何特別受益#

1. **需要穿越的相依層級較少。**可節省智慧區域預算（參見脈絡視窗智慧區域）。
2. **測試邊界一目瞭然。**審查代理程式可以在介面處驗證行為，不必鉅細靡遺地管理內部細節。
3. **實作可以委派。**Pocock 的「灰箱」模式——自行設計介面，再把實作交給代理程式。你保留對做什麼的掌握，不必耗費注意力在怎麼做上。
4. **模組地圖有限而明確。**PRD 若寫「修改遊戲化服務、儀表板路由、課程路由」，就很具體；面對淺層程式碼庫，同一份 PRD 則可能得說「修改 47 個檔案」。

風險：代理程式會傾向淺層結構#

Pocock 的觀察：

「如果你不仔細留意 AI，它就會產生看起來像[淺層結構]的程式碼庫。所以你在指揮它時，真的必須非常、非常小心。」

代理程式傾向淺層結構的原因：

• 每項任務都很小；代理程式會採取能奏效的最小改動
• 沒有全域模組地圖，代理程式就不知道應擴充哪個既有模組，因此另建一個模組
• 誤用「單一職責原則」——代理程式把每個輔助函式都包進獨立檔案

解法有兩部分：

1. 將模組地圖保留在 PRD 中（參見設計概念深度提問），讓代理程式知道要擴充什麼。
2. 定期執行重構，將淺層模組整併為深層模組。Pocock 有一項技能可用於此：improve-code-base-architecture——掃描程式碼庫，找出「架構改善候選項」（可深化的相關模組群），並列出各項的論據與相依類別。

推送與提取指令#

一項細微但影響深遠的架構選擇：如何將程式撰寫標準和架構規則交付給代理程式。

模式	機制	適用時機
推送	始終置於脈絡中（CLAUDE.md、系統提示）	審查代理程式——它們需要知道標準，才能與程式碼比對
提取	透過技能按需取得（代理程式在相關時自行擷取）	實作者代理程式——提取可避免為不適用的規則耗用智慧區域預算

這也解釋了為何全新脈絡中的審查者比同一脈絡中的審查者更聰明：實作者可以按需提取規則；審查者則受益於規則已推送進來，加上乾淨的智慧區域視窗，能真正評估程式碼。

在全新脈絡中審查#

若實作已耗用 80K 個智慧區域 token，同一脈絡中的審查者會在愚笨區域閱讀差異。清空脈絡並以全新狀態進行審查，就能恢復智慧區域推理。Pocock 也搭配模型選擇：實作用 Sonnet，審查用 Opus——「這時我需要聰明的模型。」

Sandcastle 三代理程式模式#

Pocock 的平行化程式庫將深層模組紀律融入架構：

1. 規劃者——從待辦清單挑出 N 個可平行處理的議題
2. N 個實作者——每個議題各派一個，各自在獨立的 git worktree 與 Docker 沙箱中工作；可透過提取技能取得程式撰寫標準
3. 審查者——在全新脈絡中逐一審查每位實作者的差異；程式撰寫標準會推送到系統提示中
4. 合併者——整合所有核准的分支，並解決型別與測試衝突

每個代理程式都在自己的智慧區域中執行。每項模組層級的改動都在介面處審查，而非檢查實作細節。

為何「模型夠大就不需要設計」是錯的#

誘人的論點是：「現在模型夠聰明，什麼程式碼庫都能駕馭，設計已不重要。」Pocock 的反駁：

「糟糕的程式碼庫會造就糟糕的代理程式。如果你的程式碼庫一團糟，在那個程式碼庫中工作的代理程式也只會產出垃圾。」

智慧區域限制（參見脈絡視窗智慧區域）是結構性的，不只是模型規模的函數。讓代理程式工作更困難的架構選擇，會耗掉更好架構原本能省下的智慧區域預算。

Ousterhout 的另一方，以及架構閘門（Martin，2026-08）#

Robert C. Martin——他在《Clean Code》第二版附錄辯論中是 Ousterhout 的對手，因此最不可能替本頁背書——卻毫無保留地同意本頁的核心主張（Uncle Bob on Software Fundamentals in the Age of AI，2026-08-19，practitioner-opinion）。有人問他，深層模組是否適合代理程式，因為代理程式可以讀介面而不必理解實作：

「絕對適合。它們會留意結構。這能讓它們不必讀取底下的程式碼，這既是危險，也是優勢——只要程式碼一致，就沒問題。它們也會留意測試。它們會讀測試來理解系統的功能。」

有兩項補充值得一併記下。

**模組邊界的主題連貫性論據。**Martin 對本頁以脈絡為基礎的機制（「模組符合視窗大小時，代理程式的工作表現較好」）提出另一個根據——主題連貫性，而非規模：

「如果代理程式能專注於一個模組，而且該模組有明確的發展脈絡，它們的表現會好得多，模型也不會被模組裡的各種主題搞混……如果你把世上所有東西都塞進一個模組，可憐的代理程式就會納悶：我到底在這裡做什麼？」

這裡指的是訪談中的咖啡與肥皂劇示例：無關內容進入脈絡視窗後，會污染後續的所有內容，因此混合不同關注事項的模組是污染源，而不只是規模太大。這推導出一項僅看大小無法預測的結果——含有兩項無關職責的小型模組，對代理程式的傷害可能大於大型但用途單一的模組。

**以架構作為確定性閘門，且已有部分成果。**Martin 是這份資料集中，最進一步嘗試把模組結構從文字審查移到檢查工具中的人：

• 代理程式替他建置的架構檢視器：以 UML 呈現模組結構與相依方向，可點入子模組直達程式碼，讓他不必讀取檔案就能檢視任何層級。
• 相依規則規格檔——明列哪些模組可以相依於哪些模組，以及相依方向——「代理程式不得違反這些規則。最後還會執行另一個小型檢查器；如果它們違反規則，就得設法修正。通常是反轉相依方向、插入介面，或把模組拆成兩半。」

他之所以走上這條路，是因為每次詢問代理程式它們產生了什麼結構，答案都令人不安：「我會被嚇壞，因為那些答案可怕得不得了。」他也明確指出，剩下那一步無法自動化——一開始決定如何劃分模組：「我現在正在研究能不能把這件事自動化，但目前進展不太順利。」這讓架構落在重振不切實際的品質工具中各項品質閘門的另一側：複雜度與涵蓋率可以檢查；只要先宣告相依方向，它也能檢查；但模組應該如何劃分則無法檢查。

延伸閱讀#

• 強調價值，而非規訓——依 Ousterhout 和 Martin 的說法，這項價值能原樣傳遞給代理程式，與那些不適用於代理程式的人體工學儀式形成對照

• 規格驅動開發成為新瀑布式流程——Martin 與其他人都尚未自動化的，是各次增量之間的架構審查步驟

• 以審查作為控制點——即使 Martin 已將逐行審查交由閘門處理，仍保留的人類介入步驟

• Robert C. Martin（Uncle Bob）——Ousterhout 在附錄中的對手，認同深層模組適合代理程式，並補充主題發展脈絡的論據

• 重振不切實際的品質工具——可檢查的品質閘門；他的相依規則檢查器是其中的架構類工具，而模組劃分決策則是難以納入檢查的部分

• 互動／背景模型分離——非同步背景模型是隱藏推理過程、只露出精簡介面的深層模組

• Model Introspection Feedback——自省探測模組邊界，找出 harness 淺薄之處

• Matt Pocock——主要論述者

• 脈絡視窗智慧區域——深層模組能節省智慧區域預算

• Vertical Slice Tracer Bullets——切片在介面處穿過深層模組，並運用自然形成的測試邊界

• 設計概念深度提問——在規劃階段，PRD 中的模組地圖讓深層模組紀律落實於實際流程

• Agent Loop Pattern——在全新脈絡中審查，符合迴圈中清除後重新開始的節奏

• Agent Harness Engineering——「強制執行不變條件，而非實作」是協調層的同一項原則

• Claude Code Best Practices——CLAUDE.md 中的模組地圖也屬於同一類做法

• Agentic Technical Debt——深層模組加上持續存在於 CLAUDE.md 的脈絡，共同構成架構防線，抵禦創辦人手冊所指出的債務複利失控模式

• Evals 即產品規格——Pocock 在深層模組邊界設置的整合測試，是 Cat Wu「十個優質 evals」在工程上的實例；兩者都是介面處持久的驗證成果

• 驗證成為新的瓶頸——當驗證成為瓶頸時，在模組介面處以全新脈絡審查，具體回應了Fiona Fung提出的「誰來審查」問題

• Repository Exploration Subagent——FastContext 將深層模組與全新脈絡的紀律應用於搜尋：探索者是深層模組（輸入自然語言查詢，輸出含檔案行號的引文），精簡的回傳結果讓解題者保持乾淨的視窗，就像在全新脈絡中審查一樣

• 程式碼品質的收益以 Token 為尺度——這項紀律的經濟論據及其失效條件：DHH主張，只有在 token 稀缺期間，才值得打造代理程式可讀的架構，因為其歷史依據（以低成本進行人類修改）已不再適用

延伸出的文章#

• 單一通用代理程式 vs. 多代理程式程式碼架構——Sandcastle 中規劃者／實作者／審查者／合併者的分工，以及在全新脈絡中審查，被引用為模型進步後仍然有效的「脈絡隔離」專門化（結構性的智慧區域限制）；相較之下，苦澀教訓會消解人工設計的任務結構
• 撰寫者／審查者 vs. 代理程式對代理程式審查——以測量到的替代方法檢驗全新脈絡論據，並將其一分為二：新鮮脈絡可帶來智慧區域推理（本頁的主張，practitioner-opinion；唯一引用的數據取自相鄰任務——安全監控器的召回率在長篇良性脈絡下從 92% 降至 48%），而通常被認為可藉此消除的自有程式碼偏誤，實際上是模型家族的特性，清除脈絡也無法改變

開放問題#

• 「夠深」要多深？Pocock 的模組範例有數百行程式碼；Ousterhout 教科書中的範例更大。應該存在一個最佳範圍，但尚未明確指出。
• 對於連接埠／配接器程式碼庫，深層模組建議能否直接套用？「小介面」是連接埠，「豐富行為」是配接器。可能可以，但來源中沒有實際驗證。
• 重構成本與效益：在什麼情況下，值得對正常運作的程式碼庫執行「improve-code-base-architecture」？

資料來源#

• Full Walkthrough: Workflow for AI Coding — Matt Pocock
• Uncle Bob on Software Fundamentals in the Age of AI — Robert C. Martin 與 Matt Pocock，2026-08-19（practitioner-opinion；自動字幕逐字稿）：Ousterhout 在附錄中的對手對深層模組的認同、以主題發展脈絡為基礎的模組邊界論據，以及他讓代理程式建置的相依規則檢查器與 UML 架構檢視器