improve-codebase-architecture

name	improve-codebase-architecture
description	扫描代码仓寻找深化机会，以可视化 HTML 报告呈现，然后针对你选择的任一方案进行访谈打磨。
disable-model-invocation	true

改善代码仓架构

揭示架构摩擦，提出深化机会 — 将浅层模块转变为深层模块的重构。目标是可测试性和 AI 可导航性。

此命令_基于_项目的领域模型，并建立在共享设计词汇之上：

• 运行 /codebase-design 技能获取架构词汇（module、interface、depth、seam、adapter、leverage、locality）及其原则（删除测试、"接口就是测试表面"、"一个适配器 = 假设缝合点，两个 = 真实缝合点"）。在每个建议中严格使用这些术语 — 不要滑向 "component"、"service"、"API" 或 "boundary"。
• CONTEXT.md 中的领域语言为好的缝合点提供名称；docs/adr/ 中的 ADR 记录此命令不应重新争论的决策。

流程

1. 探索

首先阅读项目的领域词汇表（CONTEXT.md）和你接触区域的任何 ADR。

然后使用 Agent 工具，以 subagent_type=Explore 遍历代码仓。不要遵循僵化的启发式 — 有机地探索，注意你在何处遇到摩擦：

• 理解一个概念需要在多个小模块之间反复跳跃？
• 哪些模块是浅层的 — 接口几乎和实现一样复杂？
• 哪些纯函数仅为了可测试性而被提取，但真正的 bug 却隐藏在它们的调用方式中（没有局部性）？
• 哪些紧密耦合的模块在其缝合点处泄漏？
• 代码仓的哪些部分未经测试，或难以通过其当前接口进行测试？

对你怀疑是浅层的任何东西应用删除测试：删除它会集中复杂性，还是仅仅移动它？"是的，会集中"就是你想要的信号。

2. 以 HTML 报告呈现候选方案

将自包含的 HTML 文件写入操作系统临时目录，以免任何内容落入仓库。从 $TMPDIR 解析临时目录，回退到 /tmp（Windows 上用 %TEMP%），写入 <临时目录>/architecture-review-<时间戳>.html，使每次运行获得全新文件。为用户打开它 — Linux 上用 xdg-open <路径>，macOS 上用 open <路径>，Windows 上用 start <路径> — 并告知绝对路径。

报告使用 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-REPORT.md 获取完整的 HTML 脚手架、图表模式和样式指南。

此时不要提出接口。文件写入后，询问用户："你想探索其中哪一个？"

3. 访谈循环

一旦用户选择了候选方案，运行 /grilling 技能与他们一起遍历设计树 — 约束、依赖、深化模块的形状、缝合点后面的内容、哪些测试存留下来。

当决策结晶时，副作用即时发生 — 运行 /domain-modeling 技能保持领域模型同步更新：

• 为 CONTEXT.md 中没有的概念命名深化模块？ 将术语添加到 CONTEXT.md。如果文件不存在则延迟创建。
• 在对话中精炼模糊术语？ 当场更新 CONTEXT.md。
• 用户以具有负载作用的理由拒绝候选方案？ 提供 ADR，框架为："要我将其记录为 ADR 吗？这样未来的架构审查不会重新建议它。" 仅在未来的探索者确实需要此理由来避免重新建议相同内容时才提供 — 跳过暂时性理由（"现在不值得做"）和自明性理由。
• 想要探索深化模块的替代接口？ 运行 /codebase-design 技能并使用其"设计两次"并行子 agent 模式。