前言¶
用 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
