improve-codebase-architecture

改进代码库架构

发现架构摩擦，并提出加深机会——将浅模块改造成深模块的重构。目标是提升可测试性和 AI 导航能力。

此命令参考项目的领域模型，并基于一套共享的设计词汇：

• 运行 /codebase-design 技能，了解架构词汇（模块、接口、深度、接缝、适配器、杠杆作用、局部性）及其原则（删除测试、“接口就是测试面”、“一个适配器 = 假设的接缝，两个 = 实际的接缝”）。在每条建议中都要准确使用这些术语——不要偏离为“组件”“服务”“API”或“边界”。
• CONTEXT.md 中的领域语言为良好接缝命名；docs/adr/ 中的 ADR 记录了此命令不应重新讨论的决策。

流程

1. 探索

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

然后使用 subagent_type=Explore 的 Agent 工具遍历代码库。不要遵循僵化的启发式规则——自然地探索，并记录遇到的摩擦：

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

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

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

将自包含的 HTML 文件写入操作系统临时目录，确保仓库中不会留下任何文件。通过 $TMPDIR 获取临时目录；若未设置，则回退到 /tmp（Windows 上使用 %TEMP%），并写入 <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 中的一项，并以徽章呈现

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

领域术语使用 CONTEXT.md 中的词汇，架构术语使用 /codebase-design 中的词汇。 如果 CONTEXT.md 定义了“订单”，就称其为“订单接收模块”，不要称为“FooBarHandler”或“订单服务”。

ADR 冲突：如果某个候选方案与现有 ADR 矛盾，只有在摩擦确实严重到值得重新审视 ADR 时，才将其列出。在卡片中明确标注（例如，添加警告提示：“与 ADR-0007 矛盾——但值得重新审视，因为……”）。不要列出每个被 ADR 禁止的理论性重构方案。

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

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

3. 深入探讨循环

用户选定候选方案后，运行 /grilling 技能，与用户共同梳理设计树：约束、依赖关系、深化模块的形态、接口背后的内容，以及哪些测试会保留。

随着决策逐步明确，副作用会同步发生——运行 /domain-modeling 技能，随时更新领域模型：

• 将深化模块命名为 CONTEXT.md 中尚未定义的概念？ 将该术语添加到 CONTEXT.md。如果文件不存在，则按需创建。
• 在对话中厘清模糊术语？ 立即更新 CONTEXT.md。
• 用户基于关键理由拒绝了候选方案？ 提出记录为 ADR，并这样表述：“要我把这个决定记录为 ADR，避免未来的架构评审再次建议同一方案吗？”只有当未来的探索者确实需要知道这个理由、以免重复提出同一建议时才提出；跳过暂时性理由（“目前不值得做”）和不言自明的理由。
• 想探索深化模块的替代接口？ 运行 /codebase-design 技能，并使用其「设计两次」并行子 Agent 模式。