codebase-design

Files (4)

• DEEPENING.md
• DESIGN-IT-TWICE.md
• SKILL.md
• openai.yaml · agents/

SKILL.md (first lines)

# 代码库设计

设计 **deep module**：小接口后面藏大量行为，放在干净的 seam 上，通过该接口可测。凡是在设计或重组代码的地方，都用这套语言和这些原则。目标是：调用方获得杠杆，维护者获得局部性，所有人获得可测试性。

## 词汇表

精确使用这些术语 — 不要用「component」「service」「API」或「boundary」替换。语言一致才是全部意义所在。

**Module** — 任何带有接口和实现的东西。刻意与尺度无关：一个函数、类、包，或跨层的切片。_避免_：unit、component、service。

**Interface** — 调用方要正确使用该模块必须知道的一切：类型签名，以及不变量、顺序约束、错误模式、必需配置和性能特征。_避免_：API、signature（太窄 — 它们只指类型层表面）。

**Implementation** — 模块内部，它的代码体。区别于 **Adapter**：一个东西可以是小 adapter 配大实现（Postgres repo），也可以是大 adapter 配小实现（内存 fake）。当话题是 seam 时用「adapter」；否则用「implementation」。

**Depth** — 接口上的杠杆：调用方（或测试）每学习一单位接口所能行使的行为量。当大量行为坐在小接口后面时，模块是 **deep**；当接口几乎和实现一样复杂时，是 **shallow**。

**Seam** _(Michael Feathers)_ — 你可以在不编辑该处的情况下改变行为的地方；模块接口所在的 *位置*。把 seam 放在哪里是独立的设计决策，不同于后面放什么。_避免_：boundary（与 DDD 的 bounded context 过载）。

**Adapter** — 在 seam 上满足某个接口的具体物。描述的是 *角色*（它填哪个槽），不是实质（里面是什么）。

**Leverage** — 调用方从 depth 得到的东西：每学习一单位接口获得更多能力。一份实现在 N 个调用点和 M 个测试上得到回报。

**Locality** — 维护者从 depth 得到的东西：变更、bug、知识和验证集中在一处，而不是散落到调用方。修一次，处处修好。

## Deep vs shallow

**Deep module** = 小接口 + 大量实现：

```
┌─────────────────────┐
│   Small Interface   │  ← Few methods, simple params
├─────────────────────┤
│                     │
│  Deep Implementation│  ← Complex logic hidden
│                     │
└─────────────────────┘
```

**Shallow module** = 大接口 + 很少实现（避免）：

```
┌─────────────────────────────────┐
│       Large Interface           │  ← Many methods, complex params
├─────────────────────────────────┤
│  Thin Implementation            │  ← Just passes through
└─────────────────────────────────┘
```

设计接口时，问：

- 我能减少方法数量吗？
- 我能简化参数吗？
- 我能把更多复杂度藏在里面吗？

## 原则

- **Depth 是接口的属性，不是实现的属性。** 一个 deep module 内部可以由小的、可 mock、可替换的部分组成 — 它们只是不属于接口。一个模块可以有 **内部 seam**（对实现私有，供自己的测试使用），也可以有接口处的 **外部 seam**。
- **删除测试。** 想象删掉这个模块。若复杂度随之消失，它只是直通。若复杂度在 N 个调用方上重新出现，它就在赚回自己的位置。
- **接口就是测试面。** 调用方和测试穿过同一条 seam。若你想测 *越过* 接口，模块的形状大概就不对。
- **一个 adapter 意味着假设的 seam。两个 adapter 意味着真正的 seam。** 除非确实有东西在 seam 两侧变化，否则不要引入 seam。

## 为可测试性而设计

好的接口让测试变得自然：

1. **接受依赖，不要创建依赖。**

   ```typescript
   // Testable
   function processOrder(order, paymentGateway) {}

   // Hard to test
   function processOrder(order) {
     const gateway = new StripeGateway();
   }
   ```

2. **返回结果，不要产生副作用。**

   ```typescript
   // Testable
   function calculateDiscount(cart): Discount {}

   // Hard to test
   function applyDiscount(cart): void {
     cart.total -= discount;
   }
   ```

3. **小表面积。** 更少方法 = 需要更少测试。更少参数 = 更简单的测试准备。

## 关系

- 一个 **Module** 恰好有一个 **Interface**（它呈现给调用方和测试的表面）。
- **Depth** 是 **Module** 的属性，相对其 **Interface** 来度量。
- **Seam** 是 **Module** 的 **Interface** 所在之处。
- **Adapter** 坐在 **Seam** 上并满足该 **Interface**。
- **Depth** 为调用方产生 **Leverage**，为维护者产生 **Locality**。

## 被拒绝的框架

- **把 Depth 当成实现行数与接口行数之比**（Ousterhout）：会奖励给实现注水。我们改用 depth-as-leverage。
- **把「Interface」当成 TypeScript 的 `interface` 关键字或类的公开方法**：太窄 — 这里的 interface 包括调用方必须知道的每一项事实。
- **「Boundary」**：与 DDD 的 bounded context 过载。说 **seam** 或 **interface**。

## 再往深处

- **在给定依赖的情况下加深一个簇** — 见 [DEEPENING.md](DEEPENING.md)：依赖类别、seam 纪律，以及替换-不要-叠层的测试。
- **探索备选接口** — 见 [DESIGN-IT-TWICE.md](DESIGN-IT-TWICE.md)：拉起并行 subagent，用几种截然不同的方式设计接口，再按 depth、locality 和 seam 位置比较。

From shenjunjian/matt-skill-cn, MIT.

More from shenjunjian/matt-skill-cn