改善程式碼庫架構
以 AI 的視角探索程式碼庫,找出架構摩擦點,發現提升可測試性的機會,並將模組加深的重構提案以 GitHub Issue RFC 的形式提出。
深層模組(John Ousterhout,《軟體設計哲學》)是指一個小型介面包藏大量實作的模組。深層模組更具可測試性、更易於 AI 瀏覽,並且讓你可以在邊界進行測試,而非深入內部。
流程
1. 探索程式碼庫
使用 subagent_type=Explore 的代理工具自然瀏覽程式碼庫。請勿遵循僵化的啟發式規則 — 以有機的方式探索,並記錄下你遇到摩擦的地方:
- 理解某個概念是否需要在多個小檔案之間來回跳轉?
- 哪些模組淺層到介面幾乎和實作一樣複雜?
- 哪些純粹函式只是為了可測試性而提取,但真正的錯誤卻隱藏在它們被呼叫的方式中?
- 緊密耦合的模組在哪裡產生了模組間接縫處的整合風險?
- 程式碼庫的哪些部分未經測試,或難以測試?
你所遇到的摩擦本身就是訊號。
2. 提出候選項目
提供一個編號列表,列出加深的機會。每個候選項目需包含:
- 叢集:涉及哪些模組/概念
- 為何耦合:共享的型別、呼叫模式、共同擁有的概念
- 依賴類別:請參閱 REFERENCE.md 中的四個類別
- 測試影響:哪些現有測試將被邊界測試取代
不要先提出介面。詢問使用者:「您想探索哪一個?」
3. 使用者選擇候選項目
4. 界定問題空間
在產生子代理之前,先為所選的候選項目撰寫一份面對使用者的問題空間說明:
- 任何新介面必須滿足的限制條件
- 它需要依賴的依賴項目
- 一個粗略的說明性程式碼草稿,以便將限制條件具體化 — 這不是提案,只是為了讓限制條件更具體
向使用者展示此說明,然後立即進入步驟 5。使用者可以在子代理並行工作時閱讀並思考問題。
5. 設計多個介面
使用代理工具並行產生 3 個以上的子代理。每個子代理必須為加深的模組提供一個截然不同的介面。
為每個子代理提供獨立的技術摘要(檔案路徑、耦合細節、依賴類別、隱藏了什麼)。此摘要獨立於步驟 4 中面對使用者的說明。給予每個代理不同的設計限制:
- 代理 1:「最小化介面 — 目標最多 1-3 個進入點」
- 代理 2:「最大化靈活性 — 支援多種使用案例與擴展」
- 代理 3:「為最常見的呼叫者最佳化 — 讓預設案例變得簡單」
- 代理 4(如適用):「針對跨邊界依賴,以連接埠與適配器模式進行設計」
每個子代理輸出:
- 介面簽章(型別、方法、參數)
- 使用範例,展示呼叫者如何使用
- 它內部隱藏了哪些複雜度
- 依賴策略(如何處理依賴 — 請參閱 REFERENCE.md)
- 取捨
依序呈現設計,然後以文字進行比較。
比較之後,提出你自己的推薦:你認為哪個設計最強以及原因。如果不同設計的元素可以很好地結合,提出一個混合方案。請抱持明確的意見 — 使用者想要的是明確的觀點,而不只是一個選項清單。
6. 使用者選擇介面(或接受推薦)
7. 建立 GitHub Issue
使用 gh issue create 將重構 RFC 建立為 GitHub Issue。使用 REFERENCE.md 中的範本。建立前無需請使用者審查 — 直接建立並分享網址。