---
name: improve-codebase-architecture
description: 在代码库中发现深化机会，参考 CONTEXT.md 中的领域语言和 docs/adr/ 中的决策。当用户想要改进架构、寻找重构机会、整合紧密耦合的模块或使代码库更易测试和更利于 AI 导航时使用。
---

# 改进代码库架构

暴露架构摩擦并建议**深化机会**——将浅模块转化为深模块的重构。目标是可测试性和 AI 可导航性。

## 词汇表

在每个建议中精确使用这些术语。一致的语言是关键——不要滑向"组件"、"服务"、"API"或"边界"。完整定义见 [LANGUAGE.md](LANGUAGE.md)。

- **模块(Module)** — 任何有接口和实现的东西（函数、类、包、切片）。
- **接口(Interface)** — 调用者必须知道的一切才能使用该模块：类型、不变式、错误模式、顺序、配置。不仅仅是类型签名。
- **实现(Implementation)** — 内部的代码。
- **深度(Depth)** — 接口的杠杆作用：一个小接口背后的大量行为。**深(Deep)** = 高杠杆。**浅(Shallow)** = 接口几乎与实现一样复杂。
- **接缝(Seam)** — 接口所在的位置；无需原位编辑即可改变行为的地方。（使用此词，而不是"边界"。）
- **适配器(Adapter)** — 在接缝处满足接口的具体事物。
- **杠杆(Leverage)** — 调用者从深度中获得的东西。
- **局部性(Locality)** — 维护者从深度中获得的东西：变更、错误、知识集中在一个地方。

关键原则（完整列表见 [LANGUAGE.md](LANGUAGE.md)）：

- **删除测试**：想象删除该模块。如果复杂性消失了，它是一个透传。如果复杂性重新出现在 N 个调用者身上，它物有所值。
- **接口就是测试表面。**
- **一个适配器 = 假设性接缝。两个适配器 = 真实接缝。**

此技能**受**项目领域模型的指导。领域语言为好的接缝提供名称；ADR 记录了此技能不应重新争论的决策。

## 流程

### 1. 探索

首先读取项目的领域词汇表和你将触及区域中的任何 ADR。

然后使用 `subagent_type=Explore` 的 Agent 工具遍历代码库。不要遵循僵化的启发式规则——有机地探索，并注意你在哪里遇到摩擦：

- 在哪里理解一个概念需要在许多小模块之间来回跳跃？
- 哪些模块是**浅的**——接口几乎与实现一样复杂？
- 在哪里纯函数仅仅为了可测试性而被提取出来，但真正的 bug 隐藏在它们如何被调用中（没有**局部性**）？
- 在哪里紧密耦合的模块跨越它们的接缝泄露？
- 代码库的哪些部分未经测试，或通过当前接口难以测试？

对你怀疑是浅层的任何东西应用**删除测试**：删除它会集中复杂性，还是仅仅移动它？"是的，会集中"就是你想要的信号。

### 2. 展示候选

以编号列表展示深化机会。对每个候选：

- **文件** — 涉及哪些文件/模块
- **问题** — 为什么当前架构导致摩擦
- **解决方案** — 将改变的通俗英文描述
- **收益** — 用局部性和杠杆来解释，以及测试将如何改进

**领域部分使用 CONTEXT.md 词汇，架构部分使用 [LANGUAGE.md](LANGUAGE.md) 词汇。** 如果 `CONTEXT.md` 定义了"订单(Order)"，就说"订单录入模块"——而不是"FooBarHandler"，也不是"订单服务"。

**ADR 冲突**：如果一个候选与现有 ADR 相矛盾，只有在摩擦足够真实、值得重新审视 ADR 时才提出。清晰标记（例如"_与 ADR-0007 矛盾——但值得重新讨论，因为……"_）。不要列出每个 ADR 禁止的理论重构。

暂时不要提出接口。问用户："你希望探索哪些？"

### 3. 质询循环

一旦用户选择一个候选，进入质询对话。与他们一起遍历设计树——约束、依赖关系、深化后的模块形态、接缝背后的内容、哪些测试存活。

副作用在决策结晶时实时发生：

- **为一个不在 `CONTEXT.md` 中的概念命名了深化模块？** 将术语添加到 `CONTEXT.md`——和 `/grill-with-docs` 相同的规范（见 [CONTEXT-FORMAT.md](../grill-with-docs/CONTEXT-FORMAT.md)）。如果文件不存在则惰性创建。
- **对话中精炼了一个模糊术语？** 立即更新 `CONTEXT.md`。
- **用户因重要原因拒绝了候选？** 提供 ADR，表述为：_"要我把它记录为 ADR 吗？这样未来的架构评审就不会再提出同样的建议。"_ 只有当这个原因对一个未来的探索者来说确实需要知道以避免重复提议相同内容时才提供——跳过临时原因（"现在不值得"）和自明的原因。见 [ADR-FORMAT.md](../grill-with-docs/ADR-FORMAT.md)。
- **想为深化模块探索替代接口？** 见 [INTERFACE-DESIGN.md](INTERFACE-DESIGN.md)。
