AGENT SKILL

codebase-design

用于设计深模块的共享词汇。用户希望设计或改进模块接口、寻找深化机会、决定接缝位置、提高代码的可测试性或 AI 可导航性,或其他技能需要深模块词汇时使用。

License 许可
MIT
最近更新
2026-07-23
Stars
★ 1
Forks
0

01 前言 Front Matter

name
codebase-design
description
用于设计深模块的共享词汇。用户希望设计或改进模块接口、寻找深化机会、决定接缝位置、提高代码的可测试性或 AI 可导航性,或其他技能需要深模块词汇时使用。

02 资源文件 3

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 个调用方中,说明它确实物有所值。
  • 接口就是测试表面。 调用方和测试跨越同一个接缝。如果你想越过接口深入测试,模块的形态很可能有误。
  • 一个适配器意味着假想接缝,两个适配器才意味着真实接缝。 除非确实有某些内容会跨接缝变化,否则不要引入接缝。

为可测试性而设计

良好的接口让测试自然而然:

  1. 接收依赖,不要创建依赖。

    // 可测试
    function processOrder(order, paymentGateway) {}
    
    // 难以测试
    function processOrder(order) {
      const gateway = new StripeGateway();
    }
    
  2. 返回结果,不要产生副作用。

    // 可测试
    function calculateDiscount(cart): Discount {}
    
    // 难以测试
    function applyDiscount(cart): void {
      cart.total -= discount;
    }
    
  3. 表面积要小。 方法越少 = 所需测试越少。参数越少 = 测试设置越简单。

关系

  • 一个模块恰好有一个接口(它向调用方和测试呈现的表面)。
  • 深度是模块的属性,依据其接口衡量。
  • 接缝是模块的接口所在之处。
  • 适配器位于接缝处,并满足接口。
  • 深度为调用方带来杠杆效应,为维护者带来局部性。

不采用的表述方式

  • 把深度视为实现行数与接口行数之比(Ousterhout):这会奖励填充实现。我们改用“深度即杠杆效应”。
  • 把“接口”理解为 TypeScript 的 interface 关键字或类的公共方法:范围过窄——这里的接口包括调用方必须知道的每项事实。
  • “边界”:与 DDD 的限界上下文含义重叠。应使用接缝或接口。

继续深入

  • 根据依赖深化模块簇——参见 DEEPENING.md:依赖类别、接缝纪律,以及“替换而非叠加”的测试策略。
  • 探索备选接口——参见 DESIGN-IT-TWICE.md:启动并行子智能体,以若干种截然不同的方式设计接口,然后比较深度、局部性和接缝位置。

04 同仓库更多 Skills