improve-codebase-architecture

name	improve-codebase-architecture
description	扫描代码库中的深化机会，将候选项整理为可视化 HTML 报告，再围绕用户选择的一项持续追问。
disable-model-invocation	true

改进代码库架构

找出架构摩擦，并提出深化机会（deepening opportunities），通过重构把浅模块变成深模块。目标是提高可测试性和 Agent 对代码库的可导航性。

本命令以项目领域模型为依据，并建立在共享设计词汇之上：

• 运行 /codebase-design Skill，获取架构词汇（module、interface、depth、seam、adapter、leverage、locality）及相关原则，包括删除测试、“接口就是测试表面”、“一个 adapter 代表设想中的 seam，两个 adapter 才代表真实 seam”。每项建议都必须准确使用这些术语，不能逐渐换成 “component”“service”“API” 或 “boundary”。
• CONTEXT.md 中的领域语言为良好 seams 提供名称；docs/adr/ 中的 ADR 记录了本命令不应重新争论的既有决策。

流程

1. 探索

先读取项目领域术语表 CONTEXT.md，以及当前涉及区域的所有 ADR。

随后使用 subagent_type=Explore 调用 Agent 工具，浏览代码库。不要套用僵硬的启发式规则；应自然探索，并记录自己在哪些位置感受到理解阻力：

• 理解一个概念时，是否必须在许多小模块之间来回跳转？
• 哪些模块很浅，接口几乎与实现一样复杂？
• 是否有纯函数只因测试需要而被抽出，但真正缺陷隐藏在调用方式中，导致没有局部性？
• 哪些紧密耦合的模块会跨越各自 seam 泄漏细节？
• 代码库的哪些部分没有测试，或很难通过当前接口测试？

对每个可能过浅的对象应用删除测试：删除它会让复杂度集中起来，还是只会把复杂度搬到别处？你需要寻找的是“会重新集中”的情况。

2. 用 HTML 报告展示候选项

把一个自包含 HTML 文件写入操作系统临时目录，不能让任何产物进入仓库。优先从 $TMPDIR 解析临时目录，失败时使用 /tmp；Windows 使用 %TEMP%。文件名为 <tmpdir>/architecture-review-<timestamp>.html，保证每次运行都生成新文件。为用户打开文件：Linux 使用 xdg-open <path>，macOS 使用 open <path>，Windows 使用 start <path>；同时告知用户绝对路径。

报告使用通过 CDN 加载的 Tailwind 完成布局和样式；当图、流程或序列能够可靠表达结构时，使用通过 CDN 加载的 Mermaid 绘图。Mermaid 可以与手工 CSS / SVG 视觉元素混合使用：调用图、依赖图、序列等图结构适合 Mermaid；质量图、横截面、折叠动画等更具编辑感的表达适合手工 div 或 SVG。每个候选项都要提供一组改造前/改造后可视化。报告应充分使用视觉表达。

每个候选项使用一张卡片展示：

• Files——涉及哪些文件或模块
• Problem——当前架构为什么造成阻力
• Solution——用清楚直白的语言说明会发生哪些改变
• Benefits——从局部性、杠杆和测试改进三个角度解释收益
• Before / After diagram——并排展示的自定义图示，呈现当前浅模块结构和深化后的结构
• Recommendation strength——使用 Strong、Worth exploring、Speculative 之一，并以徽章显示

报告结尾添加 Top recommendation 一节：说明最值得优先处理的候选项及原因。

领域部分使用 CONTEXT.md 的词汇，架构部分使用 /codebase-design 的词汇。 如果 CONTEXT.md 定义了 “Order”，应写成 “Order intake module”；不要使用 “FooBarHandler”，也不要写 “Order service”。

与 ADR 冲突时： 只有实际摩擦严重到值得重新审视 ADR，才展示与既有 ADR 冲突的候选项。必须在卡片中明确标记，例如警告提示：“与 ADR-0007 冲突——但值得重新讨论，因为……”。不要列出 ADR 在理论上禁止的每一种重构。

完整 HTML 骨架、图示模式和样式指南参见 HTML-REPORT.md。

此时不得提出具体接口方案。文件写完后，询问用户：“你想深入探索其中哪一项？”

3. 持续追问闭环

用户选择候选项后，运行 /grilling Skill，与用户逐层走完设计决策树：约束、依赖、深化后模块的形态、seam 后面包含什么，以及哪些测试能够保留。

决策一旦清晰，就同步产生副作用。运行 /domain-modeling Skill，在讨论过程中保持领域模型最新：

• 深化后的模块名称使用了 CONTEXT.md 中尚不存在的概念？ 将术语加入 CONTEXT.md。文件不存在时按需创建。
• 讨论中打磨出更准确的术语？ 当场更新 CONTEXT.md。
• 用户基于关键理由否决了候选项？ 询问是否记录 ADR：“要不要把它记成 ADR，避免未来的架构审查再次提出同一建议？”只有未来探索者确实需要知道这个理由，才能避免重提建议时，才提出 ADR。暂时性理由（“现在不值得做”）和显而易见的理由都应跳过。
• 希望为深化后的模块探索不同接口方案？ 运行 /codebase-design Skill，并使用其中“设计两次”的并行子 Agent 模式。