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](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。

Deepening

给定依赖关系，如何安全地 deepen 一组 shallow modules。假设你使用 LANGUAGE.md 中的词汇：module、interface、seam、adapter。

Dependency categories

评估 deepening candidate 时，先分类它的 dependencies。类别决定 deepened module 如何跨 seam 测试。

1. In-process

纯计算、in-memory state、无 I/O。总是可以 deepen：合并 modules，并直接通过新 interface 测试。不需要 adapter。

2. Local-substitutable

存在本地 test stand-ins 的 dependencies（Postgres 用 PGLite、in-memory filesystem）。如果 stand-in 存在，就可以 deepen。deepened module 在 test suite 中用 stand-in 测试。seam 是内部的；module 外部 interface 上不需要 port。

3. Remote but owned (Ports & Adapters)

你自己控制的跨 network boundary 服务（microservices、internal APIs）。在 seam 处定义 port（interface）。deep module 拥有逻辑；transport 作为 adapter 注入。tests 使用 in-memory adapter。production 使用 HTTP/gRPC/queue adapter。

推荐表达：_"Define a port at the seam, implement an HTTP adapter for production and an in-memory adapter for testing, so the logic sits in one deep module even though it's deployed across a network."_

4. True external (Mock)

你不控制的第三方服务（Stripe、Twilio 等）。deepened module 把外部 dependency 作为 injected port；tests 提供 mock adapter。

Seam discipline

• One adapter means a hypothetical seam. Two adapters means a real one. 除非至少有两个 adapters 有正当理由（通常 production + test），否则不要引入 port。单 adapter seam 只是 indirection。
• Internal seams vs external seams. deep module 可以有 internal seams（implementation 私有，由自己的 tests 使用），也可以有 interface 上的 external seam。不要因为 tests 使用 internal seams，就把它们暴露到 interface 上。

Testing strategy: replace, don't layer

• 一旦 deepened module interface 上有 tests，旧的 shallow modules unit tests 就变成浪费，删除它们。
• 在 deepened module 的 interface 上写新 tests。interface is the test surface。
• Tests 通过 interface 断言 observable outcomes，而不是 internal state。
• Tests 应经受 internal refactors；它们描述 behaviour，不描述 implementation。如果 implementation 改变时 test 也必须改变，那它测过了 interface。

HTML Report Format

Architectural review 会被渲染成一个 self-contained HTML file，放在 OS temp directory。Tailwind 和 Mermaid 都来自 CDNs。Mermaid 能稳定处理 graph-shaped diagrams；手写 divs 和 inline SVG 更适合 editorial visuals（mass diagrams、cross-sections）。两者混用，不要所有东西都依赖 Mermaid，否则看起来会很 generic。

Scaffold

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>Architecture review — {{repo name}}</title>
    <script src="https://cdn.tailwindcss.com"></script>
    <script type="module">
      import mermaid from "https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs";
      mermaid.initialize({ startOnLoad: true, theme: "neutral", securityLevel: "loose" });
    </script>
    <style>
      /* small custom layer for things Tailwind doesn't cover cleanly:
         dashed seam lines, hand-drawn-feeling arrow heads, etc. */
      .seam { stroke-dasharray: 4 4; }
      .leak { stroke: #dc2626; }
      .deep { background: linear-gradient(135deg, #0f172a, #1e293b); }
    </style>
  </head>
  <body class="bg-stone-50 text-slate-900 font-sans">
    <main class="max-w-5xl mx-auto px-6 py-12 space-y-12">
      <header>...</header>
      <section id="candidates" class="space-y-10">...</section>
      <section id="top-recommendation">...</section>
    </main>
  </body>
</html>

Header

Repo name、date，以及紧凑 legend：solid box = module，dashed line = seam，red arrow = leakage，thick dark box = deep module。不要 introduction paragraph，直接进入 candidates。

Candidate card

Diagrams 承担主要信息量。Prose 要稀疏、直白，并直接使用 glossary terms（LANGUAGE.md），不要铺垫。

每个 candidate 是一个 <article>：

• Title — 简短，命名 deepening（例如 “Collapse the Order intake pipeline”）。
• Badge row — recommendation strength（Strong = emerald，Worth exploring = amber，Speculative = slate），再加一个 dependency category tag（in-process、local-substitutable、ports & adapters、mock）。
• Files — monospaced list，font-mono text-sm。
• Before / After diagram — 核心内容。两列并排。见下面的 patterns。
• Problem — 一句话。痛点是什么。
• Solution — 一句话。改变什么。
• Wins — bullets，每条不超过 6 个词。例如 “Tests hit one interface”、“Pricing logic stops leaking”、“Delete 4 shallow wrappers”。
• ADR callout（如果适用）— amber-tinted box 里的一行。

不要写成段落解释。如果 diagram 需要一段文字才能看懂，就重画 diagram。

Diagram patterns

选择适合 candidate 的 pattern。混合使用。不要让每个 diagram 长得一样，变化本身就是重点。

Mermaid graph（dependencies / call flow 的主力）

当重点是 “X calls Y calls Z, and look at the mess” 时，使用 Mermaid flowchart 或 graph。外面包一个 Tailwind-styled card，避免像是直接空降。用 classDef 把 leakage edges 标红，把 deep module 标成深色。Sequence diagrams 很适合 “before: 6 round-trips; after: 1.”

<div class="rounded-lg border border-slate-200 bg-white p-4">
  <pre class="mermaid">
    flowchart LR
      A[OrderHandler] --> B[OrderValidator]
      B --> C[OrderRepo]
      C -.leak.-> D[PricingClient]
      classDef leak stroke:#dc2626,stroke-width:2px;
      class C,D leak
  </pre>
</div>

Hand-built boxes-and-arrows（当 Mermaid layout 跟你作对时）

Modules 用带 border 和 label 的 <div> 表示。Arrows 用 inline SVG <line> 或 <path>，absolute 定位在 relative container 上。当你希望 “after” diagram 像一个 thick-bordered deep module，内部结构被 greyed-out 显示时，用这个；Mermaid 很难渲染出正确的 weight。

Cross-section（适合 layered shallowness）

堆叠 horizontal bands（h-12 border-l-4）来展示一次 call 穿过的 layers。Before：6 个薄 layer，每个几乎什么都不做。After：1 个 thick band，标注 consolidated responsibility。

Mass diagram（适合 “interface as wide as implementation”）

每个 module 用两个 rectangles：一个表示 interface surface area，一个表示 implementation。Before：interface rectangle 几乎和 implementation rectangle 一样高（shallow）。After：interface rectangle 很短，implementation rectangle 很高（deep）。

Call-graph collapse

Before：把 function calls tree 渲染成 nested boxes。After：把同一棵 tree 折叠成一个 box，并把现在内部化的 calls 以 faded 状态显示在里面。

Style guidance

• Lean editorial，不要 corporate-dashboard。留足 whitespace。Headings 可选 serif（font-serif 和 stone/slate 很搭）。
• Colour sparingly：一个 accent（emerald 或 indigo），red 用于 leakage，amber 用于 warnings。
• Diagrams 保持约 320px 高，这样 before/after 可以舒适并排，不需要滚动。
• Diagram 内部 module labels 使用 text-xs uppercase tracking-wider，应该读起来像 schematic，而不是 UI。
• 唯一 scripts 是 Tailwind CDN 和 Mermaid ESM import。除此之外 report 是 static，不要 app code，不要 Mermaid 自身渲染之外的 interactivity。

Top recommendation section

一个更大的 card。Candidate name，一句话说明为什么，anchor link 到它的 card。仅此而已。

Tone

Plain English，concise，但 architectural nouns 和 verbs 必须直接来自 LANGUAGE.md。简洁不是漂移的借口。

Use exactly: module, interface, implementation, depth, deep, shallow, seam, adapter, leverage, locality.

Never substitute: component, service, unit (for module) · API, signature (for interface) · boundary (for seam) · layer, wrapper (for module, when you mean module).

Phrasings that fit the style:

• "Order intake module is shallow — interface nearly matches the implementation."
• "Pricing leaks across the seam."
• "Deepen: one interface, one place to test."
• "Two adapters justify the seam: HTTP in prod, in-memory in tests."

Wins bullets 要用 glossary terms 命名收益：_"locality: bugs concentrate in one module"_、_"leverage: one interface, N call sites"_、_"interface shrinks; implementation absorbs the wrappers"_。不要写 _"easier to maintain"_ 或 _"cleaner code"_，这些词不在 glossary 中，不能直接获得位置。

不要 hedging，不要 throat-clearing，不要 “it's worth noting that…”。如果一个 sentence 可以变成 bullet，就改成 bullet。如果一个 bullet 可以删，就删。如果一个 term 不在 LANGUAGE.md 里，先找一个已经存在的 term，再考虑发明新词。

Interface Design

当用户想为选中的 deepening candidate 探索替代 interfaces 时，使用这个 parallel sub-agent pattern。基于 “Design It Twice”（Ousterhout）：你的第一个想法很可能不是最好的。

使用 LANGUAGE.md 中的词汇：module、interface、seam、adapter、leverage。

Process

1. Frame the problem space

在生成 sub-agents 前，先为选中的 candidate 写一段面向用户的问题空间说明：

• 新 interface 必须满足的 constraints
• 它依赖哪些 dependencies，以及它们属于哪个 category（见 DEEPENING.md）
• 一个粗略 illustrative code sketch，用来让 constraints 具体化；这不是 proposal，只是帮助理解 constraints

把它展示给用户，然后立即进入 Step 2。用户阅读和思考时，sub-agents 并行工作。

2. Spawn sub-agents

使用 Agent tool 并行生成 3+ 个 sub-agents。每个都必须为 deepened module 产出一个根本不同的 interface。

给每个 sub-agent 单独的 technical brief（file paths、coupling details、DEEPENING.md 中的 dependency category、seam 后面是什么）。brief 独立于 Step 1 中面向用户的问题空间说明。给每个 agent 不同的 design constraint：

• Agent 1: "Minimize the interface — aim for 1–3 entry points max. Maximise leverage per entry point."
• Agent 2: "Maximise flexibility — support many use cases and extension."
• Agent 3: "Optimise for the most common caller — make the default case trivial."
• Agent 4 (if applicable): "Design around ports & adapters for cross-seam dependencies."

在 brief 中同时包含 LANGUAGE.md 词汇和 CONTEXT.md 词汇，让每个 sub-agent 使用 architecture language 和项目 domain language 一致命名。

每个 sub-agent 输出：

1. Interface（types、methods、params，以及 invariants、ordering、error modes） 2. Usage example，展示 callers 如何使用它 3. Implementation 在 seam 后面隐藏什么 4. Dependency strategy 和 adapters（见 DEEPENING.md） 5. Trade-offs：哪里 leverage 高，哪里薄

3. Present and compare

顺序展示 designs，让用户能吸收每个方案，然后用 prose 比较。按 depth（interface 上的 leverage）、locality（change 集中在哪里）和 seam placement 对比。

比较后给出你自己的 recommendation：你认为哪个 design 最强，以及为什么。如果不同 designs 的元素可以很好组合，就提出 hybrid。要有判断力；用户要的是明确判断，不是菜单。

Language

这个 skill 的所有建议都使用这套共享词汇。精确使用这些 terms，不要替换成 “component”、“service”、“API” 或 “boundary”。一致语言就是全部重点。

Terms

Module 任何有 interface 和 implementation 的东西。刻意保持尺度无关，同样适用于 function、class、package 或跨 tier 的 slice。 _Avoid_: unit, component, service.

Interface caller 为正确使用 module 必须知道的一切。包括 type signature，也包括 invariants、ordering constraints、error modes、required configuration 和 performance characteristics。 _Avoid_: API, signature（太窄，只指 type-level surface）。

Implementation module 内部的代码主体。不同于 Adapter：一个东西可以是小 adapter 但有大 implementation（Postgres repo），也可以是大 adapter 但小 implementation（in-memory fake）。当 seam 是主题时用 “adapter”，其他时候用 “implementation”。

Depth interface 上的 leverage：caller（或 test）每学习一单位 interface 能触达多少 behaviour。大量 behaviour 位于小 interface 后面时，module 是 deep。interface 几乎和 implementation 一样复杂时，module 是 shallow。

Seam _(from Michael Feathers)_ 一个可以不在原地编辑就改变 behaviour 的地方。也就是 module interface 所在的_位置_。seam 放在哪里本身就是 design decision，和它背后放什么不同。 _Avoid_: boundary（与 DDD 的 bounded context 混用过载）。

Adapter 在 seam 处满足 interface 的具体东西。描述的是_角色_（填哪个 slot），不是内容（里面有什么）。

Leverage callers 从 depth 获得的东西。每学习一单位 interface，获得更多能力。一个 implementation 回报 N 个 call sites 和 M 个 tests。

Locality maintainers 从 depth 获得的东西。change、bugs、knowledge 和 verification 集中在一个地方，而不是散布到 callers。修一次，到处都修好。

Principles

• Depth is a property of the interface, not the implementation. deep module 内部可以由小的、mockable、swappable parts 组成，只是它们不是 interface 的一部分。module 可以有 internal seams（implementation 私有，由自己的 tests 使用），也可以有 interface 上的 external seam。
• The deletion test. 想象删除 module。如果复杂性消失，module 没隐藏任何东西（只是 pass-through）。如果复杂性在 N 个 callers 中重新出现，module 就在发挥价值。
• The interface is the test surface. Callers 和 tests 跨越同一个 seam。如果你想测试 interface _后面_的东西，module 形状可能不对。
• One adapter means a hypothetical seam. Two adapters means a real one. 除非确实有东西会跨 seam 变化，否则不要引入 seam。

Relationships

• 一个 Module 恰好有一个 Interface（它呈现给 callers 和 tests 的 surface）。
• Depth 是 Module 的属性，针对其 Interface 衡量。
• Seam 是 Module 的 Interface 所在的位置。
• Adapter 位于 Seam，并满足 Interface。
• Depth 为 callers 产生 Leverage，为 maintainers 产生 Locality。

Rejected framings

• 把 Depth 当作 implementation-lines 与 interface-lines 的比例（Ousterhout）：这会奖励给 implementation 填水。我们使用 depth-as-leverage。
• 把 “Interface” 当作 TypeScript `interface` keyword 或 class public methods：太窄。这里的 interface 包含 caller 必须知道的每个事实。
• “Boundary”：与 DDD 的 bounded context 混用过载。说 seam 或 interface。