Improve Codebase Architecture

发现架构摩擦并提出模块深化机会：把浅模块重构为深模块，提高可测试性和 AI 可导航性。本 Skill 只做只读探索、报告和决策收口，不修改业务代码；用户确认要实施后再进入 impl。

流程

1. 加载项目上下文

按项目知识协议使用相关 CONTEXT 与适用 RULE；已有知识足够时复用，知识不可用时说明缺口并继续。项目术语用于命名业务概念，相关 ADR 用于识别不应无故重新打开的既有决策。

读取 codebase-design，使用其中的职责归属、必要接口与局部性判断。这里的模块深化指：让消费者通过更简单的接口使用模块，把必须处理的复杂规则集中到模块内部。

2. 探索

先限定扫描范围：YAGNI。 深化模块的收益来自让未来变化更容易，因此优先关注近期频繁变化的区域。

• 用户指定模块、子系统或痛点时，直接使用该方向。
• 用户未指定时，查看一段足够长的 git log --oneline，找出反复出现的文件和热点区域；没有明显热点时再扩大范围。

把选定范围、相关 CONTEXT、RULE、ADR 和 codebase-design 判断准则交给一个只读子 Agent 探索。不要套用固定检查表，而是在理解代码时记录真实摩擦：

• 理解一个概念是否需要在许多小模块之间来回跳转？
• 哪些模块较浅，接口几乎与实现同样复杂？
• 哪些纯函数只是为了测试而抽出，但真实缺陷藏在调用方式中，缺少局部性？
• 哪些紧耦合模块让细节泄漏到接缝之外？
• 哪些区域无法通过当前接口自然测试？

对疑似浅模块执行删除检验：删除它会让复杂度消失，还是只会把复杂度重新散到多个调用者？复杂度重新散开才说明该模块具有深化价值。

3. 生成 HTML 报告

在操作系统临时目录写入一个新的 architecture-review-<timestamp>.html，不向仓库写入报告。优先使用 $TMPDIR，否则使用 /tmp；Windows 使用 %TEMP%。生成后用当前系统的默认方式打开，并向用户返回绝对路径。

报告使用 Tailwind CDN 完成布局和样式，使用 Mermaid CDN 表达调用图、依赖图和时序；需要质量感、剖面或折叠效果时使用手写 CSS、div 或内联 SVG。每个候选都必须有 before / after 可视化。

每个候选卡片包含：

• 涉及文件：相关文件与模块；
• 问题：当前架构造成的具体摩擦；
• 方案：用业务可读语言说明要改变什么；
• 收益：说明规则集中位置、消费者调用和必要验证如何改善；
• Before / After：并排展示当前浅形状与深化后形状；
• 推荐强度：强烈推荐、值得探索 或 推测性。

有成立的候选时，在报告末尾给出一个首选建议及原因；没有可证实收益时直接说明，不为填满报告制造候选。

使用 CONTEXT 词汇命名业务概念，使用 codebase-design 词汇描述架构。候选与 ADR 冲突时，只有摩擦真实且足以重新讨论 ADR 才展示，并在卡片中明确标记冲突。

完整格式、图形模式和样式要求见 [HTML-REPORT.md](./HTML-REPORT.md)。此阶段不设计具体接口。有候选且用户尚未选择时，请用户选择下一步探索方向；用户已指定时直接继续。

4. 决策追问

用户选中候选后，依据已有需求和代码判断常规设计选择。关键取舍需要用户决定时，围绕该候选调用 ask-me；已确认的选择直接用于后续方案。

决策过程中：

• 出现新的长期项目术语或可复用规则时，按项目知识协议提出记录建议，并在用户确认后写入；
• 用户因长期、承重原因拒绝候选时，询问是否记录 ADR，避免未来重复建议；短期优先级等一次性原因不记录；
• 用户希望比较多种接口时，读取 codebase-design 的 DESIGN-IT-TWICE.md 并执行多方案设计；
• 用户确认实施时，结束本 Skill，转入 impl，不在架构探索流程内直接修改代码。