进阶 约 25 分钟 2026-10-14 02:31:17 · 31 阅读

improve-codebase-architecture 实操:让 AI 定期给你的代码库做一次架构体检

代码越写越乱,AI 只会让它乱得更快

编码代理把写代码的速度提上去之后,下一个挨骂的就是代码本身:三个月前还能看懂的模块,经过几十轮「帮我加个小功能」之后,调用链长了一倍,谁也不敢动。mattpocock/skills 这个仓库(GitHub 28 万+ star,MIT 协议;选题入库时是 282,647,2026 年 10 月中旬实查已经涨到 289,299,以仓库页为准)给自己的定位写在 README 第一段:not vibe coding。作者 Matt Pocock 是 TypeScript 社区写《Total TypeScript》的那位,这套技能是他每天自己用的工程纪律,其中 improve-codebase-architecture 只干一件事:扫一遍代码库,把值得「深化」的模块找出来,摆进一份可视化 HTML 报告,等你挑中一个,再追着问到底。

README 里引了 Kent Beck 的一句话作为整个仓库的立意:「Invest in the design of the system every day.」这个技能就是那个「每天」里管架构的部分。本篇依据该仓库的 SKILL.md、HTML-REPORT.md 与根 README 整理(属于 AI 编程实操系列),安装命令、流程步骤、报告格式全部出自原文。

先补一课:什么叫深、什么叫浅

这个技能的所有判断都建立在同一仓库另一个技能 codebase-design 定义的词汇表上,先把这套话术学会,后面的报告才看得懂。核心只有一个对比:深模块是小接口后面藏着大量行为,浅模块是接口几乎和实现一样复杂。它刻意不用「组件」「服务」「API」「边界」这些词——SKILL.md 原文要求 "Use these terms exactly in every suggestion, and don't drift into "component," "service," "API," or "boundary."",理由来自 README 引用的 Eric Evans《Domain-Driven Design》:所有人都从同一个领域模型里取词,沟通才不浪费。

图里这套画法就是词汇表原文 ASCII 示意图的转绘,深浅的差别一眼可见:

深模块与浅模块对比图

深模块 vs 浅模块:深度衡量的是接口面积,不是实现行数(依据 codebase-design SKILL.md 绘制)

词汇表里最值钱的是两条判据。一条是「接口」的定义比类型签名宽得多:

Interface: everything a caller must know to use the module correctly: the type signature, but also invariants, ordering constraints, error modes, required configuration, and performance characteristics.

另一条是删除测试(the deletion test),判断一个模块是不是白吃饭的 pass-through:想象把它删掉,如果复杂度凭空消失,它就是个转发壳;如果复杂度散落到 N 个调用点重新长出来,它才配存在。还有一条关于接缝(seam,借自 Michael Feathers)的:one adapter means a hypothetical seam, two adapters means a real one——只有一个实现却先抽了接口,那道缝是假想的;两个 adapter 才证明这里真的会换实现。README 里给过一个术语收敛效果的对照例子,原文是 "There's a problem when a lesson inside a section of a course is made 'real' (i.e. given a spot in the file system)",收敛成一个词之后变成 "There's a problem with the materialization cascade"——这个词从此进 GLOSSARY.md,人和代理都用它。

把它装进你的代理

仓库支持五种代理宿主,安装命令各一句(README 原文照抄):

# Claude Code(插件自更新)
claude plugin install mattpocock-skills@claude-plugins-official

# Codex
codex plugin marketplace add mattpocock/skills
codex plugin add mattpocock-skills@mattpocock

# GitHub Copilot(CLI 与 VS Code)
copilot plugin marketplace add mattpocock/skills
copilot plugin install mattpocock-skills@mattpocock

# Gemini CLI(手动更新,重跑两条即更新)
gemini skills install https://github.com/mattpocock/skills.git --path skills/engineering
gemini skills install https://github.com/mattpocock/skills.git --path skills/productivity

# 其它代理 / 想要可编辑副本(cursor、opencode、windsurf 等)
npx skills@latest add mattpocock/skills -a <agent>

两个坑写在前面。其一,README 明确警告插件和 skills.sh 两条通道只能选一条,"Pick one per agent, because installing both gives you every skill twice"——装重了每个技能出现两份,代理会犯选择困难。其二,skills.sh 装的是可编辑副本,不会自更新,要靠 npx skills@latest update 手动拉新;插件方式则各自自动更新。

装完先在每个仓库跑一次 /setup-matt-pocock-skills,它会问三件事:issue tracker 用哪个(GitHub / GitLab / 本地 markdown 文件 / 其它,个人项目选本地 markdown 就够,工单会落在 .scratch/ 目录下)、triage 标签是否沿用默认五角色、领域文档放哪(默认仓库根目录一个 GLOSSARY.md 加 docs/adr/)。配置结果写进 docs/agents/ 供所有技能读取,这个架构技能跑起来要读的 GLOSSARY.md 和 ADR 位置就来自这里。

跑起来:勘察、报告、追问三段

SKILL.md 把这个技能的执行分成三段,一段比一段介入得深:

三阶段流程图

完整链路:Explore 定范围 → HTML 报告摆候选 → Grilling 追问循环(依据 SKILL.md Process 一节绘制)

