/improve-codebase-architecture 指令詳解 · Matt Pocock's Engineering Skills

指令用途

/improve-codebase-architecture 會尋找把 shallow module 深化的機會，產生視覺化的 HTML 報告，再針對你選定的候選進行追問。它以 /codebase-design 的 module、interface、depth、seam、adapter、leverage 與 locality 詞彙描述建議，目標是提升可測試性與 AI 導航性。

這就像有一個資深架構師在幫你審查程式碼庫，找出潛在的改進空間。

運作流程

先縮小範圍：若使用者指定 module、subsystem 或痛點，就以它為方向；否則先讀近期 git log --oneline，把最近反覆變更的熱點放在前面，而不是平均掃描整個 repo。
建立候選：讀取 CONTEXT.md 與相關 ADR，再由 agent 探索 shallow module、seam 滲漏、缺乏 locality 或難以透過 interface 測試的地方，並套用刪除測試。
產生報告：將 self-contained HTML 寫到 OS temp 目錄的 architecture-review-<timestamp>.html，用目前平台的方式開啟；報告使用 Tailwind CDN、必要時使用 Mermaid，並為每個候選提供 files、problem、solution、benefits、before/after visualisation 與 recommendation strength。
選擇項目：報告最後提出 top recommendation，然後詢問使用者要探索哪個候選；此階段不要先提出 interface。
深入追問：使用者選定後執行 /grilling，並由 /domain-modeling 同步更新 CONTEXT.md 的領域詞彙與必要決策。

實戰對話範例

範例：從熱點產生深化候選

You:
```
/improve-codebase-architecture
```
AI:
我會先讀近期 commit，找出反覆變更的熱點，再檢查 CONTEXT.md 與相關 ADR。

報告已產生：%TEMP%/architecture-review-2026-08-08T120000.html

候選 1：Order intake module 的 seam 滲漏
- Files：src/orders/*、tests/orders/*
- Problem：呼叫端必須知道資料庫查詢與重試細節。
- Solution：把這些行為收回小 interface 背後，增加 locality。
- Benefits：呼叫端與測試只需理解穩定的 interface。
- Strength：Strong
候選 2：Notification adapter 的 interface 過淺
- 比較兩個 adapter 方案，再決定真正的 seam。
- Strength：Worth exploring
你想探索哪個候選？
You:
```
探索候選 1。
```
AI:

接下來以 /grilling 追問 constraints、dependencies、seam 形狀與測試；需要新領域詞彙時，會由 /domain-modeling 更新 CONTEXT.md。

報告內容

每個候選至少包含：

涉及的 files 或 modules。
造成 friction 的 problem。
plain English 的 solution。
以 locality、leverage 與測試改善說明 benefits。
before / after visualisation，以及 Strong、Worth exploring 或 Speculative recommendation strength。
報告結尾的 top recommendation。

報告是 self-contained HTML，寫入 OS temp 目錄，不把探索產物放進 repo。圖表需要呈現 graph、flow 或 sequence 關係時可使用 Mermaid；其他 editorial 視覺可使用手繪 CSS/SVG。

何時不應該使用

只想直接實作功能：先用適合的規格或實作流程，不要先做架構調查。
還沒選定深化候選：報告階段只提出候選，不要提前設計 interface。
沒有真實 friction 的理論重構：沒有近期變更熱點或可觀察的維護痛點時，不要為了抽象而抽象。