Lesson 0005 · Engineering · 人和 AI 都能启动（model-invoked）· 词汇课

codebase-design：模块设计的共享词汇

codebase-design 是一套用来谈论模块设计的共享词汇： 什么算模块、接口、深度、接缝，每个词都有精确定义，不许随便换成近义词。 你什么时候会碰到它？当你想说「这个模块只是在转发调用」却找不到准确的词时， 或者当 improve-codebase-architecture、tdd、to-spec 这些 skill 的正文里引用这套词汇时。 词汇本身在 SKILL.md 里，它还有两个搭档文件： DEEPENING.md 讲怎么把浅模块加深，DESIGN-IT-TWICE.md 讲怎么并行设计几种接口。 学完这节课，你能用这套词判断一个模块是深还是浅、接缝放得对不对， 也知道行为不对时该去改哪个文件的哪一段。

1. 它在整个系统里站在哪

0001 把 22 个 skill 分成三层：配置层（跑一次性的初始设置）、编排层（你手动启动的完整流程）、 纪律层（被反复调用的基本功）。codebase-design 属于纪律层，而且是纪律层里特殊的一类： 它不规定流程，只规定词汇，作者把这类 skill 叫词汇地板（ask-matt 里写作 Vocabulary underneath）——主流程上的 skill 都可以踩在这块地板上说话。 它是 model-invoked 的（人和 AI 都能启动）：别的 skill 想用它， 只要在正文里写一句自然语言的「Run the /codebase-design skill」就能把它拉进来 （0001 讲过，这叫 prose 调用），你也可以单独把它当参考书翻。

它和 0004 讲的 domain-modeling 是一对平行的词汇地板，各管一套词：

ask-matt 的原文把这两个地板放在 Vocabulary underneath 一节： 当你的问题是用词问题、而不是要跑一整条流程时，直接用它； 如果是跑流程的过程中碰到用词问题，让上面那个 skill 把它拉进来就行。 注意别把两件事混进同一段对话：「改领域术语」和「加深模块形状」是两块地板， 混着用，两边留下的记录都会被搞脏。

罗盘：MISSION.md · 地图：0001 · 平行的一课：0004 domain-modeling · 路由规则：ask-matt/SKILL.md 的 Vocabulary underneath 一节

2. 它是什么、什么时候用

2.1 它是一套语言，不是一条流程

docs 和 SKILL.md 的说法一致：这个 skill 讲的是怎么设计 deep module（深模块）——一个模块把大量行为藏在一个小接口后面， 立在一条干净的 seam（接缝，就是不用改那处代码就能换行为的位置）上， 并且通过那个接口就能测试。目标是：给调用它的人 leverage （杠杆，学会一点接口就能驱动很多行为），给维护它的人 locality （局部性，改动和知识集中在一处），给所有人可测性。 这几个词在第 3 节都有精确定义，先有个印象就行。

2.2 AI 什么时候会自己加载它

frontmatter 里的 description 字段写明了触发条件：当你要设计或改进一个模块的接口、 想找加深模块的机会、要决定接缝放在哪、想让代码更好测或对 AI 更好读， 或者别的 skill 需要这套词汇时——用它。

权威原文： skills/engineering/codebase-design/SKILL.md · 给人看的叙事版： docs/engineering/codebase-design.md （aihero.dev/skills-codebase-design）

3. 核心词汇：八个词，一个都不能换

SKILL.md 开篇就要求：用这些词，不要换成 component / service / API / boundary。 词汇统一是这个 skill 存在的理由——换成近义词，会把真正要区分的差别抹掉。 下面这张表把每个词的定义按 SKILL.md 原文压缩了一遍，第一次读可以慢一点。

4. 深模块 vs 浅模块，和删除测试

Deep module                          Shallow module（要避免）
┌─────────────────────┐              ┌─────────────────────────────────┐
│   Small Interface   │  少方法、简参 │       Large Interface           │  多方法、复杂参
├─────────────────────┤              ├─────────────────────────────────┤
│                     │              │  Thin Implementation            │  几乎只转发
│  Deep Implementation│  复杂逻辑隐藏 │                                 │
│                     │              └─────────────────────────────────┘
└─────────────────────┘

设计接口时，问自己三个问题：
  · 能否减少方法数？
  · 能否简化参数？
  · 能否把更多复杂度藏进里面？

