Lesson 0004 · 深课 · 人和 AI 都能启动 · 词汇层

domain-modeling：把项目里的叫法统一起来

一个项目里，「一个工作单元到底叫 Issue 还是 ticket」这种问题总得有人管——管它的就是 domain-modeling。它负责把术语定下来、写进 CONTEXT.md， 并把那些难反悔的架构决定记成 ADR。你跑 grill-with-docs、triage、wayfinder 时都会间接用到它。 学完这节课，你能说清：什么才算真的在跑这个 skill（打开术语表看一眼不算）、 它的文件怎么摆、什么决定够格写 ADR、行为不对时去改哪个文件的哪一段。

1. 这个 skill 在整套系统里站在哪

假设你正和 AI 讨论需求，它一会儿说「工单」一会儿说「issue」——词到底该谁管？就归 domain-modeling 管。它是纪律层里一个 Model-invoked 的 skill。纪律层就是那些可复用的基本功： 一般不单独交付什么，而是被完整流程调用。Model-invoked 的意思是人和 AI 都能启动它—— 你可以亲手输 /domain-modeling；AI 碰到合适的场景也会自己加载它； 别的 user-invoked skill 还可以在正文里写一句自然语言 「Run the /domain-modeling skill」来用上它（这叫 prose 调用： 用一句话声明调用，不是代码层面的 import）。

地图原文：ask-matt/SKILL.md 的 Vocabulary underneath 一段 · 两种启动方式的契约：.agents/invocation.md · 对外文档：docs/engineering/domain-modeling.md

2. 什么才算真的在跑它（而不是读了一眼术语表）

这是本 skill 最容易被误用的边界。 invocation.md 写得很直白：

Merely reading CONTEXT.md for vocabulary is a one-line prose pointer, not the domain-modeling skill. Only the active build/sharpen discipline (challenge terms, edge-case scenarios, write ADRs, update CONTEXT.md inline) is domain-modeling.

用大白话说：打开 CONTEXT.md 查个词，不算用了这个 skill——那只是「读」。 只有动手去建它、磨它才算：挑战用错的词、拿具体场景压测定义、写 ADR、当场改 CONTEXT.md。两者的区别全在下面这张表里：

SKILL 正文开头说的是同一个意思：本 skill 用于 changing the model, not just consuming it （改模型，不只是消费模型）。如果你只是写 issue 标题时避开了 _Avoid_ 列的同义词—— 那是读者该遵守的规则，不算跑了一次本 skill。

3. 谁会启动它

它的 description（frontmatter 里写给 AI 看的触发语）说的是：要敲定术语、 要建立 ubiquitous language、要记录架构决策，或者另一个 skill 需要维护领域模型时。 编排层（你手动启动的那些完整流程）里，在正文用 prose 调用它的「主客户」有这些 （以各 SKILL.md 为准）：

不启动它、只读 CONTEXT 的例子： tdd 写测试名时对齐术语表、diagnosing-bugs 的探索阶段、 to-spec 用项目里的词写需求文档、improve-codebase-architecture 的探索和报告阶段（先读；等你选定方案后，才在面试循环里主动改模型）。

grill-with-docs     → /grilling + /domain-modeling
grill-me            → /grilling only（明确不建 CONTEXT）
triage (if needed)  → /grilling + /domain-modeling
wayfinder chart     → /grilling + /domain-modeling（定下 destination）
wayfinder work      → 默认 /grilling + /domain-modeling；Notes 可点名其它 skill
improve-arch pick   → /grilling；过程中用 /domain-modeling 维持模型
                      （接口形状另用 /codebase-design）

4. 文件怎么摆：一个术语表，还是按领域分多个

布局由 setup 的 Section C 写进 docs/agents/domain.md 定下来； 本 skill 运行时看磁盘上有什么文件来判断：

