Improve Codebase Architecture

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

本命令 informed by 项目领域模型，建立在共享设计词汇之上：

• 运行 /codebase-design skill 获取架构词汇（module、interface、depth、seam、adapter、leverage、locality）及其原则（deletion test、「interface 就是 test surface」、「one adapter = hypothetical seam，two = real」）。每个建议中 精确 使用这些术语 — 不要 drift 到 "component"、"service"、"API" 或 "boundary"。
• CONTEXT.md 中的领域语言为 good seam 命名；docs/adr/ 中的 ADR 记录本命令不应 re-litigate 的决策。

Process

1. Explore

先读项目领域词汇表（CONTEXT.md）及你即将改动区域的 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. Present candidates as an 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。

每个候选 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 用 /codebase-design 词汇。 若 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 loop

用户 pick 候选后，运行 /grilling skill 与用户走 design tree — constraint、dependency、deepened module 形状、seam 后是什么、哪些 test survive。

决策 crystallize 时 inline 副作用 — 运行 /domain-modeling skill 保持领域模型 current：

• deepened module 命名用了 CONTEXT.md 中没有的概念？ 加 term 到 CONTEXT.md。不存在则 lazy 创建。
• 对话中 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？ 运行 /codebase-design skill 并使用其 design-it-twice 并行 sub-agent 模式。