4.1 删除测试（deletion test）

想象把这个模块整个删掉，然后看复杂度去了哪：

• 如果复杂度跟着它一起消失——说明它只是个 pass-through（转手层：什么都不加工，只把调用转发给下一层），很浅，删掉也不亏，它没挣到自己存在的价值。
• 如果复杂度在 N 个调用者身上重新冒出来——说明它真的在干活，挣到了自己存在的价值，值得加深或保留。

improve-codebase-architecture 在找浅模块时会主动套用这个测试，问： 「删掉它，复杂度是被集中消灭了，还是只是搬了个家？」 答案是「会集中」，才是你想要的加深信号。

5. 四条原则

四条原则全部围绕一件事：深度是长在接口上的，不是长在实现上的。

6. 为可测性设计

SKILL.md 给了三条可以直接照做的经验法则（和 tdd、mocking 的纪律同方向）：

1. Accept dependencies, don't create them. 依赖从参数传进来（注入），别在函数体里 new StripeGateway()。
2. Return results, don't produce side effects. 优先返回值（比如 calculateDiscount(cart): Discount）， 而不是原地改状态、留下难以断言的副作用（side effect：函数除了返回值之外，对外界造成的改动）。
3. Small surface area. 接口面要小：方法越少，要写的测试越少；参数越少，测试数据越好准备。

7. 关系图，和被明确否定的说法

                    ┌──────────────┐
                    │   Module     │  恰好有一个 Interface
                    └──────┬───────┘
                           │ presents
                           ▼
                    ┌──────────────┐
         Depth ───► │  Interface   │  Depth 相对 Interface 度量
                    └──────┬───────┘
                           │ lives at
                           ▼
                    ┌──────────────┐
                    │    Seam      │  位置决策 ≠ 背后装什么
                    └──────┬───────┘
                           │ filled by
                           ▼
                    ┌──────────────┐
                    │   Adapter    │  满足 Interface 的具体物
                    └──────────────┘

Depth ──produces──► Leverage（调用者）
                 └──► Locality（维护者）

7.1 被明确否定的三种说法

• 「深度 = 实现行数 ÷ 接口行数」（Ousterhout 给过的一种度量）： 这么算会奖励给实现注水。本仓库用的是「深度 = 杠杆」。
• 「接口」= TypeScript 的 interface 关键字、或类的 public 方法： 太窄了；这里的接口包括调用者必须知道的每一个事实。
• 「boundary」：这个词和 DDD 的 bounded context 撞车，意思已经过载。请说 seam 或 interface。

8. DEEPENING.md：怎么把浅模块加深

DEEPENING.md 假定你已经会第 3 节的词汇，它回答的问题是： 给定一个依赖，怎么安全地把一簇浅模块加深。 「deepening opportunity」（加深机会）在 architecture 那条 skill 里， 指「把浅模块变深」的重构候选（目的是可测性和 AI 可导航性——让 AI 更容易读懂代码、找到路）； 在这个文件里，它落成三件具体的事：依赖分类、接缝纪律、测试策略。

8.1 依赖分四类，决定跨接缝怎么测

对类别 3，推荐的表达形状是（按原文的意图）： 「在接缝上定义 port，实现一个 HTTP adapter 给生产环境、一个内存 adapter 给测试， 这样即使部署横跨网络，逻辑也落在一个深模块里。」

8.2 加深时的接缝纪律

• 再强调一次：一个 adapter = 假想的接缝；两个 = 真接缝。拿不出至少两个正当的 adapter（通常是生产 + 测试），就不要开 port。
• 内部接缝 vs 外部接缝：深模块可以有只给自己测试用的内部接缝；别为了测试把它们捅到对外接口上。

8.3 测试策略：替换，不叠加（replace, don't layer）

• 浅模块上的旧单元测试，一旦加深后的接口上有了新测试 → 把旧的删掉（留着是浪费）。
• 新测试写在加深后模块的接口上：接口就是测试面。
• 断言接口上可观察的结果，不断言内部状态。
• 测试应该扛得住内部重构：它描述行为，不描述实现。实现一改测试就炸 → 说明你测穿了接口。

9. DESIGN-IT-TWICE.md：同一个接口并行设计几种

