codebase-design
用于设计深模块的共享词汇。用户希望设计或改进模块接口、寻找深化机会、决定接缝位置、提高代码的可测试性或 AI 可导航性,或其他技能需要深模块词汇时使用。
- License 许可
- MIT
- 最近更新
- 2026-07-23
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- codebase-design
- description
- 用于设计深模块的共享词汇。用户希望设计或改进模块接口、寻找深化机会、决定接缝位置、提高代码的可测试性或 AI 可导航性,或其他技能需要深模块词汇时使用。
02 资源文件 3
- 参考文档agents/openai.yaml90 B
- 参考文档DEEPENING.md2.4 KB
- 参考文档DESIGN-IT-TWICE.md2.6 KB
03 SKILL.md 正文
代码库设计
设计深模块:在清晰的接缝处,以小接口承载大量行为,并可通过该接口进行测试。凡是设计或重构代码,都应使用这套语言和原则。目标是让调用方获得杠杆效应,让维护者获得局部性,并让所有人都获得可测试性。
术语表
必须准确使用这些术语——不得替换为“component”“service”“API”或“boundary”。这套方法的核心正是保持语言一致。
模块(Module)——任何具有接口和实现的事物。刻意不限定规模:可以是函数、类、包,也可以是跨层切片。避免使用:unit、component、service。
接口(Interface)——调用方为正确使用模块而必须知道的一切:不仅包括类型签名,还包括不变量、顺序约束、错误模式、必需配置和性能特征。避免使用:API、signature(范围过窄——它们仅指类型层面的表面)。
实现(Implementation)——模块内部的内容,即其代码主体。它不同于适配器(Adapter):一个事物可以是实现很大的小型适配器(Postgres 仓库),也可以是实现很小的大型适配器(内存假对象)。讨论接缝时使用“适配器”,其他情况下使用“实现”。
深度(Depth)——接口处的杠杆效应:调用方(或测试)每学习一个单位的接口,便可运用多少行为。当大量行为位于小接口之后时,模块是深的;当接口几乎与实现一样复杂时,模块是浅的。
接缝(Seam) (Michael Feathers)——无需在某处直接编辑就能改变行为的位置;即模块接口所在的位置。接缝放在哪里本身就是一项设计决策,与接缝之后放什么不同。避免使用:boundary(与 DDD 的限界上下文含义重叠)。
适配器(Adapter)——在接缝处满足接口的具体事物。它描述的是角色(填补哪个位置),而非实质(内部有什么)。
杠杆效应(Leverage)——调用方从深度中获得的收益:每学习一个单位的接口,就能获得更多能力。一份实现可惠及 N 个调用点和 M 项测试。
局部性(Locality)——维护者从深度中获得的收益:变更、缺陷、知识和验证集中在一处,而不是散布于各调用方。修复一次,处处生效。
深与浅
深模块 = 小接口 + 大量实现:
┌─────────────────────┐
│ 小型接口 │ ← 方法少,参数简单
├─────────────────────┤
│ │
│ 大量实现 │ ← 隐藏复杂逻辑
│ │
└─────────────────────┘
浅模块 = 大接口 + 少量实现(应避免):
┌─────────────────────────────────┐
│ 大型接口 │ ← 方法多,参数复杂
├─────────────────────────────────┤
│ 少量实现 │ ← 仅作透传
└─────────────────────────────────┘
设计接口时,问自己:
- 能否减少方法数量?
- 能否简化参数?
- 能否在内部隐藏更多复杂性?
原则
- 深度是接口的属性,而非实现的属性。 深模块内部可以由小型、可模拟、可替换的部件组成——只是这些部件不属于接口。模块既可以有内部接缝(实现私有,供自身测试使用),也可以在接口处有外部接缝。
- 删除测试。 想象一下删除该模块。如果复杂性消失了,它只是透传层;如果复杂性重新出现在 N 个调用方中,说明它确实物有所值。
- 接口就是测试表面。 调用方和测试跨越同一个接缝。如果你想越过接口深入测试,模块的形态很可能有误。
- 一个适配器意味着假想接缝,两个适配器才意味着真实接缝。 除非确实有某些内容会跨接缝变化,否则不要引入接缝。
为可测试性而设计
良好的接口让测试自然而然:
-
接收依赖,不要创建依赖。
// 可测试 function processOrder(order, paymentGateway) {} // 难以测试 function processOrder(order) { const gateway = new StripeGateway(); } -
返回结果,不要产生副作用。
// 可测试 function calculateDiscount(cart): Discount {} // 难以测试 function applyDiscount(cart): void { cart.total -= discount; } -
表面积要小。 方法越少 = 所需测试越少。参数越少 = 测试设置越简单。
关系
- 一个模块恰好有一个接口(它向调用方和测试呈现的表面)。
- 深度是模块的属性,依据其接口衡量。
- 接缝是模块的接口所在之处。
- 适配器位于接缝处,并满足接口。
- 深度为调用方带来杠杆效应,为维护者带来局部性。
不采用的表述方式
- 把深度视为实现行数与接口行数之比(Ousterhout):这会奖励填充实现。我们改用“深度即杠杆效应”。
- 把“接口”理解为 TypeScript 的
interface关键字或类的公共方法:范围过窄——这里的接口包括调用方必须知道的每项事实。 - “边界”:与 DDD 的限界上下文含义重叠。应使用接缝或接口。
继续深入
- 根据依赖深化模块簇——参见 DEEPENING.md:依赖类别、接缝纪律,以及“替换而非叠加”的测试策略。
- 探索备选接口——参见 DESIGN-IT-TWICE.md:启动并行子智能体,以若干种截然不同的方式设计接口,然后比较深度、局部性和接缝位置。
04 同仓库更多 Skills
writing-great-skills
出色编写和编辑技能的参考资料——让技能具备可预测性的词汇与原则。
teach
在此工作区内向用户教授新的技能或概念。
handoff
将当前对话压缩成交接文档,以便另一个智能体接手。
grilling
围绕计划、决策或想法对用户进行不留情面的深度追问。当用户想对自己的思路进行压力测试,或使用任何“深度追问”触发措辞时使用。
grill-me
通过不留情面的深度追问打磨计划或设计。
obsidian-vault
使用 wikilink 和索引笔记搜索、创建和管理 Obsidian 仓库中的笔记。当用户想要在 Obsidian 中查找、创建或整理笔记时使用。