improve-codebase-architecturelisted

# Improve Codebase Architecture — 架构改进 发现架构摩擦并提出**深化机会**——把浅模块变成深模块的重构。目标是可测试性和 AI 可导航性。 ## 流程 ### 1. 探索 **确定范围——YAGNI。** 在搜索前决定*往哪看*： - 如果用户指定了方向（模块、子系统、痛点），用它 - 否则在 commit history 中找热点区域——频繁出现的文件和区域 先读项目的领域词汇表（`CONTEXT.md`）和 ADR。 用 sub-agent 探索代码库。有组织地探索，注意你感到摩擦的地方： - 理解一个概念需要在多少小模块间跳转？ - 哪些模���**浅**——接口几乎和实现一样复杂？ - 什么地方因为可测试性抽出了纯函数，但真正 bug 藏在它们怎么被调用上？ - 哪里紧耦合的模块跨 seam 泄漏？ - 哪些部分未测试，或通过当前接口很难测试？ 对任何怀疑是浅的东西应用**删除测试**：删除它会集中复杂性，还是只移动它？"是的，会集中"是你想要的信号。 ### 2. 提交候选 —— HTML 报告 写一个自包含的 HTML 文件到 OS 临时目录，不放进仓库。打开给用户看。 每个候选渲染一个卡片包含： - **文件** — 涉及哪些文件/模块 - **问题** — 为什么当前架构造成摩擦 - **方案** — 用纯英语描述会有什么变化 - **收益** — 用 locality 和 leverage 解释 - **Before/After 图** — 展示浅和深化 - **推荐强度** — `Strong | Worth exploring | Speculative` 报告末尾是**Top recommendation**：你最先选哪个候选，为什么。 **这里不提出接口。** 文件写完后问用户："你想探索哪一个？" ### 3. Grilling 循环 用户选定候选后，启动 grilling 模式来逐步解析决策树： - 深化模块命名后新概念不在 `CONTEXT.md` 中？添加术语 - 打磨模糊术语？立即更新 `CONTEXT.md` - 用户以重要理由拒绝候选？提供 ADR 需要探索替代接口？用 codebase-design 的 design-it-twice 模式。