这个文件出自 Ousterhout 的「Design It Twice」（设计两遍）：第一个想法多半不是最好的。 当你已经选定了一个加深候选、想探索几种不同的接口方案时，用并行子代理模式 （sub-agent：主 agent 派出去、各自独立干活的 agent）。 architecture 的面试循环结尾也会点名它：想看多种接口设计 → 运行 /codebase-design 并走这个模式。

9.1 三步走

9.2 每个 agent 各自的设计约束（默认四个方向）

Agent 1  Minimize interface — 1–3 entry points；最大化每点 leverage
Agent 2  Maximise flexibility — 多用例与扩展
Agent 3  Optimise for most common caller — 默认路径极简
Agent 4  （若适用）Ports & adapters，围绕跨 seam 依赖

9.3 每个子代理必须交出五样东西

1. 接口（类型、方法、参数，加上必须恒成立的条件、调用顺序、出错模式）
2. 用法示例（调用者怎么用）
3. 实现在接缝后面藏了什么
4. 依赖策略和 adapters（对照 DEEPENING 的分类）
5. 取舍：哪里杠杆厚、哪里薄

10. 谁在用这套词

                ┌─────────────────────────┐
                │   codebase-design       │  词汇的唯一权威出处
                │   (+ DEEPENING,         │
                │    DESIGN-IT-TWICE)     │
                └───────────┬─────────────┘
           ┌────────────────┼────────────────────┐
           ▼                ▼                    ▼
 improve-codebase-     tdd / implement      to-spec
 architecture          （在接缝上测）       （画接缝草图）
 · 找浅点、套删除测试   · 先确认接缝        · 优先复用已有接缝
 · 报告里用这套词      · 接口=测试面       · 接缝尽量少（理想 1）
 · 面试后可回本 skill   · 反对测试耦合实现
   做 design-it-twice

11. 会留下什么、用完接什么、想微调改哪里

11.1 每个动作会不会写文件

11.2 用完之后，下一步去哪

1. 只是把词说对了、形状也想清楚了 → 回到你当前的流程；如果你在写功能，让 to-spec 记下模块、接口和测试决策，或者直接在约定好的接缝上用 tdd 开写。
2. 从 architecture 报告里挑中了一个加深候选 → 走面试的决策树 → 想法进 /grill-with-docs 主流程 → to-spec / tickets / implement（ask-matt 的说法：扫描产生想法，设计工作台是 codebase-design）。
3. 跑了 design-it-twice → 采纳推荐方案（或混合体）→ 把接口决策写进 spec 或 ADR（如果不可逆）→ 实现阶段 tdd 只测那条外部接缝。
4. 加深完成了 → 按 DEEPENING 的要求：新测试写在加深后的接口上；删掉浅层的旧测试；之后的内部重构不应该逼你改测试。

11.3 行为不对时，去改哪个文件的哪一段

12. 检索练习

先别往回翻表，凭记忆答。选项的长度刻意对齐，不会从版式泄题。术语以本课和 SKILL.md 的精确定义为准。

13. 下一课与一手材料

本课主一手材料（请打开原文读，不要只背本页摘要）：

• skills/engineering/codebase-design/SKILL.md —— 词汇、深/浅、原则、可测性、关系图、被否定的说法。
• …/DEEPENING.md —— 依赖四类、接缝纪律、替换不叠加。
• …/DESIGN-IT-TWICE.md —— 并行子代理接口设计。
• docs/engineering/codebase-design.md —— 给人看的叙事版：「语言不是流程 / 什么时候用 / 谁引用它」。
• 使用方对照： improve-codebase-architecture · tdd · to-spec（接缝一节）· ask-matt（Vocabulary underneath 一节）。

速查页（本课同步）： reference/codebase-design.html

导航： 上一课 0004 domain-modeling （平行的词汇地板：一个管领域词，一个管模块形状）。 总览仍回 0001 系统地图； 面试编排见 0003。

建议下一课（0006，还没写）： 按 NOTES.md 的课程顺序，两个词汇地板之后是 handoff（再往后是 research / prototype）——跨会话的桥，和「可运行答案」的岔路。 和本课的交接点：当 design-it-twice 或 architecture 的面试把上下文塞满时， 用 handoff 换个新会话，别在一个已经变迟钝的窗口里硬写加深后的接口。