improve-codebase-architecture

改进代码库架构

揭示架构摩擦，并提出深化机会：将浅层模块改造成深层模块的重构。目标是提升可测试性和 AI 导航能力。

此命令以项目的领域模型为依据，并建立在一套通用设计词汇之上：

• 加载「codebase-design」技能（阅读其 SKILL.md），了解架构词汇（module、interface、depth、seam、adapter、leverage、locality）及其原则（删除测试、「接口就是测试面」、「一个适配器 = 假设的 seam，两个 = 真实的 seam」）。每条建议都要准确使用这些术语，不要偏离到「component」、「service」、「API」或「boundary」。
• GLOSSARY.md 中的领域术语为良好的 seam 提供了命名；docs/adr/ 中的 ADR 记录了此命令不应重新讨论的决策。

流程

1. 探索

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

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

先阅读项目的领域术语表（GLOSSARY.md），以及涉及区域内的所有 ADR。

然后启动一个具有全新上下文窗口的子 Agent，让它遍历代码库。不要拘泥于固定的启发式方法；应有机地探索，并记录遇到的摩擦：

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

对任何疑似浅层的模块应用删除测试：删掉它会让复杂性集中起来，还是只会把复杂性挪到别处？回答「会集中」正是你要找的信号。

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

报告语言应与用户的对话语言一致。 使用用户正在使用的语言撰写报告（用户用英语交流时用英语，用户用中文交流时用中文，依此类推）。架构术语首次出现时保留英文形式，并在后面括注报告语言的译文（例如 locality（局部性））；之后使用更自然的表达即可。子 Agent 的探索笔记也遵循相同的语言规则。

将自包含的 HTML 文件写入操作系统临时目录，确保仓库中不留下任何文件。明确解析临时目录（Windows 上使用 $env:TEMP；Linux / WSL / macOS 上使用 $TMPDIR，否则使用 /tmp），并写入 <tmpdir>/architecture-review-<timestamp>.html，确保每次运行都会生成新文件。为用户打开文件（Linux 上使用 xdg-open <path>，macOS 上使用 open <path>，Windows 上使用 start <path>），并告知用户其绝对路径。

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

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

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

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

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

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

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

此时不要提出接口设计。文件写好后，询问用户：“你想深入探讨其中哪一个？”

3. 深入探讨循环

用户选定候选方案后，加载“grilling”技能（阅读其 SKILL.md），与用户一起沿决策树逐步讨论：约束条件、依赖关系、加深后模块的形态、接口后方的实现，以及哪些测试能够保留。

随着决策逐渐明确，立即进行相应的副作用操作；加载“domain-modeling”技能（阅读其 SKILL.md），以便随进展更新领域模型：

• 将不在 GLOSSARY.md 中的概念用作加深后模块的名称？ 将该术语添加到 GLOSSARY.md。如果文件不存在，则按需创建。
• 在对话中明确含糊的术语？ 立即更新 GLOSSARY.md。
• 用户基于关键理由否决候选方案？ 提议记录为 ADR，并这样询问：“要我把这个决定记录为 ADR，以免未来的架构审查再次提出同一建议吗？”只有当未来的探索者确实需要知道这个理由，才能避免重复提出相同建议时才提出；对于短期理由（“现在不值得做”）和不言自明的理由则不要提出。
• 想探索加深后模块的替代接口设计？ 加载“codebase-design”技能（阅读其 SKILL.md），并使用其并行子 Agent 模式，同时设计两种方案。