Improve codebase architecture

Improve Codebase Architecture

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

Glossary

在每条 suggestion 中精确使用这些 terms。语言一致就是重点，不要漂移到 “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 — 内部 code。
• Depth — interface 上的 leverage：小 interface 后面有大量 behaviour。Deep = high leverage。Shallow = interface 几乎和 implementation 一样复杂。
• Seam — interface 所在之处；可以在不原地编辑的情况下改变 behaviour 的地方。（用这个，不用 "boundary"。）
• Adapter — 在 seam 上满足 interface 的具体东西。
• Leverage — callers 从 depth 得到的东西。
• Locality — maintainers 从 depth 得到的东西：change、bugs、knowledge 集中在一个地方。

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

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

这个 skill 受项目 domain model 启发。Domain language 给好的 seams 命名；ADRs 记录 skill 不应重新争论的 decisions。

Process

1. Explore

先阅读项目的 domain glossary，以及你正在触碰区域的 ADRs。

然后使用 Agent tool，并设置 subagent_type=Explore 来遍历 codebase。不要遵循僵硬 heuristics；有机探索，并记录你体验到 friction 的地方：

• 理解一个 concept 是否需要在许多小 modules 之间来回跳？
• 哪里有 shallow modules：interface 几乎和 implementation 一样复杂？
• 哪里为了 testability 提取了 pure functions，但真正 bugs 藏在它们被调用的方式中（没有 locality）？
• 哪里 tightly-coupled modules 泄漏到了它们的 seams 外？
• Codebase 的哪些部分未测试，或很难通过当前 interface 测试？

对任何你怀疑 shallow 的东西应用 deletion test：删除它会集中 complexity，还是只是移动它？“yes, concentrates” 是你想要的信号。

2. Present candidates

展示 deepening opportunities 的编号列表。对每个 candidate：

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

使用 CONTEXT.md vocabulary 表达 domain，使用 LANGUAGE.md vocabulary 表达 architecture。 如果 CONTEXT.md 定义了 "Order"，就谈 "the Order intake module"，不要说 "the FooBarHandler"，也不要说 "the Order service"。

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

此时不要提出 interfaces。询问用户："Which of these would you like to explore?"

3. Grilling loop

用户选定 candidate 后，进入 grilling conversation。和他们一起走 design tree：constraints、dependencies、deepened module 的形状、seam 后面是什么、哪些 tests 能存活。

当 decisions crystallize 时，side effects 立即发生：

• 用一个不在 CONTEXT.md 中的 concept 命名 deepened module？ 把该 term 添加到 CONTEXT.md，纪律与 /grill-with-docs 相同（见 CONTEXT-FORMAT.md）。如果文件不存在，惰性创建。
• 在对话中打磨 fuzzy term？ 立刻更新 CONTEXT.md。
• 用户用 load-bearing reason 拒绝 candidate？ 提出 ADR，表述为："Want me to record this as an ADR so future architecture reviews don't re-suggest it?" 只有当这个 reason 未来 explorer 确实需要知道、以避免再次提出同一建议时才提出；跳过短暂理由（"not worth it right now"）和显而易见的理由。见 ADR-FORMAT.md。
• 想为 deepened module 探索 alternative interfaces？ 见 INTERFACE-DESIGN.md。