codebase-design

代码库设计

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

模块划分

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

接口设计

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

为 AI 导航设计

结构同时服务人和 agent，按可发现性组织：

• 目录约定稳定：同类东西总在同类位置，换模块不用重新学布局。
• 每个模块一个入口文件，公共面从入口完整可见。
• AGENTS.md 与 CONTEXT.md 里的指针指向入口文件，不散指内部实现。
• 与 domain-modeling 协作：定稿的术语写进 CONTEXT.md，难取舍的划分决策（两种分法各有代价）记成 ADR。

可测试性

• 依赖穿过接口注入：网络、文件、时钟、随机数都从接口进来，业务逻辑不直接绑定 IO。
• 新增模块先想怎么测它：说不出替换哪几个依赖就能单独驱动这个模块，就回到模块划分改设计。

完成条件

• 划分方案可解释：每个模块一句话说清它因什么而变
• 依赖图无环：列出模块间的依赖方向，逐条确认没有循环
• 依赖单向：高层不直接依赖低层实现，跨层依赖通过接口
• 接口暴露面最小：入口之外没有导出符号
• 入口可发现：公共面从入口文件可见，AGENTS.md 与 CONTEXT.md 的指针指向入口