什么是 improve-codebase-architecture？
如果你维护过超过半年的项目，大概率遇到过这种情况：代码能跑，功能正常，但加一个新功能越来越费劲，改一行代码要牵扯五六个文件，测试也很难写。你不知道问题出在哪，更不知道从哪下手。
improve-codebase-architecture 就是用来解决这个问题的。它是一个由 TypeScript 大神 Matt Pocock 开发的 AI 技能，核心工作只有一件事：像医生做体检一样，扫描你的代码仓库，找出架构层面的“病灶”，然后告诉你最该先治哪里。
截至 2026 年 8 月，这个技能的安装量已经超过 56 万次，在 Claude Code 技能排行榜上排名第七。
这个技能不会自动帮你重构代码，它做的事情更务实：帮你决定“该重构哪里” 。
主要功能
1. 扫描代码库，找出“浅模块”
improve-codebase-architecture 的核心概念是 “浅模块”（shallow module） 。什么是浅模块？就是那些“公开接口几乎和内部实现一样复杂”的模块——你调用它的时候，需要知道的细节太多，相当于把模块的内部逻辑暴露给了调用方。
技能会扫描整个代码库，找出所有这样的浅模块，然后把它们列成一份候选清单。
2. 生成可视化的 HTML 报告
扫描完成后，技能会在你的电脑临时目录里生成一份自包含的 HTML 报告。报告用 Tailwind 做样式、Mermaid 画关系图，把候选的架构问题清晰地展示出来。报告会自动在浏览器中打开。
这份报告不写入代码仓库，每次运行都是独立的。
3. “删除测试”——判断模块是否值得保留
技能在判断一个模块是否“浅”的时候，会应用一个叫 “删除测试”（deletion test） 的方法：想象一下，如果删除这个模块，它的复杂度会消失，还是分散到所有调用它的地方？
如果删除之后，复杂度只是转移到了 N 个调用方，说明这个模块“物有所值”——它把分散的复杂度收拢到了一起。如果删除之后复杂度直接消失了，说明这个模块只是个“传声筒”，没有真正承载任何逻辑。
4. 架构词汇的精准使用
这个技能有一套严格的设计词汇——module、interface、depth、seam、adapter、leverage、locality。AI 在给出任何建议时，必须精准使用这些术语，不能随口说“组件”“服务”“API”或“边界”这类模糊的词。
这套词汇来自 /codebase-design 技能，确保了每次架构分析都在同一个语言体系下进行。
5. 基于真实变更历史的热点扫描
技能不会傻乎乎地扫描整个仓库。它会先看 git log，找出最近频繁变更的文件和区域（hot spots）——这些地方往往是架构问题最集中的区域。如果变更很分散，再扩大扫描范围。
它会先读项目的 CONTEXT.md（领域词汇表）和 docs/adr/（架构决策记录），避免重复讨论已经定下来的事情。
如何安装 improve-codebase-architecture
安装命令
在终端中执行以下命令：
npx skills add mattpocock/skills --skill improve-codebase-architecture
这条命令会从 Matt Pocock 的官方技能仓库中单独安装 improve-codebase-architecture。
备选安装方式
你也可以通过完整 URL 安装：
npx skills add https://github.com/mattpocock/skills --skill improve-codebase-architecture
安装完整技能包
如果你想一次性安装 Matt Pocock 的所有技能（包括 grill-me、grill-with-docs 和 improve-codebase-architecture），可以执行：
npx skills add mattpocock/skills验证安装
安装完成后，通过以下命令确认：
npx skills list
如何使用
安装后，在你的 AI 编程助手（Cursor、Claude Code、Codex 等）中输入：
/improve-codebase-architecture
或者直接说“帮我分析一下这个项目的架构”。AI 就会开始扫描你的代码库。
应用场景
场景一：接手一个陌生项目
你刚加入一个新团队，或者接手了一个老项目。代码能跑，但结构混乱，你不知道从哪里开始理解。用 improve-codebase-architecture，AI 会帮你画出架构概览，指出最需要关注的核心模块。
场景二：加新功能越来越吃力
你维护一个项目已经半年了，最近每次加新功能都比上一次更费劲——改一行代码要改五个文件，测试也越来越难写。这通常是架构在“变浅”的信号。用这个技能扫描一遍，它会告诉你哪些模块正在拖慢你的开发速度。
场景三：代码评审中发现“说不清哪里不对”的 PR
团队里有人在 PR 里改了一大堆文件，你觉得“这样写不太对”，但说不清具体哪里不对。用 improve-codebase-architecture 跑一下，AI 会从架构层面给出具体的诊断和建议，你的评审意见就有了依据。
场景四：准备做一次架构重构，但不知道从哪开始
你知道项目需要重构，但几千个文件摆在那，不知道先动哪一块。这个技能会帮你排出一个优先级清单——哪些模块最“浅”、最该先动。
场景五：让代码库更容易被 AI 理解
如果你经常用 AI 编程助手来开发和维护这个项目，代码的“AI 可导航性”（AI-navigability）就很重要。模块越深、接口越清晰，AI 就越容易理解你的代码结构，生成的代码质量也越高。
使用案例
案例一：一个电商项目的架构诊断
一个团队维护着一个运行了三年的电商平台。代码量超过 10 万行，涉及订单、支付、库存、物流、用户等多个模块。最近每次修改订单流程，都要改至少 6 个文件，测试覆盖率也不高。
团队负责人安装了 improve-codebase-architecture，让 AI 对整个订单子系统做了一次扫描。AI 先看了 git log，发现订单模块是最近半年变更最频繁的区域。然后它逐层分析了模块结构，找出了三个“浅模块”——其中一个是“订单状态管理器”，接口有 20 多个方法，几乎把内部实现的所有细节都暴露了出来。
AI 生成了 HTML 报告，用 Mermaid 画出了模块依赖关系图，标注了这三个候选重构点。团队根据报告，优先重构了那个“状态管理器”，把 20 多个公开方法缩减到了 5 个核心方法。重构之后，修改订单状态的代码改动量从平均 6 个文件降到了 2 个。
案例二：一个内部工具从“能跑”到“好改”
一个开发者在维护一个内部数据看板项目，代码量不大但很乱——好几个文件超过 800 行，函数之间互相调用，测试基本写不了。他想重构但不知道从哪下手。
他运行了 improve-codebase-architecture。AI 扫描后指出：项目中最大的那个文件其实是一个“浅模块”——它做了太多事情，但公开接口却几乎把内部所有函数都暴露了出来。AI 建议把这个文件拆成三个深模块，每个只暴露少量核心接口。报告里还附带了具体的拆分建议和依赖关系图。
他按照建议重构之后，测试覆盖率从几乎为零提升到了 60% 以上。
案例三：PR 评审中的架构把关
一个开源项目的维护者在审查一个 PR 时，发现贡献者在一个核心模块里加了 7 个新的公开方法。他直觉觉得“不太对”，但说不出具体问题。
他让 AI 用 improve-codebase-architecture 分析了一下这个模块。AI 的结论是：这个模块正在从“深”变“浅”——新增的公开方法让接口变得越来越复杂。AI 建议贡献者重新设计接口，只暴露 2 个核心方法，把其他逻辑收拢到内部实现里。贡献者按照建议修改后，PR 顺利合并。
案例四：技术负责人的“架构体检”
一个技术负责人每季度会给核心项目做一次“架构体检”。以前全靠人工 review，耗时一周。引入 improve-codebase-architecture 之后，AI 能在 30 分钟内完成扫描、生成报告。技术负责人只需要看报告、做决策、分配重构任务。
他说了一句很实在的话：“这个技能不会替你写代码，但它能让你知道该在哪里花时间。”
总结
improve-codebase-architecture 解决的是一个非常现实的问题：你知道代码架构有问题，但不知道问题在哪、不知道从哪改。
扫描精准：基于 git 历史找热点，不盲目扫全量
输出直观：生成 HTML 报告，带依赖关系图
决策有据：用“删除测试”判断模块价值
语言统一：严格使用架构设计词汇，避免模糊表达
如果你正在维护一个“能跑但不好改”的项目，improve-codebase-architecture 可能是你装过的所有技能里，最能帮你节省“纠结时间”的那一个。它不替你写代码，但它能让你知道该在哪里写代码。
◯ 评论 0