代码库设计

在动手写代码前把结构定对。讨论任何结构决策，都按下面的纪律来。重构现有结构时，先写出新结构，迁移完所有调用方，再删旧路径。拿不准划分时，用 tracer bullets 先垂直打通一条调用链，验证结构后再横向铺开。

模块划分

• 按变化原因聚合：一个模块只因一种原因变。两个东西会因不同理由、在不同时间变化，就分进两个模块。哪个模块说不清“我因什么而变”，划分就没做完。
• 依赖单向：整个依赖图的箭头朝一个方向，高层不直接依赖低层细节。业务策略不引用具体的存储、网络实现。低层要服务高层时，高层声明接口、低层实现（依赖倒置），让依赖从细节指向抽象。
• 循环依赖是拆分信号：A 依赖 B、B 又依赖 A，说明两者共同依赖的第三个模块还没抽出来。先拆出共享部分消除循环，不要用延迟引用或运行时查找把循环藏起来。
• 新增先归位：新需求先找它属于哪个已有模块的变化原因，一个都套不进时再新建。新建模块要有新的变化原因，理由不能是目录看起来干净。

接口设计

• 最小暴露面：只导出调用方需要的符号。每导出一个，就冻住一块内部实现。没有调用方的导出，降回私有。
• 公共类型收敛在少数入口：调用方从一两个入口文件拿到全部公共面。类型散落在深层目录会逼调用方了解内部布局。
• 从使用者倒推形状：先写调用方代码再定接口。写得别扭的调用现场就是接口的缺陷清单，调用方代码顺势成为接口的第一个测试。

为 AI 导航设计