improve-codebase-architecturelisted

# 改善程式碼庫架構 浮現架構摩擦並提出**深化機會**——把淺模組變成深模組的重構。目標是測試性與對 AI 的可導覽性。 這個指令_受_專案的領域模型_啟發_，並建立在共享的設計詞彙上： - 執行 `/codebase-design` 技能取得架構詞彙（**模組**、**介面**、**深度**、**接縫**、**轉接器**、**槓桿收益**、**局部性**）及其原則（刪除測試、「介面就是測試表面」、「一個轉接器 = 假設性接縫，兩個 = 真實」）。在每個建議中精確使用這些術語——不要漂移成「component」「service」「API」或「boundary」。 - `CONTEXT.md` 中的領域語言為好接縫命名；`docs/adr/` 中的 ADR 記錄了這個指令不該重新爭論的決策。 ## 流程 ### 1. 探索 **掃描前先定範圍——YAGNI。** 深化模組的回報來自於讓未來對它的變更更容易，所以對程式碼庫最近變更的部分要特別加權。在看你之前先決定*往哪看*： - 如果使用者指定了方向——一個模組、一個子系統、一個痛點——採用它，並跳過下面的推斷。 - 否則，往回走一段良好的 commit 歷史（`git log --oneline`）找出程式碼庫的熱點——那些一直出現的檔案與區域——讓那些路徑先吸引你的注意力。如果變更四散、沒有清楚熱點，就擴大網子。 先讀專案的領域詞彙表（`CONTEXT.md`）與你要觸及區域中的任何 ADR。 然後用 Agent 工具、`subagent_type=Explore` 走訪程式碼庫。不要遵循僵硬的啟發式——有機地探索，並記下你感到摩擦的地方： - 哪裡理解一個概念需要在許多小模組之間彈跳？ - 哪裡有模組**淺**——介面幾乎跟實作一樣複雜？ - 哪裡有純函式只是為了可測試性被抽出來，但真正的 bug 藏在它們如何被呼叫（沒有**局部性**）？ - 哪裡有緊密耦合的模組跨越接縫洩漏？ - 程式碼庫的哪些部分沒有測試，或難以透過它們目前的介面測試？ 對任何你懷疑是淺的東西套用**刪除測試**：刪掉它會集中複雜度，還是只是搬移？「會，集中」就是你要的訊號。 ### 2. 以 HTML 報告呈現候選 把自足的 HTML 檔案寫到作業系統的暫存目錄，讓什麼都不落進 repo。從 `$TMPDIR` 解析暫存目錄，回退到 `/tmp`（Windows 用 `%TEMP%`），寫到 `<tmpdir>/architecture-review-<timestamp>.html`，讓每次執行都有新檔案。為使用者開啟它——Linux 用 `xdg-open <path>`、macOS 用 `open <path>`、Windows 用 `start <path>`——並告訴他們絕對路徑。 報告使用 **Tailwind via CDN** 做佈局與樣式、**Mermaid via CDN** 做圖表，在圖/流程/序列能可靠傳達結構時使用。把 Mermaid 與手工打造的 CSS/SVG 視覺混用——當關係是圖形狀時用 Mermaid（呼叫圖、相依、序列），當你想要更具編輯性的東西時用手工的 div/SVG（質量圖、剖面、摺疊動畫）。每個候選都有**前/後視覺化**。要視覺化。 每個候選渲染一張卡片： - **檔案**——涉及哪些檔案/模組 - **問題**——為什麼目前架構造成摩擦 - **解決方案**——用白話描述會改變什麼 - **好處**——以局部性與槓桿收益來解釋，以及測試