適合代理程式的深層模組

資料來源#

• Full Walkthrough: Workflow for AI Coding — Matt Pocock

摘要#

John Ousterhout 的 A Philosophy of Software Design 區分了深層模組（介面小、行為多）與淺層模組（介面小、行為少，但數量很多）。Matt Pocock 將這項區分應用於適合代理程式的程式碼庫：代理程式在深層模組程式碼庫中表現良好，因為測試邊界清楚、相依圖淺，而且開發者可以委派實作，同時把介面放在心上。如果你不加以約束，淺層模組的氾濫就是 AI 預設會產生的結果，最終形成無法審查、無法測試的程式碼庫。

深層與淺層#

• **淺層模組：**許多小檔案，每個檔案都公開許多小型函式，彼此之間形成密集的相依圖。測試邊界不清楚——你要模擬每個鄰近模組嗎？要隔離測試單元，卻漏掉整合錯誤嗎？AI 看不見全貌，也無法判斷抽象化應該放在哪裡。
• **深層模組：**一個較大的模組，公開介面小，內部邏輯卻很多。自然的測試邊界只有一個：公開介面。AI 不必穿越相依關係，就能看懂模組的作用。因為介面就是契約，所以實作可以委派出去。

為何代理程式特別受益#

1. **需要穿越的相依跳躍更少。**節省 Smart-zone 預算（見 Context Window Smart Zone）。
2. **測試邊界一目了然。**審查代理程式可以在介面層級驗證行為，不必微觀管理內部細節。
3. **實作可以委派。**Pocock 的「灰盒」模式——自行設計介面，再把實作交給代理程式。你保留對做什麼的模型，不必把注意力耗在如何做上。
4. **模組圖是有限的。**寫著「修改遊戲化服務、儀表板路由、課程路由」的 PRD 很具體；同一份 PRD 若套用在淺層程式碼庫上，可能會變成「修改 47 個檔案」。

風險：代理程式會逐漸走向淺層#

Pocock 的觀察：

「如果你不仔細看著 AI，它會產生一個看起來像[淺層模組]的程式碼庫。所以你在指導它時，真的、真的要非常小心。」

代理程式走向淺層的原因：

• 每項任務都很小；代理程式會做出能運作的最小變更
• 沒有全域模組圖時，代理程式不知道應該擴充哪個現有模組，因此會建立新的模組
• 「單一職責原則」被錯誤套用——代理程式把每個輔助函式都包進自己的檔案

解法有兩個面向：

1. 將模組圖保留在 PRD 中（見 Design Concept Grilling），讓代理程式知道要擴充什麼。
2. 定期執行重構，將淺層模組整併成深層模組。Pocock 有一項技能可處理這件事：improve-code-base-architecture——掃描程式碼庫，找出「架構改善候選項」（可以深化的相關模組群組），並為每一項提供論據與相依類別。

推送與拉取指令#

一項微妙但槓桿效應很高的架構選擇：要如何將程式碼標準與架構規則交付給代理程式。

模式	機制	時機
推送	始終位於上下文中（CLAUDE.md、系統提示）	審查代理程式——它們需要知道標準，才能拿來與程式碼比較
拉取	透過技能按需取得（代理程式在相關時自行擷取）	實作者代理程式——拉取可避免把不適用規則耗費在 Smart-zone 預算上

這也是為什麼乾淨的審查代理程式比同一上下文中的審查代理程式更聰明：實作者可以在需要時拉取規則；審查者則受益於規則已被推送，並且擁有乾淨的 Smart-zone 視窗來實際評估程式碼。

在全新上下文中進行審查#

如果實作使用了 80K 個 Smart-zone token，同一上下文的審查者就會在 dumb zone 中讀取差異。清除上下文並在全新環境中執行審查，就能恢復 Smart-zone 推理。Pocock 將此與模型選擇配對：實作使用 Sonnet，審查使用 Opus——「我需要的是智慧，然後才是它。」

Sandcastle 三代理程式模式#

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

1. 規劃者——從待辦清單中挑選 N 個平行議題
2. N 個實作者——每個議題一個，各自在自己的 git worktree 與 Docker sandbox 中工作；透過拉取技能取得程式碼標準
3. 審查者——針對每個實作者的差異，在全新上下文中執行；程式碼標準被推送到其系統提示中
4. 合併者——協調所有已核准的分支，修復型別／測試衝突

每個代理程式都在自己的 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「十個優秀 evals」在工程上的實例；兩者都是介面層級的持久驗證工件
• Verification as the New Bottleneck——當驗證成為瓶頸時，全新上下文中的模組介面審查，具體回答了 Fiona Fung 所提出的「誰來審查」
• Repository Exploration Subagent——FastContext 將深層模組／全新上下文的紀律應用於搜尋：探索者是深層模組（輸入自然語言查詢，輸出檔案行號引用），其精簡回傳讓解題者的視窗保持乾淨，就如同全新上下文的審查者

衍生內容#

• Single General Agent vs. Multi-Agent Coding Architecture——Sandcastle 的 Planner／Implementers／Reviewer／Merger 分工，以及在全新上下文中進行審查，被引用為能在模型改進後存續的「上下文隔離」專門化（結構性的 Smart-zone 限制）；相較之下，手工設計的任務結構會被苦澀教訓消解

待解決的問題#

• 「深」到什麼程度才算夠？Pocock 的範例模組有數百個 LOC；Ousterhout 的教科書範例更大。這裡存在一個甜蜜點，但尚未闡明。
• 對於 ports/adapters 程式碼庫，深層模組建議是否能順利移植？「小介面」就是 port；「大行為」就是 adapter。可能可以，但來源中沒有實際驗證。
• 重構成本與效益：什麼時候值得在一個正常運作的儲存庫上執行「improve-code-base-architecture」？

資料來源#

• Full Walkthrough: Workflow for AI Coding — Matt Pocock