improve-codebase-architecture

改进代码库架构

发现架构摩擦点，并提出深化机会——将浅层模块转变为深层模块的重构。目标是提升可测试性和 AI 导航能力。

术语表

每条建议都必须准确使用以下术语。保持用词一致是关键——不要改用“组件”“服务”“API”或“边界”。完整定义见 LANGUAGE.md。

• 模块 — 任何具有接口和实现的事物（函数、类、包、切片）。
• 接口 — 调用方使用模块时必须了解的一切：类型、不变量、错误模式、顺序、配置。不只是类型签名。
• 实现 — 内部代码。
• 深度 — 接口所提供的杠杆作用：用小型接口承载大量行为。深层 = 高杠杆作用。浅层 = 接口几乎和实现一样复杂。
• 接缝 — 接口所在之处；可以不在原处编辑就改变行为的位置。（使用这个词，不要用“边界”。）
• 适配器 — 在接缝处满足接口的具体实现。
• 杠杆作用 — 调用方从深度中获得的收益。
• 局部性 — 维护者从深度中获得的收益：变更、缺陷和知识集中在一处。

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

• 删除测试：设想删除这个模块。如果复杂性随之消失，它只是个转发层。如果复杂性在 N 个调用方之间重新出现，那么这个模块就发挥了价值。
• 接口就是测试面。
• 一个适配器 = 假设中的接缝。两个适配器 = 真实的接缝。

此技能以项目的领域模型为_依据_。领域语言为良好的接缝提供命名；ADR 记录了此技能不应重新讨论的决策。

流程

1. 探索

首先阅读项目的领域术语表，以及你要处理的领域内的任何 ADR。

然后使用 Agent 工具，通过 subagent_type=Explore 遍历代码库。不要遵循僵化的启发式规则——自然地探索，并记录你遇到的摩擦：

• 理解一个概念是否需要在许多小型模块之间来回跳转？
• 哪些模块是浅层的——接口几乎和实现一样复杂？
• 是否有纯函数仅为可测试性而抽出，但真正的缺陷却藏在调用方式中（缺乏局部性）？
• 紧密耦合的模块是否会跨越各自的接缝而泄漏？
• 哪些代码库部分未经测试，或难以通过当前接口进行测试？

对任何疑似浅层的模块应用删除测试：删除它会让复杂性集中起来，还是只会把复杂性转移到别处？“会集中”的答案正是你要找的信号。

2. 提出候选项

按编号列出深化机会。每个候选项都要包含：

• 文件 — 涉及哪些文件/模块
• 问题 — 当前架构为何造成摩擦
• 解决方案 — 用通俗语言描述将会发生的变化
• 收益 — 从局部性和杠杆作用的角度说明，并说明测试将如何改进

**领域内容使用 CONTEXT.md 中的词汇，架构内容使用 LANGUAGE.md 中的词汇。**如果 CONTEXT.md 定义了“Order”，就称其为“Order 接入模块”——不要称为“FooBarHandler”，也不要称为“Order 服务”。

与 ADR 冲突：如果候选项与现有 ADR 相矛盾，只有当摩擦足够严重、值得重新审视该 ADR 时才提出。请明确标注（例如：“与 ADR-0007 相矛盾——但由于……，值得重新讨论”）。不要列出 ADR 禁止的所有理论性重构。

暂时不要提出接口。询问用户：“你想深入探讨其中哪一项？”

3. 反复推敲

用户选定一个候选方案后，就进入深入推敲的对话。与用户一起梳理设计树——约束、依赖项、深化后模块的形态、接口背后的内容，以及哪些测试可以保留。

随着决策逐渐明确，副作用会同步发生：

• 为深化后的模块取名时，使用了 CONTEXT.md 中没有的概念？ 将该术语添加到 CONTEXT.md——遵循与 /grill-with-docs 相同的规范（参见 CONTEXT-FORMAT.md）。如果文件不存在，则按需创建。
• 在对话中厘清了含糊的术语？ 立即更新 CONTEXT.md。
• 用户因一个关键理由否决了候选方案？ 提议创建 ADR，并这样措辞：“要我把这点记录为 ADR 吗？这样今后的架构评审就不会再次提出这个方案。” 仅当未来的探索者确实需要知道该理由，才能避免再次提出同一方案时才提出——跳过暂时性的理由（“现在不值得”）和不言自明的理由。参见 ADR-FORMAT.md。
• 想探索深化后模块的替代接口吗？ 参见 INTERFACE-DESIGN.md。

---

从 mattpocock/skills @ b843cb5 引入 — MIT License。有关更新说明，请参见 skills/UPSTREAM-CREDITS.md。