improve-codebase-architecture

改进代码库架构

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

此命令以项目的领域模型为依据，并基于一套通用的设计词汇：

• modules.md 介绍了架构词汇（module、interface、depth、seam、adapter、leverage、locality）及其原则（删除测试、“interface 就是测试面”、“一个 adapter = 假设的 seam，两个 = 真实的 seam”）。每条建议都要准确使用这些术语，不要转而使用“component”、“service”、“API”或“boundary”。
• 词汇表中的领域语言为良好的 seam 命名；决策记录则记录了此命令不应重新讨论的决策。

流程

1. 探索

扫描前先确定范围：YAGNI。 加深模块的价值在于让未来对它的修改更容易，因此要优先关注近期有过变更的代码库部分。在开始查看前，先决定查看哪里：

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

首先阅读项目的词汇表、所涉及区域的决策记录，以及规范文件（如果 AGENTS.md 指向这些文件）；如果发现可能相关但未被其提及的文件，请在报告中指出，而不要使用它。 如果缺少这些文件，就在不参考项目规范的情况下进行扫描，并在报告中说明。

然后启动一个子 Agent 来遍历代码库。不要拘泥于固定的启发式方法；自然地探索，并记录你遇到的摩擦：

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

对任何你怀疑较浅的 module 应用删除测试：删除它是否会让复杂性集中起来，还是只会把复杂性转移到别处？“会集中复杂性”就是你要找的信号。

2. 将候选方案呈现为 HTML 报告

在仓库的 documentation/architecture-audit/ 中写入一个独立的 HTML 文件（如果目录不存在，则按需创建；创建目录时，在最近的 AGENTS.md 中添加一行，说明该目录用于存放架构审查报告），文件名为 architecture-audit-<timestamp>.html，确保每次运行都会生成新文件并保留历史记录。为用户打开该文件（Linux 上使用 xdg-open <path>，macOS 上使用 open <path>，Windows 上使用 start <path>），并告知用户该文件相对于仓库根目录的路径。

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

为每个候选方案渲染一张卡片，包含：

• 文件：涉及的文件/模块
• 问题：当前架构导致阻力的原因
• 解决方案：以通俗易懂的语言描述需要做哪些改动
• 收益：从局部性和杠杆作用的角度说明收益，以及测试将如何改进
• 改造前/改造后图示：并排展示自定义绘制的图示，体现浅层结构与加深后的结构
• 推荐强度：从 Strong、Worth exploring、Speculative 中选择一个，以徽章形式呈现

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

领域术语使用术语表中的词汇，架构术语使用 modules.md 中的词汇。 如果术语表定义了 “Order”，就称其为“Order 接单模块”，而不是 “FooBarHandler” 或 “Order 服务”。

与决策记录冲突：如果候选方案与现有决策记录相矛盾，只有在确实存在足够大的阻力、值得重新审视该记录时才提出。请在卡片中明确标记（例如，警示提示：“与决策记录 0007 相矛盾，但值得重新审视，因为……”）。不要列出每一种理论上会被记录禁止的重构。

完整的 HTML 脚手架、图表模式和样式指南，请参阅 html-report.md。

此时不要提出接口方案。文件写好后，询问用户：“你想进一步探讨哪个候选方案？”

3. 迭代完善

用户选定候选方案后，按照 interview method 中的方法，与用户一起沿决策树逐步探讨：约束、依赖关系、加深后模块的形态、接口边界背后的内容，以及哪些测试会保留。

随着决策逐渐明确，立即处理相关副作用：

• 要用术语表中没有的概念为加深后的模块命名，或发现某个术语含义模糊？ 当场解决：指出冲突，用具体场景检验，推荐一个标准术语；用户同意后，按照 glossary-format.md 将其写入术语表。
• 用户基于关键理由否决候选方案？ 提议创建决策记录，措辞如下：“要我把这点记为决策记录，以免未来的架构审查再次提出同样的建议吗？” 用户同意后，按照 decision-record-format.md 写入记录。仅当未来的探索者确实需要这一理由来避免重复提出同一建议时才提出；跳过短暂性的理由（“眼下不值得做”）和不言自明的理由。
• 想要探讨加深后模块的其他接口方案？ 使用 design-it-twice.md 中的并行子 Agent 模式。
• 根据依赖关系加深某个集群？ 按照 deepening.md 了解依赖类别、接口边界原则和测试方法。