improve-codebase-architecture

improve-codebase-architecture 技能概览

这个技能做什么

improve-codebase-architecture 可以帮助你发现架构上的阻力，把浅层代码重构成更有深度、边界更清晰、可测试性更强、也更利于 AI 导航的模块。它最适合你需要一个 improve-codebase-architecture skill，能够从模块深度而不只是样式清理的角度来审视代码库的时候。

适合谁使用

适合做大量重构、架构评审，以及处理耦合过高、接口不清晰或逻辑分散导致修改变慢的代码库。它尤其适合已经重视设计术语的团队，特别是代码库里有你希望这个技能遵循的 CONTEXT.md 和 docs/adr/ 决策时。

它的不同之处

这个技能对术语非常有主见：它更偏好 module、interface、seam、adapter、depth 和 locality 这类说法。这样做很重要，因为它能让建议保持一致、可执行，而不是滑向泛泛的“把这个 service 整理一下”式建议。

如何使用 improve-codebase-architecture 技能

安装与初读

先通过 mattpocock/skills 集合里的 improve-codebase-architecture install 流程安装，然后先读 SKILL.md。接着，在把它应用到你自己的仓库之前，再查看 LANGUAGE.md、DEEPENING.md 和 INTERFACE-DESIGN.md。如果仓库里有 CONTEXT.md 或 docs/adr/，也要尽早阅读，因为它们会决定什么样的改动才算“好改动”。

如何组织一个好的提示词

给这个技能一个具体的架构问题，而不是笼统地说“改进一下”。高质量输入要明确模块范围、痛点和约束。

好的提示词：

• “Review src/billing/* for shallow modules and suggest deepening opportunities that preserve current behavior and reduce test complexity.”
• “Find refactoring candidates in the auth flow where a seam would improve locality without adding extra adapters.”
• “Assess whether packages/parser should be split or deepened for improve-codebase-architecture for Refactoring.”

弱的提示词：

• “Improve this repo.”
• “Make the architecture better.”

实际工作流

先从代码库里一个很小的切片开始，再让它给出候选方案，而不是直接要求最终重写。最好的 improve-codebase-architecture usage 模式是：先识别阻力 → 指明浅层模块 → 分类依赖 → 选择 seam → 提出能提升 depth 的最小改动。如果仓库涉及 I/O、注入的 ports 或外部服务，要告诉这个技能哪些依赖是进程内的、可本地替换的、远端拥有的，或者是真正的外部依赖。

输入里该提供什么

给出文件路径、当前行为，以及任何硬性约束，比如“必须保持测试通过”“不能改公共 CLI flags”或“必须保留 ADR 决策”。如果你希望调整接口，要说明你更看重最小化、灵活性，还是对常见调用方的优化。这样能把技能引导到真正有用的权衡分析，而不是泛化的重构点子。

improve-codebase-architecture 技能常见问题

它比普通提示词更好吗？

如果任务属于架构问题而不是表面修修补补，那答案是肯定的。普通提示词可以建议清理代码，但 improve-codebase-architecture 是按 depth、seams、adapters 和 locality 这些维度来思考的，这会让输出更适合真正的重构工作。

什么时候不适合用？

如果你只是想改命名、格式化，或者修一个一次性的 bug，就别用它。若你无法提供足够的仓库上下文来识别模块接口、依赖和约束，它的效果也会弱很多。

初学者能用吗？

可以，但前提是他们能指出代码库中的一个具体区域。初学者如果能把范围缩小到一个小而明确的切片，并附上相关文件或目录，通常会得到更好的结果。

它适用于任何技术栈吗？

大体上是的，因为这个技能更偏架构，而不是某个框架专用。只要仓库里有清晰的模块、测试，以及描述设计意图的文档，它的效果通常最好。

如何改进 improve-codebase-architecture 技能

提供更强的上下文

提升质量最大的办法，是明确指出具体的模块或子系统，并说明它哪里显得浅。把当前接口、主要依赖，以及问题是可测试性、耦合，还是所有权不清楚，一并写出来。

先要候选，再做选择

不要一上来就要求完整重写。更好的 improve-codebase-architecture usage 是先请求 2–4 个加深候选方案，并附上优缺点和 seam 选项，然后再追问最优那个。这样第一轮结果会更贴近仓库本身，而不是建立在假设上。

说清楚最重要的约束

如果你的优先级是“保留行为”“尽量少加 adapters”或“保持公共接口稳定”，就直接说出来。这个技能会根据你更看重杠杆收益、迁移成本，还是接口简洁性，给出不同建议。

用更明确的证据继续迭代

拿到第一轮结果后，把它误读的文件、漏掉的依赖，或者最难维护的测试反馈回去。把问题收窄到一个模块簇，再让它基于这些证据重新评估 seam，效果会更好。