用途:codebase-design 提供一套共享词汇,用于一致地推理模块边界,帮助设计深层、可测试的模块并评估接口、实现、接缝与适配器。它只提供语言和设计练习,不实现、审查、排期或交付变更;决策、产物与副作用仍由调用它的工作流负责。
主要概念:模块(在边界后拥有某项能力的聚合单元)、接口(调用者使用模块必须理解的表面)、实现(接口后隐藏的决策与机制)、深度(相对较小的接口隐藏的有用复杂度)、接缝(可替换并观察行为或依赖的刻意边界)、适配器(模块内部模型与外部依赖或协议之间的翻译层)、杠杆(调用者每学一个概念所获得的价值)、局部性(变更可在一个连贯位置被理解和完成的程度)。
设计原则:深层模块提供高杠杆,调用者学习小而稳定的接口,模块自身承担大量策略与协调;浅层模块只是转移复杂度。优先选择将共同变化的行为分组、把不变量和依赖策略留在拥有者模块内部、让常见操作容易且不阻碍必要变化、在真实依赖边界设接缝、让测试针对公共接口而非内部调用链、通过减少一次变更所需文件和概念来提升局部性的边界。避免为抽象而抽象;没有持久策略的小实现可内联更清晰,直通包装通常增加表面而非深度。
使用方式:先命名能力与需要它的调用者;列出模块应隐藏的策略与复杂度;画出服务真实调用者操作的最小接口;对依赖分类并用 DEEPENING.md 放置最窄的有用接缝;用 DESIGN-IT-TWICE.md 以对比设计压测边界;在推荐设计前比较深度、杠杆、局部性、接缝位置与测试表面。词汇是描述性而非规定性的,具体情境决定模块应加深、合并、保持小还是内联。
限制:资料未提供安装命令、平台、收费或具体代码示例;实际迭代、生成或修改代码的效果与兼容性暂未提供。