deep-codebase-audit

深度代码库审查

发现架构摩擦，并提出加深机会——将浅模块重构为深模块。目标是提升可测试性、AI 导航能力和杠杆效应。

此技能的参考资料位于 references/ 文件夹中：

• GLOSSARY.md — 每条建议都要使用的词汇
• DEPTH-GUIDE.md — 如何对依赖进行分类，以及如何跨接缝测试
• INTERFACES.md — 如何探索替代接口

适用场景

在以下情况下使用此技能：

• 用户表示代码库杂乱、难以修改或“不适合 AI”。
• 你想提升可测试性，让未来的 TDD 或自主 Agent 工作更有效。
• 你即将大量投入 AI 驱动的修改，想先降低风险。

如果用户只是想交付一个小功能，不要使用此技能——请改用 /incremental-tdd。

术语表

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

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

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

• 删除测试：设想删除该模块。如果复杂性随之消失，它就是一个传递层。如果复杂性分散到 N 个调用者中并重新出现，它就发挥了价值。
• 接口就是测试面。
• 一个适配器 = 假设的接缝。两个适配器 = 真实的接缝。

流程

0. 先阅读上下文

在探索任何内容之前，检查项目是否包含：

• 领域术语表（CONTEXT.md、docs/glossary.md 或类似文件）——阅读并使用其中的词汇为模块和接缝命名。
• 架构决策记录（docs/adr/ 或类似目录）——记录可能限制或影响探索范围的决策。

如果两者都不存在，就直接继续，无需创建。

1. 探索

使用 Agent 工具，设置 subagent_type=Explore，以自然方式遍历代码库。不要遵循僵化的检查清单——从自然入口开始探索（主应用、顶层路由、CLI 命令或用户指出的区域），并记录你遇到的摩擦：

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

对任何你怀疑较浅的模块应用删除测试：删除它会让复杂性集中到调用者中，还是只会消除复杂性？如果答案是“会集中”，这就是你要找的信号。

事先询问用户，在此情境中“更好的架构”意味着什么——更便于 AI 修改、更完善的测试、更低的认知负担、更少的回归问题——以及有哪些约束（时间范围、技术栈、团队经验）。据此调整探索重点。

2. 展示候选方案

按编号列出可深化的机会。每个候选方案包括：

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

命名时使用项目的领域术语（例如，如果 CONTEXT.md 将 "Order" 定义为领域术语，就称为“Order 接收模块”），架构相关术语则使用 GLOSSARY.md 中的词汇（module、seam、depth、leverage，而不是“service”“boundary”“API”）。

ADR 冲突：如果某个候选方案与现有 ADR 相矛盾，只有在确有充分理由重新审视时才提出。明确标注（例如，“与 ADR-0007 冲突——但值得重新审视，因为……”）。不要列出 ADR 禁止的所有理论性重构。

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

3. 深入探讨

用户选定候选方案后，进入深入探讨对话。与用户一起梳理设计空间——约束、依赖、深化后模块的形态、seam 后面的内容，以及哪些测试得以保留。

随着决策逐渐明确，及时处理相关事项：

• 将深化后的模块命名为领域词汇表中没有的概念？ 将该术语添加到 CONTEXT.md（如果文件不存在，则按需创建）。
• 在对话中明确模糊术语？ 立即更新 CONTEXT.md。
• 用户以关键理由否决某个候选方案？ 提议将其记录为 ADR：“要我把这个决定记录下来，避免今后的架构评审再次提出吗？” 仅在理由长期有效时才提出；对于“现在不值得做”或显而易见的理由，不必提出。
• 想探索深化后模块的其他接口方案？ 请参阅 INTERFACES.md。

有关 seam 两侧的依赖分类和测试策略，请参阅 DEPTH-GUIDE.md。

行为与规则

1. 先描述，再提出方案。 在提出解决方案之前，花时间描述代码库在实际使用中的感受。
2. 优先考虑杠杆作用。 着重关注能让许多未来变更更容易进行的改动，而不是微调。
3. 以深模块的思路思考。 每当发现分散的逻辑，就问：“可以由哪个深模块来负责？”
4. 尊重约束。 如果用户说只有时间做快速改进，就相应调整建议。
5. 避免教条式推崇框架。 使用现有语言和框架的惯用方式；不要围绕新的架构趋势重塑项目。
6. 面向人和 Agent 撰写。 说明和建议应让人类工程师和未来阅读报告的 AI Agent 都能理解。
7. 使用固定词汇。 所有建议都使用 GLOSSARY.md 中的术语。绝不以“component”“service”“API”或“boundary”代替。

示例

用户： “这个 TypeScript 后端简直无从入手，也很难测试。让它更适合 AI 使用。”

你（大致流程）：

1. 检查是否存在 CONTEXT.md 和 ADR。若存在，则阅读。
2. 询问他们所说的“适合 AI 使用”是什么意思（例如，更安全的自主变更、更少的回归问题），以及有哪些约束。
3. 从主要入口开始探索，梳理主要模块并留意浅而分散的逻辑。对可疑部分应用删除测试。
4. 提出 3–5 个按编号排列的深化候选方案，说明文件、问题、解决方案和收益。
5. 询问他们想探索哪一个，然后深入探讨该候选方案。
6. 设计明确后，参阅 INTERFACES.md，并行探索接口方案。
7. 推荐后续技能：使用 /incremental-tdd 进行测试驱动重构；对于较大的架构项目，使用 /spec-writer 和 /slice-the-spec。