Improve Codebase Architecture

Improve Codebase Architecture 是什么

这是一个“先调查、后决策”的代码库架构体检 Skill。它读取代码、历史变更、上下文与 ADR，寻找边界泄漏、浅层模块、低内聚和难测试区域，再生成可浏览的候选报告。它不会直接重构，也不会把所有异味都包装成必须整改的问题，而是把证据、收益和置信度交给用户选择。

适用场景与不适用场景

适合接手陌生仓库、准备较大重构、技术债梳理或团队希望找到最高杠杆点时使用。若问题已经明确到某个缺陷或函数，直接修复通常更高效；若没有可运行的仓库、历史记录或目标范围，分析质量会明显下降。它也不替代性能剖析、安全审计和逐行代码评审。

核心能力与工作机制

默认从 Git 历史寻找频繁改动的热点，也可按用户指定目录聚焦。分析维度包括模块是否真正隐藏复杂度、职责是否局部化、领域规则是否泄漏、依赖是否使测试困难，并用“删除测试”判断抽象：删除一个模块后，多少调用者必须理解它的内部细节。每个候选标记 Strong、Worth exploring 或 Speculative。

实际工作流与产物

先建立仓库地图并读取已有上下文，再探索候选问题；随后生成一个临时 HTML 报告，使用图表展示相关文件、问题、改进方向、收益、改动前后和置信度。报告打开后流程主动停止，要求用户选择候选。只有选中某项后，才会进一步追问约束，并可把稳定术语写入 CONTEXT、把接受或拒绝的重要理由写成 ADR。

安装、依赖与权限

需要读取源码、Git 历史、CONTEXT 和 ADR，并能在临时目录写入 HTML。报告使用 Tailwind 与 Mermaid CDN，离线环境可能无法完整渲染样式或图。上游流程提到 Claude 的 Explore 子代理；其他代理环境没有同等工具时，探索深度可能下降，但不应据此扩大权限或直接改代码。

限制、风险与使用建议

它天然倾向于产出候选，因此所有结果均为 Speculative 时，应接受“当前架构可能已经足够好”的结论。临时报告可能被系统清理，重要结论要另行保存。热点只表示变更频繁，不等于设计错误；重构收益、迁移成本和回归风险仍需人工验证。最重要的边界是：报告阶段不修改业务代码。

上手建议

提供目标目录、近期痛点、测试命令和不能改变的外部契约；若没有明确范围，可允许它用历史热点起步。阅读报告时优先核对证据文件和调用关系，不要只看图。选择一个候选后，再要求形成小步迁移计划、回滚点和验收指标，然后另开实施任务。

来源、版本与许可

本条目依据固定提交中的完整 Skill、详细说明和 HTML 报告规范整理，仓库声明 MIT 许可证。已将上游明确写出的临时报告、子代理兼容性和“可能无需改进”等限制纳入说明。

常见问题

1. 它会直接重构代码吗？

不会。第一阶段只调查并生成候选报告，打开报告后就停止，等待用户选择。任何代码修改、迁移或删除都应成为后续独立任务，并重新确认范围、测试、回滚方式和外部兼容要求。

2. 没有指定目录时如何选择范围？

它会优先利用 Git 历史寻找频繁变更的热点，再结合模块边界和测试困难度收敛范围。热点只是探索入口，不是问题证据；仍需阅读实现、调用者和已有设计记录后才能形成候选。

3. 什么是删除测试？

它不是自动化单元测试，而是一个架构判断问题：如果删除某个模块，调用方需要了解多少内部细节才能替代它。需要复制大量规则通常说明模块提供了深层抽象；轻易替换则可能只是薄包装。

4. 报告中的置信度如何理解？

Strong 表示证据和收益较明确，Worth exploring 表示值得继续验证，Speculative 表示目前只是线索。置信度不等于优先级；即使证据强，如果迁移成本高、业务价值低，也可能不应立即实施。

5. 为什么所有候选都可能是 Speculative？

架构调查并不保证一定存在高价值重构点。上游文档明确提醒流程会偏向产出发现；当证据不足时，应诚实接受代码库目前足够合理，而不是为了交付报告夸大技术债。

6. HTML 报告会永久保留吗？

默认写到系统临时目录，可能在清理或重启后消失。若报告将用于评审，应在审阅后把选中的结论转成仓库内的计划或 ADR，而不是依赖临时文件作为长期知识源。

7. 其他代理环境可以完整运行吗？

核心分析思路可以迁移，但上游使用了特定的 Explore 子代理描述。缺少等价并行探索能力时，扫描覆盖面可能下降；此时应缩小范围、提供更明确的问题，并人工抽查遗漏，而不是假装结果完整。

8. 如何把报告转成可执行重构计划？

先选一个候选，补充不变量、外部契约、测试基线和迁移顺序，再拆成可回滚的小步骤。每一步都要有验收信号，并保留旧路径直到验证完成；不要一次实施报告中的多个候选。