Improve Codebase Architecture

Surface 架构摩擦并 propose deepening opportunities——将 shallow module 变为 deep module 的 refactor。目标是 testability 与 AI-navigability。

词汇表

每个建议中 精确 使用这些术语。一致语言是重点——不要 drift 到 "component"、"service"、"API" 或 "boundary"。完整定义见 LANGUAGE.md。

• Module — 有 interface 与 implementation 的任何东西（function、class、package、slice）。
• Interface — caller 使用该 module 必须知道的一切：type、invariant、error mode、ordering、config。不只是 type signature。
• Implementation — 内部代码。
• Depth — interface 处的 leverage：小 interface 背后大量行为。Deep = 高 leverage。Shallow = interface 几乎与 implementation 一样复杂。
• Seam — interface 所在处；可 alter 行为而无需就地编辑的位置。（用这个，不用 "boundary"。）
• Adapter — 在 seam 处 satisfy interface 的具体事物。
• Leverage — caller 从 depth 得到什么。
• Locality — maintainer 从 depth 得到什么：change、bug、knowledge 集中一处。

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

• Deletion test：想象删除该 module。若 complexity 消失，它是 pass-through。若 complexity 在 N 个 caller 重现，它在 earn keep。
• The interface is the test surface.
• One adapter = hypothetical seam. Two adapters = real seam.

本技能 informed by 项目 domain model。领域语言为 good seam 命名；ADR 记录 skill 不应 re-litigate 的决策。

流程

1. Explore

先读项目领域词汇表及你即将改动区域的 ADR。

然后用 Agent tool、subagent_type=Explore 遍历代码库。不要 rigid heuristics——有机探索并 note friction：

• 理解一个概念是否要在许多小 module 间 bounce？
• 哪些 module shallow——interface 几乎与 implementation 一样复杂？
• 纯函数是否仅为 testability 抽出，但 real bug 藏在如何被调用（无 locality）？
• 紧耦合 module 是否 leak 过 seam？
• 哪些部分 untested，或难以通过当前 interface 测试？

对 suspect shallow 的 apply deletion test：删除会 concentrate complexity 还是 merely move？「会 concentrate」是你要的信号。

2. 以 HTML report 呈现候选

写 self-contained HTML 到 OS temp directory，repo 中不留痕迹。从 $TMPDIR 解析 temp dir，fallback /tmp（Windows 为 %TEMP%），写到 <tmpdir>/architecture-review-<timestamp>.html，每次 run 新文件。为用户打开——Linux xdg-open <path>、macOS open <path>、Windows start <path>——并告知 absolute path。

report 用 Tailwind via CDN 布局样式，Mermaid via CDN 在 graph/flow/sequence 能可靠传达结构时画图。Mix Mermaid 与 hand-crafted CSS/SVG——graph-shaped 关系用 Mermaid（call graph、dependency、sequence），editorial 感（mass diagram、cross-section、collapse animation）用 hand-built div/SVG。每个候选有 before/after visualisation。要 visual。

每个候选用原 template，但 render 为 card：

• Files — 涉及哪些 file/module
• Problem — 当前架构为何 friction
• Solution — plain English 描述会改什么
• Benefits — 用 locality 与 leverage 解释，及 test 如何改善
• Before / After diagram — 并排，custom-drawn，illustrate shallowness 与 deepening
• Recommendation strength — Strong、Worth exploring、Speculative 之一，render 为 badge

report 末尾 Top recommendation：你会先 tackle 哪个候选及 why。

domain 用 CONTEXT.md 词汇，architecture 用 LANGUAGE.md 词汇。 若 CONTEXT.md 定义 "Order"，谈 "the Order intake module"——不是 "the FooBarHandler"，也不是 "the Order service"。

ADR conflicts：若候选 contradict existing ADR，仅当 friction real 到 worth revisiting ADR 时才 surface。在 card 中 clear 标记（如 warning callout："contradicts ADR-0007 — but worth reopening because…"）。不要列出 ADR forbid 的每个 theoretical refactor。

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

尚不要 propose interface。文件写完后问用户：「你想 explore 哪些？」

3. Grilling 循环

用户 pick 候选后，进入 grilling 对话。与用户走 design tree——constraint、dependency、deepened module 形状、seam 背后是什么、哪些 test survive。

决策 crystallize 时 inline 副作用：

• deepened module 命名用了 CONTEXT.md 中没有的概念？ 加 term 到 CONTEXT.md——与 /grill-with-docs 同 discipline（见 CONTEXT-FORMAT.md）。不存在则懒创建。
• 对话中 sharpen fuzzy term？ 当场更新 CONTEXT.md。
• 用户用 load-bearing reason reject 候选？ 提供 ADR，frame 为："Want me to record this as an ADR so future architecture reviews don't re-suggest it?" 仅当 future explorer 需要该 reason 避免 re-suggest 同一件事时 offer——跳过 ephemeral（"not worth it right now"）与 self-evident。
• 想 explore deepened module 的 alternative interface？ 见 INTERFACE-DESIGN.md。