improve-codebase-architecture

改进代码库架构

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

术语表

每条建议都要准确使用以下术语。统一用语是关键——不要换成“组件”“服务”“API”或“边界”。完整定义见 LANGUAGE.md。

• 模块 - 任何具有接口和实现的对象（函数、类、包、切片）。
• 接口 - 调用方必须了解的、使用模块所需的一切：类型、不变量、错误模式、顺序、配置。不只是类型签名。
• 实现 - 内部代码。
• 深度 - 接口所提供的杠杆效应：在精简的接口后封装大量行为。深层 = 杠杆效应强。浅层 = 接口几乎和实现一样复杂。
• 接缝 - 接口所在的位置；可在此处改变行为，而无须就地编辑代码。（请使用这个术语，不要用“边界”。）
• 适配器 - 在接缝处满足接口的具体对象。
• 杠杆效应 - 调用方从深度中获得的收益。
• 局部性 - 维护者从深度中获得的收益：将变更、错误和知识集中在一处。

关键原则（完整列表见 LANGUAGE.md）：

• 删除测试：设想删除该模块。如果复杂性随之消失，它只是一个传递层。如果复杂性重新分散到 N 个调用方中，它就发挥了应有的作用。
• 接口就是测试面。
• 一个适配器 = 假设的接缝。两个适配器 = 真实的接缝。

此技能以项目的领域模型为_依据_。领域语言为良好的接缝命名；ADR 会记录此技能不应重新讨论的决策。

流程

1. 探索

先确定范围，再扫描——YAGNI。 加深模块的价值在于让今后对它的修改更容易，因此，对无人维护的代码提出加深机会，只会带来无法兑现的重构收益。先决定要看_哪里_，再开始查看：

• 如果用户指定了方向——某个模块、子系统或痛点——就从那里入手，跳过下面的推断步骤。
• 否则，回顾最近约 20 次提交（git log --oneline -20 --name-only），找出热点——反复出现的文件和区域——并优先关注这些路径。如果改动分散，没有明显的热点，就扩大范围。

先阅读项目的领域术语表，以及你将要涉及区域内的所有 ADR。

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

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

对所有你怀疑是浅层的模块应用删除测试：删除它会让复杂性集中起来，还是只是把复杂性转移到别处？“会集中”的答案正是你要找的信号。

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

将独立的 HTML 文件写入操作系统临时目录，确保仓库中不会留下任何文件。从 $TMPDIR 获取临时目录，若未设置则回退到 /tmp（Windows 上使用 %TEMP%），并写入 <tmpdir>/architecture-review-<timestamp>.html，确保每次运行都会生成新文件。为用户打开文件：Linux 上执行 xdg-open <path>，macOS 上执行 open <path>，Windows 上执行 start <path>，并告知用户绝对路径。

报告使用 Tailwind via CDN 进行布局和样式设计，使用 Mermaid via CDN 绘制图表，前提是图形、流程或时序图能可靠地传达结构。将 Mermaid 与手工制作的 CSS/SVG 视觉效果结合使用：关系呈图形结构时（调用图、依赖关系、时序）使用 Mermaid；想要更具编辑感的呈现方式时（质量块图、剖面图、折叠动画）使用手工绘制的 div/SVG。每个候选方案都要有前后对比图。注重视觉效果。

每个候选方案沿用之前的模板，但以卡片形式呈现：

• 文件——涉及哪些文件/模块
• 问题——当前架构为何造成阻碍
• 解决方案——用通俗语言描述需要做哪些改变
• 收益——从局部性和杠杆效应的角度说明收益，以及测试会如何改进
• 前后对比图——并排展示自定义绘制的图，说明当前结构为何浅薄，以及如何加深
• 推荐强度——使用 Strong、Worth exploring、Speculative 之一，并渲染为徽章

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

**领域术语使用 CONTEXT.md 中的词汇，架构术语使用 LANGUAGE.md 中的词汇。**如果 CONTEXT.md 定义了 “Order”，就说“Order 接入模块”，不要说 “FooBarHandler” 或 “Order 服务”。

与 ADR 冲突：如果某个候选方案与现有 ADR 矛盾，只有在摩擦足以成为重新审视 ADR 的理由时才展示该方案。在卡片中明确标记（例如，警告提示：“与 ADR-0007 冲突——但值得重新审视，因为……”）。不要列出 ADR 禁止的所有理论性重构方案。

完整的 HTML 模板、图表模式和样式指南请参见 HTML-REPORT.md。

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

3. 讨论循环

用户选定候选方案后，进入讨论环节。与用户一起走完决策树——约束、依赖关系、加深后模块的形态、接口边界背后的内容，以及哪些测试会保留下来。

随着决策逐渐明确，立即处理副作用：

• 将深化后的模块命名为 CONTEXT.md 中尚未定义的概念？ 将该术语添加到 CONTEXT.md——遵循与 /grill-with-docs 相同的规范（参见 CONTEXT-FORMAT.md）。如果文件不存在，则按需创建。
• 讨论中澄清了模糊术语？ 立即更新 CONTEXT.md。
• 用户基于关键理由否决候选方案？ 提议记录为 ADR，并这样询问：“要我将此决定记录为 ADR，以免未来的架构审查再次提出同一建议吗？”仅当未来的探索者确实需要此理由来避免重复提出该方案时才提出；临时性理由（“目前不值得”）和不言自明的理由则跳过。参见 ADR-FORMAT.md。
• 想探索深化后模块的其他接口方案？ 请参见 INTERFACE-DESIGN.md。