第一段勘察讲究 YAGNI,原文是 "Scope before you scan: YAGNI."——深化一个模块的收益是让未来的改动更容易,所以最近常改的文件权重最高。用户点名了方向就直接用;没点名,就回滚一段 git log --oneline 的提交历史找热点路径,让热点牵引注意力。开工前先读项目自己的 GLOSSARY.md 和相关区域的 ADR,然后派一个子代理去逛代码库,不带死板启发式,凭体感记摩擦点。原文给的五个摩擦问题值得原样抄在这里:理解一个概念要不要在多个小模块之间来回跳?哪里存在接口几乎和实现一样复杂的浅模块?哪里为了可测性抽了纯函数、真正的 bug 却藏在调用方式里(没有 locality)?哪些紧耦合模块在接缝处互相漏?哪部分代码没测试、或者隔着现有接口根本没法测?可疑对象一律过删除测试。

第二段把候选写进一份自包含的 HTML 报告。文件落在系统临时目录而不是仓库里,文件名格式 architecture-review-<timestamp>.html,每次跑都是新文件;Tailwind 和 Mermaid 走 CDN,报告本身零构建。每个候选一张卡片,报告收尾给一个 Top recommendation。写完之后这个技能只问一句 "Which of these would you like to explore?"——SKILL.md 在这里用大写强调 Do NOT propose interfaces yet:摆问题阶段不许顺手设计接口,那是下一段的事。

第三段用户挑中候选后才开场:调用同仓库的 grilling 技能走决策树,把约束、依赖、深化后的模块形状、接缝后面放什么、哪些测试能活下来一条条问清;边问边调 domain-modeling 技能维护领域模型。SKILL.md 给了三个很具体的落地动作:给深化模块起的名字不在 GLOSSARY.md 里,就当场补词条(文件不存在就顺手创建);谈话把某个模糊术语谈清楚了,当场更新词条;用户用一个硬理由否掉候选,就提议记一条 ADR,原文话术是 "Want me to record this as an ADR so future architecture reviews don't re-suggest it?"——但只在理由值得留给未来的探索者时才提,"not worth it right now" 这种临时理由不配一条 ADR。

报告本身长什么样

报告格式在同目录的 HTML-REPORT.md 里单独规定(6.6 KB,比 SKILL.md 还长),立场是图承担信息量、文字从简:"No paragraphs of explanation. If the diagram needs a paragraph to be understood, redraw the diagram."。卡片结构如下:

候选卡片结构解剖图

候选卡片解剖:三档推荐徽标、文件清单、Before/After 对照图、一句话问题与方案、Wins 与 ADR 警示条(依据 HTML-REPORT.md 绘制)

推荐强度只有三档:Strong、Worth exploring、Speculative,配色固定翡翠 / 琥珀 / 石板灰。图的画法给了五种模式混用:依赖和调用流用 Mermaid flowchart(示例代码原文如下),Mermaid 布局不听话就手绘 div 盒子加 SVG 箭头,分层穿透用横条 cross-section,接口面积和实现面积的比例用 mass diagram,调用树收拢用 call-graph collapse。

flowchart LR
  A[OrderHandler] --> B[OrderValidator]
  B --> C[OrderRepo]
  C -.leak.-> D[PricingClient]
  classDef leak stroke:#dc2626,stroke-width:2px;
  class C,D leak

措辞也有铁律,Use exactly 一行和 Never substitute 一行对照着读:必须用 module、interface、depth、seam、adapter、leverage、locality;禁止用 component、service、unit 替代 module,禁止用 API、signature 替代 interface,禁止用 boundary 替代 seam。连 Wins 栏怎么写都规定了:每条不超过六个词,必须用词汇表里的词,示范句是 "locality: bugs concentrate in one module" 和 "leverage: one interface, N call sites",而 "easier to maintain"、"cleaner code" 这种没有定义的词不许出现。与既有 ADR 冲突的候选只在摩擦真实到值得重开时标注,警示条格式原文给的是 "contradicts ADR-0007, but worth reopening because…"。

它不做什么

几条边界都写在原文里,用之前心里有数。它是用户手动触发的技能,SKILL.md 的 frontmatter 里写着 disable-model-invocation: true,代理不会自作主张去跑,必须人敲 /improve-codebase-architecture。README 对它的能力上限有一句很诚实的话:

It is a survey, not a rescue: on a genuinely old codebase it will find real candidates, but it won't untangle the mud for you.

它是勘察不是救援,真成一锅粥的老代码,它能找出该深化的候选,不会替你把泥球解开——解球靠的是后面的 grilling 追问和你自己下的决心。报告阶段不设计接口(前文的 Do NOT propose interfaces yet),词汇和流程又依赖同仓库的 codebase-design、grilling、domain-modeling 三个技能配套,所以单独把这一个技能拷走意义不大。运行节奏 README 给的是作者本人的习惯:每隔几天在代码库上跑一遍,"I recommend running it on your codebase once every few days"。另外它对环境有个隐含要求——热点分析靠 git 提交历史,GLOSSARY.md 和 ADR 靠 setup 阶段配好的目录,一个没有提交习惯、没有领域文档的仓库跑它,第一段勘察就空转。

来源与延伸

本文流程、命令与引文依据 mattpocock/skills 仓库 main 分支的根 README、skills/engineering/improve-codebase-architecture/SKILL.md 与 HTML-REPORT.md(2026 年 10 月抓取)整理,配图为依据原文绘制,版权归原作者所有。同仓库 implement-spec 技能负责这条流水线的实现端,另见站内教程。

评论 (0)