improve-codebase-architecture

improve-codebase-architecture 技能概覽

這個技能做什麼

improve-codebase-architecture 幫你找出架構上的阻力，並把淺層程式碼整理成更深層的模組，讓邊界更清楚、測試性更好，也更利於 AI 理解與導覽。如果你需要一個能從模組深度而不只是樣式整理的角度來檢視 codebase 的 improve-codebase-architecture skill，這個技能特別有用。

誰適合使用

適合拿來處理重構密集的工作、架構審查，以及那些因耦合過高、介面不清楚或邏輯散落各處而讓變更變得緩慢的 codebase。對已經重視設計語彙的團隊尤其合適，特別是當 codebase 裡有你希望技能遵循的 CONTEXT.md 和 docs/adr/ 決策時。

這個技能有什麼不同

這個技能對語言很有主張：它偏好使用 module、interface、seam、adapter、depth、locality 這類詞。這很重要，因為它能讓建議保持一致又可執行，不會滑向千篇一律的「把 service 整理一下」這種泛泛建議。

如何使用 improve-codebase-architecture 技能

安裝與初步閱讀

先使用 mattpocock/skills 集合中的 improve-codebase-architecture install 流程，然後先讀 SKILL.md。接著，在套用到自己的 repository 前，先查看 LANGUAGE.md、DEEPENING.md 和 INTERFACE-DESIGN.md。如果你的 repo 裡有 CONTEXT.md 或 docs/adr/，也要提早閱讀，因為它們會影響什麼才算是好的變更。

如何寫出好的提示詞

要給技能一個具體的架構問題，不要只說「幫我改進一下」。有效的輸入會點名模組範圍、痛點，以及限制條件。

好的提示詞：

• “Review src/billing/* for shallow modules and suggest deepening opportunities that preserve current behavior and reduce test complexity.”
• “Find refactoring candidates in the auth flow where a seam would improve locality without adding extra adapters.”
• “Assess whether packages/parser should be split or deepened for improve-codebase-architecture for Refactoring.”

較弱的提示詞：

• “Improve this repo.”
• “Make the architecture better.”

實際工作流程

先從 codebase 的一小段範圍開始，再請它找候選方案，不要直接要最終重寫。最佳的 improve-codebase-architecture usage 模式是：先找出阻力 → 點名淺層模組 → 分類依賴 → 選擇一個 seam → 提出能提升深度的最小變更。如果 repo 涉及 I/O、注入的 ports 或外部服務，也要告訴技能哪些依賴是 in-process、local-substitutable、remote-owned，哪些才是真正的 external。

輸入內容要包含什麼

請提供檔案路徑、目前行為，以及任何硬性限制，例如「必須保持 tests 綠燈」、「不能更動 public CLI flags」或「必須保留 ADR 決策」。如果你想調整 interface，也請說明你要的是最小化、彈性，還是為了常見呼叫端做最佳化。這會讓技能更容易做出有用的取捨分析，而不是只給出泛泛的重構點子。

improve-codebase-architecture 技能 FAQ

這比一般提示詞更好嗎？

是，當任務屬於架構層次而不是外觀整理時尤其如此。一般提示詞可以建議清理，但 improve-codebase-architecture 是以 depth、seams、adapters 和 locality 這些概念來推理，對真正的重構會更有幫助。

什麼情況下不適合？

如果你只是想改命名、格式化，或修一個單次 bug，就不用它。當你無法提供足夠的 repo context 來辨識 module interfaces、dependencies 和 constraints 時，它也會比較不適合。

初學者可以用嗎？

可以，但前提是他們能指出 codebase 裡的特定區域。初學者若能提供較小、具體的範圍，並附上相關檔案或資料夾，通常會得到更好的結果。

它適用於任何 stack 嗎？

大致上可以，因為這個技能是以架構為導向，而不是綁定某個 framework。當 repo 有清楚的 modules、tests，以及描述設計意圖的文件時，它的效果最好。

如何改善 improve-codebase-architecture 技能

提供更強的背景脈絡

品質提升最大的一步，是把精確的 module 或 subsystem 名稱說清楚，並指出它到底哪裡顯得太淺。也要包含目前的 interface、主要 dependencies，以及問題到底是 testability、coupling，還是 ownership 不清。

先請它給候選方案，再由你選擇

不要一開始就要求全面重寫。更好的 improve-codebase-architecture usage 是先請它提出 2–4 個能加深結構的候選方案，並附上優缺點與 seam 選項，然後再針對最好的那個往下追問。這樣第一輪輸出才會真正立基於 repository，而不是靠假設。

把最重要的限制講明白

如果你的優先順序是「保留行為」、「把 adapters 減到最少」，或「維持 public interface 穩定」，就直接說清楚。這個技能會根據你重視的是 leverage、migration cost，還是 interface 簡潔性，給出不同的建議。

用更精準的證據持續迭代

拿到第一輪輸出後，把它誤讀的檔案、漏看的依賴，或最難維護的 tests 回饋回去。當你把問題縮到單一的 module cluster，並要求它根據這些證據重新評估 seam，這個技能通常會表現得更好。