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

展示一个编号列表，列出 deepening opportunities。每个 candidate 包含：

• Files — 涉及哪些 files/modules
• Problem — 当前 architecture 为什么造成 friction
• Solution — 用普通语言说明会改变什么
• Benefits — 用 locality 和 leverage 解释，也说明 tests 会如何改善

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

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

不要还没问用户就提出 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。