前言¶
用 AI 寫代碼之後，倉庫變複雜的速度往往比以前更快。功能能跑，測試也能綠，但模塊接口越鋪越寬、概念散落在好幾個小文件裏、真正難測的地方仍然測不到——這類問題不會在某次 git commit 裏突然爆發，而是慢慢把後續改動拖慢。
常見做法有兩種。一種是憑經驗做一次大重構，風險高、難評審；另一種是直接讓 Agent「把架構改好」，它很容易按自己的口味重寫一堆文件，卻說不清改動值不值得、跟現有決策有沒有衝突。Matt Pocock 維護的 improve-codebase-architecture 走第三條路：先做一次架構普查，把「值得加深的模塊」寫成可視化報告，由你挑選候選，再進入追問（grilling），全程不改業務代碼。
它收錄在 mattpocock/skills 倉庫的 skills/engineering/improve-codebase-architecture/ 目錄，和同倉庫的 codebase-design、grilling、domain-modeling 配套使用。作者自己的說明頁在 aihero.dev。
這是什麼¶
一句話定位：掃描代碼庫裏的加深機會（deepening opportunities）——把淺模塊變成深模塊的重構候選——寫成一份獨立 HTML 報告，然後對你選中的那一項做設計追問。目標是可測試性，以及讓 AI 更容易在倉庫裏導航。
官方 SKILL.md 的 frontmatter 如下：
- name：
improve-codebase-architecture - description：掃描代碼庫中的加深機會，以可視化 HTML 報告呈現，再對你挑中的那一項做 grilling
- disable-model-invocation：
true（Agent 不會自己調用；必須在對話裏輸入/improve-codebase-architecture）
倉庫 README 把它歸爲 User-invoked 技能：只能由你主動喚起，用來編排流程，而不是讓模型在寫功能時自動插手。作者強調它是普查（survey），不是救援（rescue）：定期跑、給後續工作排隊；面對多年泥球倉庫，它能找出真實候選，但不會替你把泥解開。
設計詞彙來自同倉庫的 /codebase-design，核心是 John Ousterhout 在《A Philosophy of Software Design》裏說的深模塊：大量行爲藏在小而穩定的接口後面。配套技能同時寫明：他們不用「實現行數 / 接口行數」當深度指標（那種算法會鼓勵把實現寫長），而用 depth-as-leverage——調用方每學會一點接口，能換回多少行爲。
核心功能與亮點¶
根據官方 SKILL.md、同目錄的 HTML-REPORT.md，以及作者站點說明，能力可以分成下面幾塊。
1. 先定範圍，再有機探索¶
流程第一步是 Explore，並且明確寫了 YAGNI：加深一個模塊的收益，取決於以後還會不會改它。因此掃描要偏向最近在動的代碼：
- 你點名了方向（某個模塊、子系統、痛點）——就按你說的看，不再自行推斷。
- 否則先讀一段
git log --oneline，找反覆出現的熱點路徑；改動太散、沒有熱點，再擴大範圍。
接着讀項目的領域詞表 CONTEXT.md，以及相關區域的 ADR（docs/adr/）。領域詞給「好的縫」（seam）起名字；ADR 記錄不該反覆翻舊賬的決策。這兩類文件不是運行前提，有則用領域名詞寫候選（例如「加深 Order intake module」），沒有也能跑。
探索本身不套死板啓發式。官方要求記下你「走代碼時感到的摩擦」，重點包括：
- 理解一個概念，要在許多小模塊之間來回跳。
- 模塊是淺的：接口幾乎和實現一樣複雜。
- 純函數被抽出去只是爲了好測，真正的 bug 藏在調用方式裏（沒有 locality）。
- 緊耦合模塊從縫裏泄漏。
- 當前接口測不到，或很難測。
對疑似淺模塊要做 deletion test（刪除測試）：刪掉它，是把複雜度集中到更小的接口後面，還是隻是把複雜度挪到調用方？只有「會集中」的才值得做成卡片。
2. 輸出一份不進倉庫的 HTML 報告¶
候選不以長篇 Markdown 列表交差，而是寫成單文件、自包含的 HTML，放到操作系統臨時目錄，避免污染倉庫。臨時目錄取 $TMPDIR，沒有則回落到 /tmp（Windows 上是 %TEMP%），文件名形如 architecture-review-*.html，每次運行一份新文件。寫完後按平臺打開（Linux xdg-open、macOS open、Windows start），並告訴你絕對路徑。
報告用 CDN 加載 Tailwind 和 Mermaid：關係圖（調用圖、依賴、時序）用 Mermaid；質量圖、剖面、摺疊動畫等更「編輯向」的圖用手寫 HTML/CSS/SVG。HTML-REPORT.md 規定：每條候選都要有 before / after 對照，圖是主體，文字要短。
每張候選卡片包含：
- Files：涉及哪些文件 / 模塊
- Problem：當前架構爲什麼摩擦
- Solution：會改什麼（白話，此時還不設計具體接口）
- Benefits / Wins：用 locality 和 leverage 解釋，以及測試會怎樣變簡單
- Before / After：並排示意圖
- Recommendation strength：
Strong/Worth exploring/Speculative三種徽章
報告末尾有 Top recommendation：優先做哪一條、爲什麼。如果某條候選和已有 ADR 衝突，只有摩擦大到值得重開 ADR 時才列出，並加警告；禁止把 ADR 已經否決的理論重構全部再列一遍。
用詞有硬約束。架構側必須用 /codebase-design 的詞：module、interface、depth、seam、adapter、leverage、locality；不要改口成 component、service、API、boundary。領域側用 CONTEXT.md 裏的名字。
報告寫完後先停下來問：「Which of these would you like to explore?」在你選定之前，不提出接口方案，也不改代碼。
3. 選定後再 grilling，決策不是 diff¶
你挑中一條之後，纔會調用 /grilling，沿決策樹追問：約束、依賴、加深後的模塊形狀、縫後面放什麼、哪些測試還能活下來。這一步的產出是決策，不是補丁。作者站點寫的後續主流程是：決策 → /to-spec → /to-tickets → /implement。
追問過程中會調用 /domain-modeling，把領域模型寫進倉庫：
- 加深後的模塊名了一個
CONTEXT.md裏沒有的概念 → 補進CONTEXT.md（沒有這個文件就現建）。 - 對話裏把含糊術語磨清楚 → 當場更新
CONTEXT.md。 - 你用「以後還用得上」的理由否決某條候選 → 可以問要不要寫成 ADR，避免下次審查再提；「現在不值得做」這類短暫理由則不寫。
- 想看加深後模塊的多種接口 → 再跑
/codebase-design，用它的 design-it-twice：並行子 Agent 給出幾套差別很大的接口（極簡、靈活、爲調用方優化、ports & adapters 等），再按深度、locality、縫的位置比較。
注意：skills.sh 摘要裏有一條「生成 GitHub Issue RFC」。當前倉庫裏的 SKILL.md 沒有這一步；把方案落成工單，是後面 /to-spec、/to-tickets 的事，不要指望本 Skill 直接開 Issue。
安裝與啓用¶
該 Skill 是通用 SKILL.md 格式，Cursor、Claude Code、Codex CLI 等支持 Agent Skills 的工具都可以裝。Matt Pocock 倉庫提供兩種安裝哲學，不要兩種都裝，否則每個 Skill 會出現兩份。
方式一：Claude Code 官方插件（整套、只讀、隨作者更新）¶
claude plugins install mattpocock-skills
也可以在 Claude Code 會話裏執行：
/plugin install mattpocock-skills
插件在 Claude Code 官方 marketplace 裏，不必先加源。這會裝上整套工程技能，而不只這一條。
方式二：skills CLI（拷貝成可改的文件，Cursor / Codex / 其他 Agent）¶
只裝這一條（skills.sh 頁面 給出的命令）：
npx skills add https://github.com/mattpocock/skills --skill improve-codebase-architecture
簡寫也可以：
npx skills@latest add mattpocock/skills --skill improve-codebase-architecture
安裝時可以選擇目標 Agent。Cursor 項目級目錄一般是：
.cursor/skills/improve-codebase-architecture/SKILL.md
或跨工具的：
.agents/skills/improve-codebase-architecture/SKILL.md
按 Cursor 文檔，項目級還會掃描 .agents/skills/、.cursor/skills/；用戶級對應 ~/.agents/skills/、~/.cursor/skills/。爲兼容其他工具，Cursor 也會讀 .claude/skills/、.codex/skills/。Claude Code 項目級是 .claude/skills/，用戶級是 ~/.claude/skills/。
整套安裝時，官方 README 要求把 setup-matt-pocock-skills 一併勾上，然後在每個倉庫跑一次 /setup-matt-pocock-skills（選 Issue 跟蹤器、triage 標籤、文檔存放位置）。只裝本 Skill 也能做掃描；但完整鏈路還依賴同倉庫的 codebase-design、grilling、domain-modeling，建議一起裝。
啓用後在 Agent 對話輸入 /improve-codebase-architecture。frontmatter 裏 disable-model-invocation: true，描述「幫我重構架構」時模型不會自動套用它，必須顯式用斜槓命令。
典型用法示例¶
日常保養（不指定範圍）¶
在倉庫根目錄喚起即可。Skill 會先看近期提交熱點，再探索、出報告：
/improve-codebase-architecture
作者建議隔幾天跑一次，放在功能開發主循環之外，用來給後續工作排隊，而不是當場改代碼。
大改動之前（官方認爲最有效的提示）¶
手裏已經有一份即將開工的 spec 時，把審查對準「怎樣讓這次改動變容易」：
/improve-codebase-architecture
我們接下來要做的是：<把 spec 或需求貼進來>
請只看這次改動會碰到的模塊，問：how can we make this change easy?
出 HTML 報告後先停，不要直接 grilling。
官方 Explore 規則：你點了名，就不要再全庫漫遊。
只看報告、先不要追問¶
作者 FAQ 裏最響的抱怨是：較弱的模型會跳過報告，對着第一個念頭連問幾十上百個問題。Skill 設計是「先報告、你選了再 grill」，但目前沒有單獨的 no-grill 模式。可以在喚起時寫明：
/improve-codebase-architecture
don't grill me, just show the report.
看完報告之後¶
- 打開臨時目錄裏的
architecture-review-*.html（需要能訪問 Tailwind / Mermaid 的 CDN，否則可能是無樣式的原始 HTML）。 - 只選 一條 候選進入當次會話。作者說明：報告、grilling、領域文檔修改和代碼改動擠在同一窗口，會把上下文塞滿；報告文件只活在臨時目錄，真正要帶走的是「選中的那條候選」本身。
- grilling 得出決策後，用
/to-spec寫成 spec，其餘候選變成獨立 ticket，以後再撿。不要從報告直接跳到實現。
一份合格運行的自檢（作者站點的 “It’s working if”）：
- 候選用的是領域概念，不是編出來的類名。
- 候選集中在最近改過的文件，而不是倉庫死角。
- 運行期間業務代碼沒動，新文件只有臨時目錄裏的 HTML。
- 出完報告會停下來問你選哪條。
- 每張卡片用 locality / leverage 解釋收益，並說明測試會怎樣變簡單。
- 用站得住的理由否決時，會提議寫成 ADR。
適用場景與注意事項¶
適合
- 倉庫已經在迭代，想定期攔住結構腐爛（作者說的 routine upkeep）。
- 大功能開工前，先問「怎樣讓這次改動變容易」。
- 結構不一致、或大量 vibe coding 留下的倉庫，想先看清形狀（brownfield audit）。
- 準備補測試，但代碼當前測不了：先找缺失的 seam，再對着接口寫測試。
不要拿它當
- 自動重構工具。它明確不改代碼；重構發生在另一次會話、走正常的 spec / ticket / implement。
/codebase-design的替代品。後者是詞表和設計紀律（model-invoked），負責「已經選定的模塊怎麼加深」；本 Skill 是普查，負責「該把什麼放到設計臺上」。拿/codebase-design當「去做」的命令，是已知失敗模式：它沒有自己的流程，Agent 會發明一套並長時間空轉。- 巨型工作的路線圖。跨多次會話的規劃用
/wayfinder。 - 具體 bug 的診斷。那是
/diagnosing-bugs；只有發現「鎖不住 bug 是因爲沒有好的 seam」時，纔會回到這裏。
已知限制（以作者 FAQ 和 SKILL.md 爲準）
- 幾乎不會告訴你「倉庫挺好」。技能被寫成要產出 findings；防禦手段是徽章——若全部是
Speculative，等於它在說「沒找到真正值得做的」。 - HTML 依賴 CDN。離線或安全策略要求 SRI 時，Tailwind / Mermaid 可能加載失敗，報告變成無樣式、無圖的原始 HTML。Agent 自己看不到渲染結果。變通是改口要求內聯 CSS 和手寫 SVG。這是仍未關閉的 rough edge。
- 探索步驟點名了 Claude Code 的
Agent工具（subagent_type=Explore）。沒有這套工具的 harness（例如部分 Codex 環境）仍能跑，但並行探索可能被跳過，掃描沒那麼充分。與 harness 無關的改寫已有人提議，官方寫明尚未合併。 - 沒有附帶 TypeScript 落地手冊。它會告訴你加深發生在哪、縫後面該放什麼；如何落到 package / 目錄結構，目前要你自己做。
- 對失控老倉庫能力有限。作者承認：結構尚可的大倉庫上它很強；「八年遺留、完全失控」的項目，用戶反饋是幫一點忙但不夠。若倉庫連共享詞表都沒有，先用
/grill-with-docs建立CONTEXT.md和 ADR，再跑本 Skill，輸出會好得多。
小結¶
improve-codebase-architecture 把「AI 如何做架構審查」收成一條可重複的流程：按熱點探索 → 用刪除測試過濾淺模塊 → 臨時目錄裏出可視化報告 → 你選一條再 grilling → 決策進 spec / ticket，而不是當場改代碼。它治理的是技術債的排隊和命名，不是替你完成重構。
和同倉庫其他工程技能一樣，它假設你願意維護一份領域詞表，並接受「先對齊、再動手」。隔幾天跑一次、大改前對準 spec 問一句 how can we make this change easy，比讓 Agent 自由發揮一次「優化架構」要可控得多。
官方地址：
https://github.com/mattpocock/skills/tree/main/skills/engineering/improve-codebase-architecture
作者說明：
https://www.aihero.dev/skills-improve-codebase-architecture
安裝索引：
https://skills.sh/mattpocock/skills/improve-codebase-architecture
