About codebase-design
A design skill for planning codebase structure before implementation, intended for developers and coding agents. It focuses on cohesive modules, one-way dependencies, minimal interfaces, discoverability, and testability.
Key features
- 01Group modules by reason for change
- 02Keep dependencies one-way and acyclic
- 03Minimize and centralize public interfaces
- 04Design discoverable structure for agents
- 05Inject dependencies through interfaces
- 06Define structural completion checks
Use cases
- 01Plan the structure of a new feature
- 02Refactor modules and dependency boundaries
- 03Improve codebase navigation and testability
Install
Copy the command and run it in a terminal.
$
npx skills add https:/After installing, type/codebase-designin Claude Code to confirm it loaded.
Details
From the project README代码库设计
在动手写代码前把结构定对。讨论任何结构决策，都按下面的纪律来。重构现有结构时，先写出新结构，迁移完所有调用方，再删旧路径。拿不准划分时，用 tracer bullets 先垂直打通一条调用链，验证结构后再横向铺开。
模块划分
- 按变化原因聚合：一个模块只因一种原因变。两个东西会因不同理由、在不同时间变化，就分进两个模块。哪个模块说不清“我因什么而变”，划分就没做完。
- 依赖单向：整个依赖图的箭头朝一个方向，高层不直接依赖低层细节。业务策略不引用具体的存储、网络实现。低层要服务高层时，高层声明接口、低层实现（依赖倒置），让依赖从细节指向抽象。
- 循环依赖是拆分信号：A 依赖 B、B 又依赖 A，说明两者共同依赖的第三个模块还没抽出来。先拆出共享部分消除循环，不要用延迟引用或运行时查找把循环藏起来。
- 新增先归位：新需求先找它属于哪个已有模块的变化原因，一个都套不进时再新建。新建模块要有新的变化原因，理由不能是目录看起来干净。
接口设计
- 最小暴露面：只导出调用方需要的符号。每导出一个，就冻住一块内部实现。没有调用方的导出，降回私有。
- 公共类型收敛在少数入口：调用方从一两个入口文件拿到全部公共面。类型散落在深层目录会逼调用方了解内部布局。
- 从使用者倒推形状：先写调用方代码再定接口。写得别扭的调用现场就是接口的缺陷清单，调用方代码顺势成为接口的第一个测试。
为 AI 导航设计
结构同时服务人和 agent，按可发现性组织：
- 目录约定稳定：同类东西总在同类位置，换模块不用重新学布局。
- 每个模块一个入口文件，公共面从入口完整可见。
AGENTS.md与CONTEXT.md里的指针指向入口文件，不散指内部实现。- 与 domain-modeling 协作：定稿的术语写进
CONTEXT.md，难取舍的划分决策（两种分法各有代价）记成 ADR。
可测试性
- 依赖穿过接口注入：网络、文件、时钟、随机数都从接口进来，业务逻辑不直接绑定 IO。
- 新增模块先想怎么测它：说不出替换哪几个依赖就能单独驱动这个模块，就回到模块划分改设计。
完成条件
- 划分方案可解释：每个模块一句话说清它因什么而变
- 依赖图无环：列出模块间的依赖方向，逐条确认没有循环
- 依赖单向：高层不直接依赖低层实现，跨层依赖通过接口
- 接口暴露面最小：入口之外没有导出符号
- 入口可发现：公共面从入口文件可见，AGENTS.md 与 CONTEXT.md 的指针指向入口
Comments
Markdown supported