improve-codebase-architecture

改进代码库架构

扫描代码库，寻找深化机会，并将结果呈现为可视化 HTML 报告，然后围绕你选中的机会展开深入探讨。在用户希望先找出架构改进候选项，再选择其中一项时使用。触发条件：改进架构、寻找深化机会、我们应该在哪里重构。

此技能从 mattpocock/skills（MIT）导入，上游要求由用户主动调用。

何时使用此技能

• 扫描代码库，寻找深化机会，并将结果呈现为可视化 HTML 报告，然后围绕你选中的机会展开深入探讨。
• 在用户希望先找出架构改进候选项，再选择其中一项时使用。
• 触发条件：改进架构、寻找深化机会、我们应该在哪里重构。

说明

改进代码库架构

找出架构摩擦，并提出深化机会：通过重构将浅模块变为深模块。目标是提升可测试性和 AI 导航能力。

此命令以项目的领域模型为依据，并基于一套共享的设计术语构建：

• 使用“codebase-design”调用 Skill 工具，了解架构术语（module、interface、depth、seam、adapter、leverage、locality）及其原则（删除测试、“接口就是测试表面”、“一个 adapter 是假设的 seam，两个才是真实的”）。每条建议都要准确使用这些术语，不要偏离去使用“component”、“service”、“API”或“boundary”。
• CONTEXT.md 中的领域语言为良好的 seam 命名；docs/adr/ 中的 ADR 记录了此命令不应重新讨论的决策。

流程

1. 探索

先确定范围，再开始扫描：YAGNI。 深化 module 能让未来对其进行的更改变得更容易，因此应重点关注代码库中近期改动过的部分。在查看之前，先决定查看哪里：

• 如果用户指定了方向（某个 module、子系统或痛点），就按这个方向进行，并跳过下面的推断步骤。
• 否则，沿着提交历史（git log --oneline）向前回溯一段时间，找出代码库的热点，即反复出现的文件和区域，并优先关注这些路径。如果改动分散，没有明显热点，就扩大搜索范围。

首先阅读项目的领域术语表（CONTEXT.md），以及所涉及区域的任何 ADR。

然后启动一个子 Agent 检查代码库。不要遵循僵化的启发式方法；自然地探索，并记录你遇到的阻力：

• 理解一个概念是否需要在许多小 module 之间来回跳转？
• 是否有 interface 几乎和实现一样复杂的浅 module？
• 是否有纯函数仅为可测试性而抽取出来，但真正的 bug 却藏在调用方式中（缺乏 locality）？
• 紧密耦合的 module 是否会跨越 seam 泄漏？
• 代码库的哪些部分未经测试，或难以通过现有 interface 进行测试？

对任何疑似浅模块的对象应用删除测试：删除它会让复杂性集中起来，还是只会将其转移到别处？如果答案是“会集中”，这就是你要寻找的信号。

2. 将候选方案整理为 HTML 报告

将独立的 HTML 文件写入操作系统临时目录，避免在仓库中留下任何文件。通过 $TMPDIR 确定临时目录，若未设置则回退到 /tmp（Windows 上使用 %TEMP%），并写入 <tmpdir>/architecture-review-<timestamp>.html，确保每次运行都会生成新文件。为用户打开该文件（Linux 上使用 xdg-open <path>，macOS 上使用 open <path>，Windows 上使用 start <path>），并告知用户绝对路径。

报告使用 Tailwind via CDN 进行布局和样式设置，并在图、流程或时序图能可靠表达结构时使用 Mermaid via CDN。将 Mermaid 与手工制作的 CSS/SVG 视觉元素结合使用：适合图形结构的关系（调用图、依赖关系、时序）使用 Mermaid；需要更具编辑感的效果（质量图、剖面图、折叠动画）时使用手工制作的 div/SVG。每个候选方案都要有一个改造前/后可视化图。注重视觉呈现。

为每个候选方案绘制一张卡片，包含：

• 文件：涉及的文件/模块
• 问题：当前架构为何造成阻碍
• 解决方案：用通俗语言描述将进行哪些更改
• 收益：从局部性和杠杆效应的角度说明收益，以及测试会如何改进
• 改造前/后示意图：并排、自定义绘制，展示浅层结构及其加深后的结构
• 推荐力度：以下三种之一：Strong、Worth exploring、Speculative，以徽章形式呈现

在报告末尾添加首选建议部分：说明你会优先处理哪个候选方案，以及原因。

领域内容使用 CONTEXT.md 中的词汇，架构内容使用 /codebase-design 中的词汇。 如果 CONTEXT.md 将“Order”定义为一个概念，请使用“Order 接单模块”，而不是“FooBarHandler”或“Order 服务”。

ADR 冲突：如果某个候选方案与现有 ADR 冲突，仅当实际阻碍严重到足以重新审议该 ADR 时才展示。在卡片中明确标注（例如警告提示：“与 ADR-0007 冲突，但值得重新审议，因为……”）。不要列出每个被 ADR 禁止的理论性重构方案。

完整的 HTML 脚手架、图示模式和样式指南请参阅 HTML-REPORT.md。

暂时不要提出接口方案。写完文件后，询问用户：“你想进一步探索哪个方案？”

3. 深入探讨循环

用户选定候选方案后，调用 Skill 工具并传入 "grilling"，与用户沿着决策树逐步讨论：约束、依赖、加深后模块的形态、接缝背后的内容，以及哪些测试得以保留。

随着决策逐步明确，相关副作用会同步发生；过程中调用 Skill 工具并传入 "domain-modeling"，确保领域模型保持最新：

• 将加深后的模块命名为 CONTEXT.md 中尚未出现的概念？ 将该术语添加到 CONTEXT.md。如果文件不存在，则按需创建。
• 在对话中明确了含糊的术语？ 立即更新 CONTEXT.md。
• 用户基于关键原因否决了候选方案？ 提议记录 ADR，措辞如下：“要我把这个原因记录为 ADR，避免未来的架构评审再次提出这个方案吗？”仅当未来的探索者确实需要这个原因来避免重复提出同一方案时才提议；对于“目前不值得”等临时性原因和不言自明的原因，则不必提议。
• 想探索加深后模块的替代接口方案？ 调用 Skill 工具并传入 "codebase-design"，采用其 design-it-twice 并行子 Agent 模式。

示例

• 先将此技能应用于一个范围较小的部分，确认输出符合上述要求后，再扩展到完整任务。
• 如果某一步需要从仓库或环境中获取信息，请先查明，而不是询问用户。

最佳实践

• 保持上游流程不变；明确记录偏离之处，不要悄然自行变通。
• 在此技能标明属于用户的每个决策点，都应暂停并交还控制权。
• 优先进行小而可逆的更改，并明确说明假设，不要将其隐去。

参考资料

• 上游技能：mattpocock/skills skills/engineering/improve-codebase-architecture/SKILL.md（提交 3cca18b，MIT）
• 配套文档：references/HTML-REPORT.md
• 项目规范：.agent-skills/skill-standardization/SKILL.md
• 验证脚本：.agent-skills/skill-standardization/scripts/validate_skill.sh