improve-codebase-architecture

Improve Codebase Architecture

暴露 architecture friction，并提出 deepening opportunities，也就是把 shallow modules 变成 deep modules 的 refactors。目标是 testability 和 AI-navigability。

Glossary

在每个建议中精确使用这些术语。语言一致性就是重点，不要漂移到 “component”、“service”、“API” 或 “boundary”。完整定义见 LANGUAGE.md。

• Module — 任何有 interface 和 implementation 的东西（function、class、package、slice）。
• Interface — caller 为正确使用 module 必须知道的一切：types、invariants、error modes、ordering、config。不只是 type signature。
• Implementation — 内部代码。
• Depth — interface 上的 leverage：小 interface 后面有大量 behaviour。Deep = 高 leverage。Shallow = interface 几乎和 implementation 一样复杂。
• Seam — interface 所在的位置；可以不原地编辑就改变 behaviour 的地方。（用这个词，不用 “boundary”。）
• Adapter — 在 seam 处满足 interface 的具体东西。
• Leverage — callers 从 depth 获得的东西。
• Locality — maintainers 从 depth 获得的东西：change、bugs、knowledge 集中在一个地方。

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

• Deletion test：想象删除这个 module。如果复杂性消失，它只是 pass-through。如果复杂性在 N 个 callers 中重新出现，它就在发挥价值。
• The interface is the test surface.
• One adapter = hypothetical seam. Two adapters = real seam.

这个 skill 会参考项目的 domain model。Domain language 为好的 seams 命名；ADRs 记录 skill 不应重新争论的决策。

Process

1. Explore

先读取项目的 domain glossary 和你将触碰区域的任何 ADR。

然后使用 Agent tool 和 subagent_type=Explore 遍历 codebase。不要死套启发式规则；自然探索并记录你感到 friction 的地方：

• 理解一个概念是否需要在许多小 modules 之间来回跳？
• 哪些 modules 是 shallow，interface 几乎和 implementation 一样复杂？
• 哪些 pure functions 只是为了 testability 被抽出，但真正 bug 藏在调用方式里（没有 locality）？
• 哪些 tightly-coupled modules 会跨 seams 泄漏？
• codebase 哪些部分未测试，或很难通过当前 interface 测试？

对任何疑似 shallow 的东西应用 deletion test：删除它会集中复杂性，还是只是移动复杂性？“会集中”就是你要找的信号。

2. Present candidates as an HTML report

写一个 self-contained HTML file 到 OS temp directory，避免任何内容落进 repo。Temp dir 从 $TMPDIR 解析，fallback 到 /tmp（Windows 上用 %TEMP%），并写入 <tmpdir>/architecture-review-<timestamp>.html，确保每次运行都有新文件。为用户打开它：Linux 用 xdg-open <path>，macOS 用 open <path>，Windows 用 start <path>，并告诉用户绝对路径。

Report 使用 Tailwind via CDN 做 layout 和 styling，使用 Mermaid via CDN 处理适合 graph/flow/sequence 的 diagrams。Mermaid 要和手写 CSS/SVG visual 混用：关系是 graph-shaped（call graphs、dependencies、sequences）时用 Mermaid；想要更 editorial 的效果（mass diagrams、cross-sections、collapse animations）时用 hand-built divs/SVG。每个 candidate 都要有一个 before/after visualisation。要视觉化。

每个 candidate 仍使用之前的模板，但渲染成 card：

• Files — 涉及哪些 files/modules
• Problem — 当前 architecture 为什么造成 friction
• Solution — 用普通语言说明会改变什么
• Benefits — 用 locality 和 leverage 解释，并说明 tests 会如何改善
• Before / After diagram — side-by-side，自定义绘制，说明 shallowness 和 deepening
• Recommendation strength — Strong、Worth exploring、Speculative 之一，渲染成 badge

Report 最后加一个 Top recommendation section：你会先处理哪个 candidate，以及原因。

domain 词汇使用 CONTEXT.md，architecture 词汇使用 LANGUAGE.md。 如果 CONTEXT.md 定义了 “Order”，就说 “Order intake module”，不要说 “FooBarHandler”，也不要说 “Order service”。

ADR conflicts：如果 candidate 与现有 ADR 冲突，只有当 friction 真实到值得重开 ADR 时才提出。在 card 中明确标记（例如一个 warning callout："contradicts ADR-0007 — but worth reopening because…"）。不要列出 ADR 理论上禁止的每个 refactor。

完整 HTML scaffold、diagram patterns 和 styling guidance 见 HTML-REPORT.md。

不要还没问用户就提出 interfaces。文件写好后，问用户：“你想探索哪一个？”

3. Grilling loop

用户选中 candidate 后，进入 grilling conversation。和他们走完整个 design tree：constraints、dependencies、deepened module 的形状、seam 后面是什么、哪些 tests 能经受变化。

决策成形时内联产生 side effects：

• 用 CONTEXT.md 中没有的概念命名 deepened module？ 把 term 加到 CONTEXT.md，纪律同 /grill-with-docs（见 CONTEXT-FORMAT.md）。文件不存在就懒创建。
• 对话中收紧了模糊 term？ 立刻更新 CONTEXT.md。
• 用户用有分量的理由拒绝 candidate？ 提议 ADR，表述为："要我把这记录成 ADR，避免未来 architecture reviews 再次建议它吗？" 只有当未来 explorer 真的需要这个理由来避免重复建议时才提议；短期理由（“现在不值得”）和显而易见的理由跳过。见 ADR-FORMAT.md。
• 想探索 deepened module 的替代 interfaces？ 见 INTERFACE-DESIGN.md。