codebase-design

技能简介

本技能为设计**深度模块（deep module）**提供了一套共享词汇与设计原则，帮助你在设计或改进模块接口、决定接缝位置、提升可测试性时做出更好决策。目标是让调用者获得杠杆（leverage）、维护者获得局部性（locality）、所有人都获得可测试性。

使用场景

• 设计或改进模块的对外接口
• 寻找模块深化（deepening）机会
• 决定接缝（seam）应放在哪里
• 让代码更可测试或更易于 AI 导航
• 其他技能需要深度模块词汇时

使用方法

本技能无需安装，由 Agent 在涉及模块设计时自动调用。核心术语需严格使用，不要替换：

• Module：拥有接口与实现的事物
• Interface：调用者必须知道的一切（类型签名、不变量、顺序约束、错误模式、配置等）
• Seam：可在不修改该处代码的情况下改变行为的位置
• Adapter：在接缝处满足接口的具体事物
• Deep module = 小接口 + 大量实现；Shallow module = 大接口 + 少量实现

设计接口时自问：能否减少方法数？能否简化参数？能否在接口背后隐藏更多复杂度？

注意事项

• 不要用 component、service、API、boundary 等词替代上述术语，统一语言是关键。
• 深度是接口的属性，不是实现的属性；模块内部可以有私有接缝。
• 只有一个 adapter 时是假设性接缝，有两个才是真实接缝，不要凭空引入。
• 接口即测试面；若想绕过接口测试，说明模块形态可能不对。