• 根目录有 CONTEXT-MAP.md → 多领域布局（multi-context）：先读这张地图，再去找各个领域的术语表
• 只有根目录的 CONTEXT.md → 单领域布局（single-context），绝大多数仓库是这种
• 两个都没有 → 什么都不建，等第一个术语敲定时才建根 CONTEXT.md（懒创建）

4.1 单领域布局（默认）

/
├── CONTEXT.md
├── docs/
│   └── adr/
│       ├── 0001-event-sourced-orders.md
│       └── 0002-postgres-for-write-model.md
└── src/

本 skills 仓库本身就是单领域布局：根目录的 CONTEXT.md 定义了 Issue tracker / Issue / Decision ticket / Triage role。 ADR 若存在，约定路径是 docs/adr/——注意本仓库自己的作者决策放在 .agents/adr/，那是这个仓库自身的工程习惯； skill 教给目标业务仓库的默认路径是 docs/adr/，两者别混。

4.2 多领域布局（根目录有 CONTEXT-MAP.md）

/
├── CONTEXT-MAP.md
├── docs/
│   └── adr/                          ← system-wide decisions
├── src/
│   ├── ordering/
│   │   ├── CONTEXT.md
│   │   └── docs/adr/                 ← context-specific decisions
│   └── billing/
│       ├── CONTEXT.md
│       └── docs/adr/

地图文件（CONTEXT-MAP.md）列出每个领域的路径和领域之间的关系；这场会话聊的是哪个领域， 就改哪个领域的术语表。拿不准就问用户。setup 只有在探测到 monorepo 信号时才会 提供多领域这个选项；默认仍是单领域。

5. 会话里的动作清单

以下几条全部来自 SKILL.md 的 During the session 一节。 把这个 skill 用出作者水平，就是把它们当成一个循环反复做，不是 checklist 打勾走过场。

5.1 挑战和术语表冲突的词

用户用的词和现有 CONTEXT.md 冲突时，立刻点破，不要默默跟着新词走：

“Your glossary defines 'cancellation' as X, but you seem to mean Y — which is it?”

本仓库的对应例子：如果有人说「把 backlog 写进 triage」——CONTEXT 已经定过， 「backlog」不再是领域词，工具叫 Issue tracker，单元叫 Issue。 这时应该挑战，而不是在处理意见里继续写 backlog。

5.2 把模糊的词磨准

碰到含糊或一词多义的词，就提议一个精确的标准用词（canonical：以后全项目统一用它）：

“You're saying 'account' — do you mean the Customer or the User? Those are different things.”

本仓库的历史：backlog 曾经同时指「托管 issue 的工具」和「一堆没做的事」—— 后来拆成了 Issue tracker 和日常口语（不算领域词），并把这段歧义记进了 CONTEXT 的 Flagged ambiguities 一节。

5.3 拿具体场景压测定义

讨论概念之间的关系时，用具体场景去压边界和边角情况（edge case）。 例：Decision ticket 和普通 Issue——「wayfinder 地图关掉以后，这张子 issue 还算决策票吗？ implement 能不能直接把它当 tracer bullet（端到端打通的可执行小切片）来做？」 这样一问就逼出了结论：决策票的产物是「一个决定」，不是可执行的切片； 雾散了（看不清的东西都问清楚了）之后，要把决策交给 to-spec 汇总成正式需求， 而不是对着决策票直接 implement。

5.4 和代码对质

用户说「系统是这样工作的」→ 去对代码。说法和代码矛盾时，必须把矛盾摆上台面：

“Your code cancels entire Orders, but you just said partial cancellation is possible — which is right?”

这一步是这个 skill 和「只画图不对代码」的纸面领域设计（DDD）的分水岭： 语言和代码必须对齐，否则术语表会变成谎言。

5.5 当场更新 CONTEXT.md

术语一敲定就写，禁止攒着一批最后一起写。格式见下一节。 硬约束：

5.6 有节制地提议写 ADR

只有三个条件同时成立才提议写 ADR（见第 7 节）。缺任何一条，就跳过。

6. CONTEXT.md 的格式与本仓库的实例

