Language（词汇）

本 skill 每条建议使用的共享词汇。精确使用这些 term——不要 substitute「component」「service」「API」或「boundary」。一致语言就是 whole point。

Terms（术语）

Module（模块）
Anything with an interface and an implementation. Deliberately scale-agnostic — 同样适用于 function、class、package 或跨 tier slice。
避免：unit、component、service。

Interface（接口）
Caller 为正确使用 module 必须知道的一切。包括 type signature，还有 invariants、ordering constraints、error modes、required configuration、performance characteristics。
避免：API、signature（太窄——仅指 type-level surface）。

Implementation（实现）
Module 内部——其 code body。与 Adapter 不同：可以是 small adapter + large implementation（Postgres repo），或 large adapter + small implementation（in-memory fake）。Seam 是话题时用「adapter」；否则用「implementation」。

Depth（深度）
Interface 处的 leverage——caller（或 test）每 unit 需学习的 interface 能 exercise 多少 behavior。Deep module 是大量 behavior 在 small interface 后。Shallow module 是 interface 几乎与 implementation 一样 complex。

Seam (from Michael Feathers)（接缝）
可 alter behavior 而无需在该处 edit 的位置。Module interface 所在的 location。Seam 放哪是独立 design decision，与后面放什么 distinct。

避免：boundary（与 DDD bounded context overloaded）。

Adapter（适配器）
在 seam 处 satisfy interface 的 concrete thing。描述 role（填什么 slot），非 substance（里面是什么）。

Leverage（杠杆）
Caller 从 depth 得到什么。每 unit interface 学习得到更多 capability。One implementation 在 N call site 与 M test 上 pay back。

Locality（局部性）
Maintainer 从 depth 得到什么。Change、bug、knowledge、verification 集中在一处而非 spread 到 caller。Fix once，fixed everywhere。

Principles（原则）

• Depth 是 interface 的属性，非 implementation。 Deep module 内部可由 small、mockable、swappable part 组成——它们不是 interface 一部分。Module 可有 internal seams（implementation private，own test 用）以及 interface 处的 external seam。
• The deletion test。 想象 delete module。若 complexity 消失，module 没 hide 任何东西（pass-through）。若 complexity 在 N caller 重现，module 在 earn keep。
• The interface is the test surface。 Caller 与 test cross 同一 seam。若想 test past interface，module 可能 shape 错了。
• One adapter means hypothetical seam. Two adapters means real one. 除非 something 真的在 seam 上 vary，否则不要 introduce seam。

Relationships（关系）

• Module 有 exactly one Interface（present 给 caller 与 test 的 surface）。
• Depth 是 Module 的属性，相对其 Interface 测量。
• Seam 是 Module 的 Interface 所在处。
• Adapter 在 Seam 处 satisfy Interface。
• Depth 为 caller 产生 Leverage，为 maintainer 产生 Locality。

Rejected framings（拒绝的 framing）

• Depth 作为 implementation-lines 与 interface-lines 之比（Ousterhout）：reward padding implementation。我们用 depth-as-leverage。
• 「Interface」仅指 TypeScript interface 或 class public methods：太窄——此处 interface 包括 caller 必须知道的 every fact。
• 「Boundary」：与 DDD bounded context overloaded。说 seam 或 interface。