Codebase Design：设计深度模块的共享词汇

技能概述

Codebase Design 是一套用来讨论"深度模块"设计的共享词汇，它让接口、实现、深度、接缝、适配器这些概念在团队里有一致的含义，从而把大量行为收敛到一个小而稳定的接口之后。

适用场景

1. 设计或改进一个模块的接口：当你需要决定一个模块对外暴露什么、隐藏什么，或者觉得现有接口的方法和参数太多、调用方学起来费劲时，这套词汇帮你把讨论聚焦在接口本身，而不是实现细节。

2. 判断接缝该放在哪里、哪里还有深化机会：重构遗留代码时最难的不是改，而是找到合适的切口。技能提供了"删除测试"等判断手段——想象删掉这个模块，如果复杂度消失了，它只是个传声筒；如果复杂度在 N 个调用点重新出现，它就在创造价值。

3. 让代码更容易测试、更容易被 AI 理解和修改：当单元测试难写、只能绕过接口去测内部实现时，通常说明模块形状不对。技能给出的可测试性设计原则（依赖从外部传入、返回结果而不是制造副作用、缩小接口面积）同样能让 AI 编程助手更准确地定位和修改代码。

核心功能

1. 一套精确的术语表，统一团队语言。技能明确定义了模块（Module）、接口（Interface）、实现（Implementation）、深度（Depth）、接缝（Seam）、适配器（Adapter）、杠杆（Leverage）、局部性（Locality），并给出了每个词该用和不该用的场合。比如"模块"是刻意与尺度无关的——可以是一个函数、一个类、一个包，也可以是一个跨层的切片；"接口"远不止类型签名，还包括调用方必须知道的不变量、顺序约束、错误模式和性能特征。

2. 可操作的深度设计原则。深度是接口的属性，不是实现的属性：一个深度模块内部完全可以由小的、可 mock 的、可替换的部件组成，它们只是不属于接口的一部分。技能还给出三条判断准则——删除测试、接口即测试面（调用方和测试穿过同一个接缝）、一个适配器只意味着假想的接缝而两个适配器才意味着真实的接缝。

3. 可测试性设计清单与延伸阅读路径。三条落地规则：接受依赖而不是创建依赖、返回结果而不是产生副作用、缩小接口面积。需要继续深入时，技能指向两个配套文档：DEEPENING.md 讲给定依赖下如何深化一组模块，DESIGN-IT-TWICE.md 讲如何用并行子代理把同一个接口设计成几种截然不同的方案再做比较。

常见问题

什么是深度模块？深浅怎么区分？

深度指的是接口上的杠杆：调用方（或测试）每学一单位接口，能撬动多少行为。大量行为藏在一个小接口后面，就是深度模块；接口复杂度和实现复杂度差不多，就是浅模块。需要注意的是，本技能不采用"实现行数 ÷ 接口行数"这种算法——那会鼓励往实现里灌水，这里衡量的是杠杆，不是行数比例。

接口和 API 是一回事吗？为什么用"接缝"而不是"边界"？

不是。API 和"签名"都太窄，它们只覆盖类型层面的表面；这里说的接口包括调用方为了正确使用模块必须知道的一切：不变量、顺序约束、错误模式、必需的配置、性能特征。"边界"这个说法则被 DDD 的限界上下文占用了，含义容易混淆，所以技能统一使用"接缝"（seam，出自 Michael Feathers）——指一个你无需修改该处就能改变行为的位置，也就是模块接口所在的地点。同理，技能也避免使用"组件""服务"来指代模块。

这个技能会直接帮我写代码或完成重构吗？

不会。它提供的是设计语言和判断准则，不是代码生成器或自动化重构工具——输出的是一致的概念、判断标准和讨论框架。它也不规定模块的尺度，函数、类、包、跨层切片都适用。实际动手改代码、写测试仍需要你或你的编程助手来完成；技能的价值在于让这些讨论和决策有共同的、精确的词汇可用。