# improve-codebase-architecture：让Claude给你的代码库做“深度体检”的Skill，拆开看它怎么写的 ## 概述 本期是 Skills 生态系列第 2 轮，做单个热门 Skill 的深度拆解。主角是 `improve-codebase-architecture`——来自 Matt Pocock（Total TypeScript 创始人）的 `mattpocock/skills` 仓库，在 skills.sh 全时段排行榜上以 **747.2K 安装**位列第 5，仅次于同仓库的 grill-me（911.2K）和官方 frontend-design（796.7K）。此前已拆解过 grill-me、tdd、agent-browser 等明星 Skill，本期避开它们，选这个“架构审查”类 Skill，原因有二：一是它是整个仓库里**文件结构最复杂**的一个（SKILL.md 之外还带一份 6.7KB 的 HTML-REPORT.md 输出规范），二是它示范了 Skills 生态里最重要的进阶写法——**Skill 组合**。本文基于其 GitHub 仓库当前 main 分支的真实文件逐段讲解，读完你可以照着写一个自己的版本。 ## 本期主角在生态中的位置 先看 skills.sh 全时段安装榜的头部格局（数据抓取于 2026-08-28）： | 排名 | Skill | 来源仓库 | 安装量 | |------|-------|----------|--------| | 1 | find-skills | vercel-labs/skills | 3.0M | | 2 | grill-me | mattpocock/skills | 911.2K | | 3 | frontend-design | anthropics/skills | 796.7K | | 4 | grill-with-docs | mattpocock/skills | 775.3K | | **5** | **improve-codebase-architecture** | **mattpocock/skills** | **747.2K** | | 6 | tdd | mattpocock/skills | 722.0K | | 7 | agent-browser | vercel-labs/agent-browser | 702.8K | | 8 | setup-matt-pocock-skills | mattpocock/skills | 663.0K | | 9 | vercel-react-best-practices | vercel-labs/agent-skills | 647.0K | | 10 | handoff | mattpocock/skills | 628.2K | 榜单前 10 里有 6 席属于同一个仓库——mattpocock/skills 已经不是“一个热门 Skill”，而是一个**套件**。这个仓库的设计本身值得先讲清楚，因为主角 Skill 的每一处设计都建立在套件架构之上。 ## 仓库级设计：先理解“谁能调用谁” mattpocock/skills 的 README 把所有 Skill 按一个轴分类：**谁能调用它**。 - **User-invoked（用户触发）**：只有你输入 `/grill-me` 这样的斜杠命令才会启动，职责是**编排**（orchestrate）。 - **Model-invoked（模型触发）**：你可以手动调，模型在任务匹配时也会**自动伸手拿**，职责是承载**可复用的纪律**（reusable discipline）。 配套一条铁律：**user-invoked Skill 可以调用 model-invoked Skill，但永远不调用另一个 user-invoked Skill**。这避免了斜杠命令之间互相拉扯形成的调用迷宫。`improve-codebase-architecture` 的 frontmatter 正是这条铁律的落地： ```yaml --- name: improve-codebase-architecture description: Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick. disable-model-invocation: true --- ``` 三个字段三个设计决策： 1. **description 写成了三段式流程摘要**——“扫描 → 出 HTML 报告 → 对你选中的候选拷问”。注意它不是写“帮助改进代码架构”这种模糊能力描述，而是把**交互合同**写进了 description：用户装完后瞄一眼就知道自己将经历什么。 2. **`disable-model-invocation: true`**——明确禁止模型自动触发。架构审查是一个“重”操作（要跑子代理探索代码库、生成 HTML 文件），绝不该在用户只想改个 bug 时被自动拉起。这是“重 Skill 必须显式触发”的范本。 3. **没有多余的 frontmatter 字段**——整个文件头部 4 行，把元数据成本压到最低。 ## 逐段拆 SKILL.md：三个阶段的流水线 SKILL.md 正文约 6KB，结构是一条清晰的三段流水线。以下逐段讲解（引用均为仓库原文的中文转述或原句）。 ### 开头两段：先“借”词汇，再干活 正文第一句就定义了目标："Surface architectural friction and propose **deepening opportunities** — refactors that turn shallow modules into deep ones. The aim is testability and AI-navigability."（浮现架构摩擦点，提出把浅模块变成深模块的重构机会，目标是可测试性和 AI 可导航性。） 紧接着立刻锚定两个外部知识源： - 跑 `/codebase-design` Skill 拿到架构词汇表：**module、interface、depth、seam、adapter、leverage、locality**，并且要求“在每一条建议里精确使用这些词——不许漂移到 component、service、API、boundary"。 - 读项目里的 `CONTEXT.md`（领域术语表）和 `docs/adr/`（架构决策记录），“这个命令不该重新翻案的决策”。 这是第一处值得抄的设计：**Skill 不自带知识，而是引用另一个 Skill 作为“字典”**。词汇表单独放在 model-invoked 的 codebase-design 里，意味着你写代码时模型也会自动用这套词——一份词汇，两处生效。 ### 阶段 1：Explore——先定范围，再扫描 这一阶段的第一行小标题就是态度："**Scope before you scan — YAGNI.**"（先定范围再扫描——你不需要那用不上的。）逻辑是：加深一个模块的收益在于让未来的修改变容易，所以要给**最近频繁变动的代码**加权。具体做法： - 用户点名了方向（某个模块、子系统、痛点）就直接用，跳过推断； - 否则回溯一段 `git log --oneline`，找出反复出现的“热点”文件，让这些路径优先吸引注意力； - 变更如果散落无热点，才扩大扫描网。 然后派 `subagent_type=Explore` 的子代理去**有机地**走读代码（Skill 明确写"不要死板地套启发式”），找四类摩擦：理解一个概念要在多个小模块间跳来跳去的地方；接口复杂度逼近实现的**浅模块**；为了可测试性抽出纯函数、但真正的 bug 藏在调用方（没有 **locality**）的地方；以及测试不到或很难从现有接口测到的地方。 点睛之笔是**删除测试**（deletion test）："Apply the deletion test to anything you suspect is shallow: would deleting it concentrate complexity, or just move it?"（对任何疑似浅模块的东西做删除测试：删掉它是让复杂度**集中**了，还是只是**挪了个地方**？“会集中”才是你要的信号。）把 Ousterhout《A Philosophy of Software Design》里的深模块思想压缩成一句模型可执行的判据——这是整个文件里提示词工程的最高光时刻。 ### 阶段 2：HTML 报告——输出到系统临时目录 第二阶段的第一个决策就很讲究：**报告写成自包含 HTML 文件，放到操作系统临时目录**。从 `$TMPDIR` 解析、回退到 `/tmp`（Windows 是 `%TEMP%`），文件名带时间戳保证每次运行拿到新文件，然后用 `xdg-open`/`open`/`start` 帮用户打开并告知绝对路径。这样**仓库里什么都不落**——审查是阅后即焚的，不会污染 git status。 渲染技术栈也写得明确：Tailwind 走 CDN 做布局，Mermaid 走 CDN 画图；但**不许全用 Mermaid**——“图形状的关系（调用图、依赖、时序）用 Mermaid，想要更编辑部风格的视觉（质量图、剖面图）就手写 div/SVG。混着来，全用 Mermaid 会开始显得千篇一律。” 每个候选机会渲染成一张卡片，字段固定： - **Files**：涉及哪些文件/模块 - **Problem**：当前架构为什么造成摩擦 - **Solution**：会改成什么样（大白话） - **Benefits**：用 locality 和 leverage 解释，以及测试会如何改善 - **Before / After 对比图**：并排、手绘感 - **推荐强度**：`Strong` / `Worth exploring` / `Speculative` 三档徽章 报告以"Top recommendation"收尾：你第一个该动哪个、为什么。然后一句硬约束："**Do NOT propose interfaces yet.**"（此刻不许提出具体接口设计。）写完文件后只问用户一句："Which of these would you like to explore?"——**先诊断，不开药**。这个阶段边界划得极其克制。 还有一个容易被忽略的细节：**ADR 冲突处理**。如果某个候选和现有 ADR 矛盾，只有当摩擦真实到值得重开决策时才提，并在卡片上用警告框标注（“与 ADR-0007 矛盾——但值得重开，因为……”）。“不要把 ADR 禁止的每一个理论重构都列出来”——这一条防住了 AI 审查工具最常见的毛病：把用户已经决策过的东西当新发现反复端上来。 ### 阶段 3：Grilling 循环——选中之后才深入 用户选中一个候选后，Skill 转入 `/grilling`——套件里那个“拷问”原语（也是 grill-me 的底层引擎，本期不展开）。它会把决策树一枝一枝和你走完：约束、依赖、加深后模块的形状、接缝后面放什么、哪些测试能存活。 同时**副作用内联发生**：对话中决策定型时，顺手跑 `/domain-modeling` 维护领域模型——给加深后的模块起了 `CONTEXT.md` 里没有的名字？当场加进去（文件不存在就惰性创建）；用户以一个“有承重能力的理由”拒绝了候选？主动提议记一条 ADR，原话框架是：“要我把这条记成 ADR 吗？这样未来的架构审查就不会再提它。”——并且明确排除两类不值得记的理由：临时性的（“现在不值得”）和不言自明的。 ## 逐文件拆 HTML-REPORT.md：给“输出物”写规范 多数 Skill 只规范“过程”，这个 Skill 额外用一份 6.7KB 的附属文件规范“输出物”——这是它区别于 90% 社区 Skill 的地方。SKILL.md 末尾一句 "See HTML-REPORT.md for the full HTML scaffold, diagram patterns, and styling guidance" 把细节**渐进披露**出去：主文件保持可读，渲染细节按需加载。 HTML-REPORT.md 里最有含金量的是**五种图表模式**，明确告诉模型“挑合适的用，混着来”： 1. **Mermaid 图**（依赖/调用流的主力）——并给了带 `classDef` 的示例：泄漏边红色、深模块深色； 2. **手绘盒子箭头**——当 Mermaid 的布局跟你较劲时，用 inline SVG 绝对定位画出“一个粗边框深模块、内部淡化的实现”； 3. **剖面图**——横向色带堆叠展示调用穿过的层：改前 6 条薄层每层都不干事，改后 1 条厚层标上合并后的职责； 4. **质量图（mass diagram）**——每个模块画两个矩形（接口面积 vs 实现面积）：改前接口矩形和实现一样高（浅），改后接口矮、实现高（深）； 5. **调用图坍缩**——改前是嵌套盒子的调用树，改后坍缩成一个盒子，内部调用淡显。 风格规范同样具体到类名："Lean editorial, not corporate-dashboard"（走编辑部风，别做企业仪表盘），标题可选衬线体，`text-xs uppercase tracking-wider` 做图内模块标签，“它们应该读起来像示意图，而不是 UI"，图表控制在约 320px 高让 before/after 并排不滚动。唯一的脚本是 Tailwind CDN 和 Mermaid ESM 导入——"report 其余部分是静态的：没有应用代码，没有交互”。 最后是**术语锁定**的二次执行，精确到给出反例句式：必须用 module / interface / implementation / depth / deep / shallow / seam / adapter / leverage / locality；绝不替换为 component / service / unit / API / signature / boundary / layer / wrapper。"Wins"列表的收益必须用词汇表术语表述（"locality: bugs concentrate in one module"），并点名禁用 "easier to maintain"、"cleaner code" 这类不入词汇表的空话。"No hedging, no throat-clearing"——不许含糊，不许清嗓子。 ## 组合架构一图流 把这个 Skill 的依赖关系画出来，你能看到它其实是套件里的一台“总装机”： ```mermaid flowchart TD U["用户输入 /improve-codebase-architecture"] --> P1["阶段1: Explore
git log 找热点 → Explore子代理走读
删除测试筛浅模块"] P1 --> P2["阶段2: HTML报告
写$TMPDIR + 自动打开
Strong/Worth exploring/Speculative 三档"] P2 --> Q{"用户选中候选?"} Q -- 否 --> END["阅后即焚, 仓库零污染"] Q -- 是 --> P3["阶段3: Grilling循环
决策树逐枝拷问"] P3 --> DM["/domain-modeling
更新CONTEXT.md + ADR"] P3 -.设计备选接口.-> CD["/codebase-design
design-it-twice 并行子代理"] subgraph 词汇层 [model-invoked 可复用纪律] CD DM GR["/grilling 拷问原语"] end GR -.被调用.-> P3 CD -.词汇表.-> P1 ``` ## 评测对比表 以下评分基于实读的源文件 + skills.sh 安装数据 + 仓库 README 的自我定位（实战效果项含 README 自述的局限，非独立实测）： | Skill | 功能完整度(25%) | 设计质量(25%) | 实战效果(20%) | 上手难度(15%) | 社区活跃度(15%) | 加权 | |-------|------|------|------|------|------|------| | improve-codebase-architecture | ★★★★★ | ★★★★★ | ★★★★ | ★★★★ | ★★★★★ | 4.8 | | grill-with-docs | ★★★★★ | ★★★★★ | ★★★★★ | ★★★★★ | ★★★★★ | 4.9 | | codebase-design（词汇Skill） | ★★★★ | ★★★★★ | ★★★★ | ★★★★★ | ★★★★★ | 4.5 | | diagnosing-bugs | ★★★★ | ★★★★ | ★★★★ | ★★★★ | ★★★★★ | 4.1 | | triage | ★★★★ | ★★★★ | ★★★★ | ★★★ | ★★★★★ | 4.0 | | handoff | ★★★★ | ★★★★ | ★★★★ | ★★★★★ | ★★★★★ | 4.2 | | vercel-react-best-practices | ★★★★ | ★★★★ | ★★★★★ | ★★★★★ | ★★★★★ | 4.5 | 说明：grill-with-docs 得分最高是因为它把拷问、领域建模、ADR 记录三件事焊在一入口里，新手零配置即用；主角 Skill 上手难度略低一档，因为它假设你愿意维护 CONTEXT.md/ADR 这套“领域文档基建”，且 README 坦言它是"a survey, not a rescue"——在真正老旧的代码库上它会找到真候选，但**不会替你解开泥球**，跟进重构仍然靠人。 ## 安装与使用 ```bash # 方式一：Claude Code 官方插件市场（托管、自动更新，只读订阅） claude plugins install mattpocock-skills # 或会话内：/plugin install mattpocock-skills # 方式二：skills.sh 安装器（文件复制进你的仓库，可自由改造） npx skills@latest add mattpocock/skills ``` 装完后每个仓库跑一次 `/setup-matt-pocock-skills`（配置 issue 跟踪器、triage 标签、文档存放位置）。注意 README 明确警告：**两种方式二选一**，都装会得到两份重复 Skill。日常用法：每隔几天对你的代码库跑一次 `/improve-codebase-architecture`，从 HTML 报告里挑一个候选进入拷问循环。 ## 适用与不适用 **适用**：AI 加速开发导致熵增失控的仓库（README 称之为"We Built A Ball Of Mud"问题的解药）；准备接手老项目前的体检；想系统性引入深模块/接缝词汇的团队；TypeScript/前后端通用工程库。 **不适用**：期待“一键自动重构”的人——它刻意停在诊断，动不改代码；没有持续维护意愿的一次性脚本仓库（YAGNI 定向逻辑会失去意义）；不愿维护 CONTEXT.md 和 ADR 的团队，词汇联动会退化成普通审查。 ## 给想写 Skill 的人：本期可抄的六个模式 1. **重 Skill 锁显式触发**：代价高的操作写 `disable-model-invocation: true`，防模型自作主张。 2. **description 即交互合同**：用流程动词串起“用户将经历什么”，不写能力形容词。 3. **渐进披露**：主 SKILL.md 只留流程骨架，输出物规范、图表模板下沉到附属 .md，用一句 "See X.md" 按需加载。 4. **词汇表独立成 Skill**：把领域词汇做成 model-invoked 的字典 Skill，过程 Skill 引用之，写作与执行共用一套语言。 5. **输出物不落仓库**：报告/草稿写 `$TMPDIR`，阅后即焚。 6. **把“不做什么”写进正文**："Do NOT propose interfaces yet"、ADR 冲突只在摩擦真实时提、临时理由不记档——负向约束比正向指令更能压住模型的过度热情。 ## 推荐排行榜 - **设计质量 TOP 1**：improve-codebase-architecture——全套件里唯一带“输出物规范”的 Skill，负向约束密度最高 - **新手首选**：grill-with-docs——一个入口同时解决对齐、领域语言、决策存档 - **性价比之王**：codebase-design——3.4KB 的纯词汇文件，被整个套件引用，安装成本几乎为零 - **被低估**：handoff（628.2K）——会话交接压缩，配合长任务几乎零学习成本 - **最值得观望**：wayfinder——README 描述的“决策票地图”是套件里最大胆的实验（16KB 单文件），尚未进入榜单头部 ## 参考来源 1. [skills.sh — The Agent Skills Directory](https://skills.sh) — 全时段安装榜数据（find-skills 3.0M、grill-me 911.2K、improve-codebase-architecture 747.2K 等），2026-08-28 抓取 2. [mattpocock/skills — GitHub 仓库](https://github.com/mattpocock/skills) — README（四大失败模式、user/model-invoked 分类、安装方式） 3. [improve-codebase-architecture/SKILL.md（main 分支）](https://github.com/mattpocock/skills/blob/main/skills/engineering/improve-codebase-architecture/SKILL.md) — 本文逐段拆解的主文件 4. [improve-codebase-architecture/HTML-REPORT.md（main 分支）](https://github.com/mattpocock/skills/blob/main/skills/engineering/improve-codebase-architecture/HTML-REPORT.md) — HTML 输出规范、五种图表模式、术语锁定 5. [codebase-design/SKILL.md 与 grilling/SKILL.md（main 分支）](https://github.com/mattpocock/skills/blob/main/skills/engineering/codebase-design/SKILL.md) — 被引用的词汇表 Skill 与拷问原语，佐证组合架构 6. [mattpocock/skills 仓库文件树（GitHub API）](https://api.github.com/repos/mattpocock/skills/git/trees/main?recursive=1) — 目录结构（engineering/productivity/misc/in-progress/deprecated 五区）、CHANGELOG.md 44KB、.agents/adr 自食其 dogfood 的佐证 > [!tip] 51学通信知识星球 > **星主：爱卫生**（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。 > **星球定位**：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。 > **当前规模**：5200 篇主题 / 990 个回答，198 元/年。 > **加入福利**：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。 > **AI 加持**：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。