improve-codebase-architecture

改进代码库架构

找出架构上的阻力，并提出加深机会——将浅模块改造成深模块的重构。目标是提升可测试性和 AI 导航能力。

这项技能基于一套共享的设计词汇，并以项目的领域模型为_依据_：

• codebase-design 技能涵盖架构词汇——module、interface、depth、seam、adapter、leverage、locality——及其原则：删除测试、“接口就是测试面”、“一个 adapter = 假设的 seam，两个 = 真实的 seam”。扫描之前先阅读，并在每条建议中准确使用这些术语。
• CONTEXT.md 为良好的 seam 命名；docs/adr/ 中的 ADR 记录了这项技能不应重新讨论的决策。如果同时安装了 grill-me 技能，这两种格式都有文档说明：CONTEXT-FORMAT.md、ADR-FORMAT.md。

流程

1. 探索

先确定范围，再开始扫描。 加深模块的价值在于让今后对它的修改更容易，因此应重点关注代码库中持续变化的部分。开始查看之前，先决定从哪里着手：

• 如果用户指定了方向——某个模块、子系统或痛点——就按这个方向探索，并跳过下面的推断步骤。
• 否则，沿着 git log --oneline 往回查看一段时间，找出代码库中的热点——反复出现的文件和区域——并优先关注这些路径。如果改动分散，没有明显热点，就扩大范围。

首先阅读该区域现有的文档：

• CONTEXT.md（或者多上下文仓库中的 CONTEXT-MAP.md 和各个 CONTEXT.md）
• docs/adr/ 中相关的 ADR（以及任何限定上下文的 docs/adr/ 目录）

如果这些文件不存在，静默继续——不要指出它们缺失，也不要主动建议创建。

然后派遣一个只读探索子 Agent 来遍历代码库（在 Claude Code 中使用 Explore Agent 类型）。不要拘泥于固定的启发式方法——自然地探索，并记录遇到的阻力：

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

对任何你怀疑是浅模块的部分应用删除测试：删掉它会让复杂性集中起来，还是只会把复杂性挪到别处？如果答案是“会集中”，这正是你要找的信号。

2. 展示候选方案

每个候选方案都包含：

• 文件 — 涉及哪些文件/模块
• 问题 — 当前架构为何造成阻碍
• 解决方案 — 用通俗语言说明将做出哪些改变
• 收益 — 从局部性和杠杆效应的角度说明收益，以及测试将如何改进
• 推荐强度 — Strong、Worth exploring 或 Speculative

最后给出首选建议：说明你会先处理哪个候选方案，以及原因。

架构呈图状，比起用一段文字描述它，展示加深模块前后的图示更有说服力。如果有 rich-page，就把候选方案列表制作成独立的 HTML 报告——每个候选方案一张卡片，包含展示浅层结构和加深后结构的前后对比图，并用徽章标注推荐强度——写入仓库外的临时路径，并为用户打开。否则就在聊天中以编号列表呈现相同字段。

领域术语使用 CONTEXT.md 中的词汇，架构术语使用 codebase-design 中的词汇。 如果 CONTEXT.md 将某个概念定义为“Order”，就称它为“Order 接收模块”，而不是“FooBarHandler”或“Order 服务”。

ADR 冲突：如果候选方案与现有 ADR 矛盾，只有在实际阻碍严重到值得重新审议 ADR 时才提出。明确标注（例如：“与 ADR-0007 矛盾，但值得重新审议，因为……”）。不要罗列 ADR 所禁止的所有理论性重构。

暂不提出接口。询问用户：“你想深入探讨哪个候选方案？”

3. 深入探讨循环

用户选定候选方案后，进入深入探讨对话——如果已安装 grill-me 技能，就使用它。与用户一起梳理设计树：约束、依赖关系、加深后模块的形态、边界之后的内容，以及哪些测试得以保留。

随着决策逐渐明确，立即落实相应变更——持续更新领域模型，遵循 ubiquitous-language 的同一套规范：

• 将加深后的模块命名为 CONTEXT.md 中尚未定义的概念？ 将该术语添加到 CONTEXT.md（参见 CONTEXT-FORMAT.md）。如果文件不存在，等到需要时再创建。
• 在对话中明确了含糊的术语？ 立即更新 CONTEXT.md。
• 用户基于关键理由拒绝了候选方案？ 提议记录为 ADR，措辞如下：“要我把这个决定记录为 ADR，避免未来的架构评审再次提出同一个方案吗？” 只有当这个理由能帮助未来的探索者避免再次提出相同方案时才提出——对于短期理由（“目前不值得”）和显而易见的理由，不要提出。参见 ADR-FORMAT.md。
• 想探索加深后模块的其他接口设计？ 使用 codebase-design 的 design-it-twice 模式。

---

改编自 mattpocock/skills，MIT © 2026 Matt Pocock。复制此文件时请保留此行。