格式的权威原文在 CONTEXT-FORMAT.md。

6.1 骨架

# {Context Name}

{一两句：这个 context 是什么、为何存在}

## Language

**Order**:
{一两句：它是什么}
_Avoid_: Purchase, transaction

**Invoice**:
A request for payment sent to a customer after delivery.
_Avoid_: Bill, payment request

6.2 四条格式规则

6.3 本仓库的 CONTEXT.md 是怎么示范这些规则的

打开 CONTEXT.md 对照着看：

• Context 名：Matt Pocock Skills——用一两句说明这是 agent skills 的集合，以及各仓库的配置怎么被消费。
• Issue tracker：托管 issue 的工具；_Avoid_ 列了 backlog manager / backlog backend / issue host。
• Issue：tracker 里的一个工作单元；口语里的 ticket 只在引用外部系统或 Decision ticket 时用。
• Decision ticket：wayfinder 的子 Issue，它的产物是一个决定，不是可构建的切片；限定词 decision 就是为了维持这个区分。
• Triage role：状态机标签；真实的字符串经过 docs/agents/triage-labels.md 映射。
• Relationships：tracker holds issues；一个 issue 同时挂一个 role；decision ticket is an issue。
• Flagged ambiguities：记录已经解决的历史歧义（backlog 的双义），防止复发。

