improve-codebase-architecture skill 是什麼、怎麼用：掃描代碼庫找「加深模組」機會並出 HTML 報告

本文根據 mattpocock/skills 倉庫裏該技能的 SKILL.md 與倉庫 README 整理，資料核對於 2026-10-11。skills.sh 榜單當日顯示該技能累計安裝約 108.4 萬次；所在倉庫 mattpocock/skills 在 GitHub 約 28.4 萬 Star（同日數據）。技能內容會隨倉庫更新，以倉庫為準。

這個 Skill 做什麼

代碼庫用久了會積累一類問題：模組很多，但每個都很「淺」——接口幾乎和實現一樣複雜，調用方得了解一堆內部細節，測試難寫，智能體讀起來也費勁。improve-codebase-architecture 專門找這類地方。description：掃描代碼庫尋找「加深」的機會，以可視化 HTML 報告呈現，然後對你挑中的那一項做拷問式討論。它只能手動調用。

說明裏把目標說得很具體：發現架構上的摩擦，提出把淺模組變成深模組的重構，目的是可測試性和「對 AI 的可導航性」。它建立在同庫 codebase-design 技能的一套固定詞彙之上——模組、接口、深度、接縫（seam）、適配器、槓桿、局部性——並要求全程嚴格使用這些詞；同時參考項目的領域模型（術語表和 ADR）。

流程三步：探索代碼庫；把候選項寫成一份自包含的 HTML 報告，存在操作系統的臨時目錄裏，不往倉庫裏放東西；你選定其中一項後進入拷問循環，把這項重構的邊界、接口和遷移方式一點點問清。

怎麼安裝

improve-codebase-architecture 隨 mattpocock/skills 整套安裝。Claude Code 用插件（命令來自倉庫 README）：

text
claude plugin install mattpocock-skills@claude-plugins-official

Codex 先 codex plugin marketplace add mattpocock/skills 再 codex plugin add mattpocock-skills@mattpocock；Cursor、OpenCode 等用 npx skills@latest add mattpocock/skills，在列表裏勾選需要的技能。README 提醒兩點：插件和 skills.sh 兩種方式每個工具只選一種，否則每個技能會出現兩份；勾選時帶上 setup-matt-pocock-skills，並在每個倉庫裏先運行一次，它會問你用哪個 issue 跟蹤器、分診用哪些標籤、文檔存在哪裏——庫裏不少技能依賴這份配置，也會互相調用。

倉庫整體介紹和其他安裝方式，詳見本站《mattpocock/skills 是什麼、怎麼安裝：Matt Pocock 的工程師 Skills（grill-me、tdd、to-spec）》。

怎麼用

• 在項目根目錄輸入 /improve-codebase-architecture，等它出報告，用瀏覽器打開查看候選項和示意圖。
• 「只看 billing 目錄」——可以限定範圍，避免大倉庫掃描太久。
• 選一項後說「就做第 2 個」，它會開始追問；談定後可接 to-spec 或 to-tickets 落成任務。

目錄裏有一份 HTML-REPORT.md，規定報告的骨架、圖示和樣式。

適合誰 / 侷限

適合接手了有年頭的代碼庫、想找出最值得重構之處的工程師，也適合定期做架構體檢。它給的是基於「深模組」這一種設計觀的建議，不是唯一正確答案；掃描大型倉庫耗時也耗用量；它只提出並討論方案，不會自動動手重構。

注意事項

• 許可：MIT。
• 只讀掃描 + 寫臨時文件：報告寫在系統臨時目錄，不改倉庫。
• 依賴同庫的 codebase-design 與 grilling，需要整套安裝。