快速开始
npx skills add mattpocock/skills --skill=improve-codebase-architecturenpx skills update improve-codebase-architecture功能说明
improve-codebase-architecture 扫描代码库以寻找深化机会——即浅层模块（接口几乎和它所隐藏的内容一样复杂的模块）可以变为深层模块的地方——将这些机会以一份自包含的可视化 HTML 报告呈现，然后针对你选择的任何一个进行拷问。
它不会给你一扁平的重构列表。每个候选都必须通过删除测试——移除这个模块会让复杂性集中到一个更小的接口后面，还是只是把复杂性搬来搬去？只有"集中"的情况才能入选。这个过滤器防止报告变成泛泛的清理建议。
除非你指定了具体范围，否则它还会将范围限定在实际开发活跃的区域——通过读取最近的提交记录，将权重偏向你仍在修改的代码。深化一个模块的价值在于让未来的变更更容易，所以它会对代码库中最近变更过的部分给予额外的权重。
何时使用
你通过输入 /improve-codebase-architecture 来调用它——智能体不会主动使用它。
作为定期的健康检查来使用它：每隔几天，或者每当代码库开始让人觉得需要在小模块之间来回跳转太多次才能理解一个概念时。如果你已经知道要重新设计的模块，只需要思考它的词汇，请改用 codebase-design——这个技能是发现候选者的调查工具；那个是设计工作台。
深化机会
整个技能围绕一个核心理念：深度。一个深层模块将大量功能隐藏在一个小而稳定的接口后面；一个浅层模块则通过一个几乎和其下代码一样宽的接口泄露了它的实现。报告会寻找浅层化的迹象——仅仅为了可测试性而提取的纯函数，而真正的 bug 隐藏在这些函数如何被调用中（缺乏局部性）；跨越接缝泄漏的模块；不打开五个文件就无法理解的概念——并提出能修复这些问题的深化方案。
它使用共享的设计词汇（模块、接口、深度、接缝、适配器、杠杆效应、局部性）以及来自 CONTEXT.md 的你项目的领域语言来表达，所以一个候选读起来像是"深化 Order intake 模块"，而不是"重构 FooBarHandler"。
报告，然后是拷问
输出是一份浏览器可读的 HTML 文件，写入你的操作系统临时目录——不会落入代码仓库。每个候选都是一张卡片，包含涉及的文件、摩擦点、用通俗语言描述的解决方案、在局部性和杠杆效应方面的收益、前后对比图，以及一个强烈推荐 / 值得探索 / 试验性 的标记。最后它会给出一个它认为应该首先处理的项目。
然后它会停下来，问你想探索哪一个。选择一个，它就会针对那个设计运行 grilling 循环——约束条件、接缝后面藏着什么、哪些测试能存活——并在决策逐步明确时内联更新领域模型。
在整个流程中的位置
improve-codebase-architecture 是定期维护——每隔几天运行一次，而不是作为链条中的一个步骤。它的相邻技能是 codebase-design，它拥有每个候选所基于的深度和接缝词汇；grilling，一旦你选择了候选者，它会遍历决策树；以及 domain-modeling，它在重新设计定型时保持 CONTEXT.md 和 ADR 的更新。当你不确定哪个技能或流程适合时，可以找 ask-matt 帮你导航。