注意它没有写：用 gh 还是 .scratch、label 字符串表、plugin.json 路径—— 那些是配置和实现，归 docs/agents/* 或代码管，不进术语表。

6.4 多领域地图长什么样（格式文件的原文结构）

# Context Map

## Contexts

- [Ordering](./src/ordering/CONTEXT.md) — receives and tracks customer orders
- [Billing](./src/billing/CONTEXT.md) — generates invoices and processes payments
- [Fulfillment](./src/fulfillment/CONTEXT.md) — manages warehouse picking and shipping

## Relationships

- **Ordering → Fulfillment**: Ordering emits OrderPlaced; Fulfillment starts picking
- **Fulfillment → Billing**: ShipmentDispatched → invoices
- **Ordering ↔ Billing**: Shared types for CustomerId and Money

7. ADR：什么决定够格记、记成什么样

ADR（architecture decision record，架构决策记录）就是给「为什么这么干」留一份书面记录。 权威原文在 ADR-FORMAT.md。 路径是 docs/adr/0001-slug.md 这样递增编号；目录同样懒创建。

7.1 三个条件（要同时满足，不是满足其一）

这三个条件是防止 docs/adr/ 变成日记本的阀门。skill 和对外文档都强调：sparingly（有节制地写）。

7.2 什么决定算合格（格式文件的清单，压缩版）

• 架构的整体形状（monorepo、事件溯源的写模型……）
• 各领域之间的集成方式（事件还是同步 HTTP）
• 有锁定成本的技术选型（换了代价很大的那种；不是每个库都记）
• 边界和范围（包括明确说「不做什么」）
• 故意偏离显然路径的决定（防止后人当 bug「修掉」）
• 代码里看不见的约束（合规、SLA）
• 拒绝过的不显然方案（不然半年后又会有人提议上 GraphQL）

7.3 模板：刻意做得极薄

# {Short title of the decision}

{1-3 sentences: context, decision, why.}

价值在于记下「做了这个决定」和「为什么」，不在于把章节填满。 可选的只有 Status frontmatter、Considered Options、Consequences——真有增益时才加。

7.4 improve-codebase-architecture 里的特殊规则

用户拒绝某个加深候选时：只有当拒绝理由对后来的探索者有「承重」作用 （load-bearing——不知道这条理由，后人会再提一次同样的方案）才提议写 ADR； 「现在没时间」这种短期理由、和不言自明的理由，都跳过。 这和三条件是同一条原则，是编排层对「有节制地提议 ADR」在具体场景里的落实。

7.5 说实话：本仓库自己的 ADR 例子

本仓库有 .agents/adr/0002 这类决策：Claude 插件现在发、Codex 原生插件推迟——难逆转、让人惊讶、有真实取舍，三条全占。 它展示了「好 ADR 长什么样」，但它的路径是 .agents/adr/，不是 skill 默认教给 使用这套 skill 的业务仓库的 docs/adr/。教别人用这套 skill 时， 目标仓库仍按 CONTEXT-FORMAT / ADR-FORMAT / domain.md 规定的布局来。

8. 读的那一侧：docs/agents/domain.md

setup 写进目标仓库的 domain.md 模板， 规定的是其它所有 skill 该怎么读领域文档——它和 domain-modeling 的「怎么写」 正好配成一对：

1. 探索前先读 CONTEXT（多领域布局先读地图）和相关的 ADR；多领域时还要查当前领域自己的 adr 目录。
2. 文件不存在 → 静默继续，不催你建；创建权只留给 domain-modeling 的懒创建。
3. 输出里给领域概念命名时，用术语表里的词，不滑到 _Avoid_ 列的同义词上。
4. 要用的概念不在术语表里：要么你在发明一个项目根本不用的词（重新想想），要么真是缺口（记下来，交给 domain-modeling）。
5. 你的输出和某篇 ADR 冲突 → 明确说出来，禁止悄悄覆盖。

9. 会留下什么、结束后接什么、与 codebase-design 的分工

9.1 会留下什么（副作用）

「副作用」就是：这个 skill 跑完，你的仓库里会多出或改动哪些文件。

9.2 结束后通常接什么

本 skill 一般嵌在别的流程里跑，结束后回到调用方的下一步，不另起一条链：

• 由 grill-with-docs 进来 → 回主流程：说不清的点去 prototype 岔路 / 清楚了去 to-spec / 小改直接 implement
• 由 triage 的面试进来 → 继续出处理结果（brief / needs-info / wontfix……）
• 由 wayfinder 进来 → 继续画地图或解决地图上的票；雾散了去 to-spec
• 由 improve-codebase-architecture 进来 → 选定的想法再进主流程的 grill-with-docs，或走 design-it-twice（同一个接口设计两版再挑，codebase-design 的模式）
• 单独启动 → 看你为什么敲词：词敲清了，可以回设计、回写需求，或就此打住

下游都会受益：to-spec 用项目里的词写需求；to-tickets / implement / tdd 的测试名和术语表对齐；任何探索类 skill 都少受「同一个东西好几个叫法」的干扰。

9.3 和 codebase-design 怎么分工

对外文档里的分界：docs 原文—— 词的问题找 domain-modeling；模块形状的问题找 codebase-design； 计划本身要被盘问，找 grilling。

10. 行为不对时，去改哪个文件

这个 skill 行为不对时，先判断问题出在哪一层，再去改对应文件的那一段 （也就是 Mission 里说的「定位该改哪段文本」）：

11. 检索练习

先别往回翻；选项长度刻意对齐，不会从字数泄题。答完再回对应的节。

12. 一手材料与下一课

必读原文（本课的压缩替代不了）：

• skills/engineering/domain-modeling/SKILL.md —— 主动/被动的定义、文件布局、会话动作清单、ADR 门槛
• CONTEXT-FORMAT.md —— 术语表的结构，以及多领域地图的写法
• ADR-FORMAT.md —— 极薄模板，以及什么决定算合格
• setup-…/domain.md —— 读侧契约的模板
• CONTEXT.md（本仓库）—— Issue tracker / Decision ticket 等活样板
• .agents/invocation.md —— Passive vs active domain work（被动读 vs 主动建模）
• ask-matt/SKILL.md —— Vocabulary underneath 一段
• docs/engineering/domain-modeling.md —— 对外叙述（用来和 SKILL 对齐检查）

建议下一课（0005）： codebase-design——另一块词汇地板：module / interface / depth / seam / adapter / leverage / locality。 两课的分工：本课定领域词，下节课定模块形状词； improve-codebase-architecture 和 tdd 两套词都要用。