---
name: 领域建模
description: "讨论代码库术语、写或改 GLOSSARY.md、记或改 ADR 时用：质疑术语、编边界场景、对照代码，术语定下来当场写进 GLOSSARY.md，难以回退的决策写成 ADR"
---

# 领域建模

边设计边主动构建、打磨项目的领域模型。这是一门*主动*的功夫：质疑术语，编造试探边界的场景，术语和决策一成形就当场写下来。（只是*读* `GLOSSARY.md` 取词不算这个 skill —— 那是任何 skill 顺手就能有的一行习惯。这个 skill 用在你要改动模型的时候，而不只是使用它。）

## 文件结构

大多数仓库只有一个上下文：

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

根目录有 `GLOSSARY-MAP.md`，说明仓库有多个上下文。map 指出每个上下文在哪：

```
/
├── GLOSSARY-MAP.md
├── docs/
│   └── adr/                          ← 全系统的决策
├── src/
│   ├── ordering/
│   │   ├── GLOSSARY.md
│   │   └── docs/adr/                 ← 该上下文自己的决策
│   └── billing/
│       ├── GLOSSARY.md
│       └── docs/adr/
```

文件按需创建：有东西要写时才建。没有 `GLOSSARY.md`，就在第一个术语定下来时建；没有 `docs/adr/`，就在需要第一份 ADR 时建。

第一次建 `GLOSSARY.md`、`GLOSSARY-MAP.md` 或 `docs/adr/` 时，同时往项目根的指令文件末尾追加下面一行 —— 不留这个指针，下次会话没人会去读这些文件。Claude Code 写 `CLAUDE.md`，Codex 等客户端写 `AGENTS.md`；文件不存在就新建，已经有这一行就跳过：

```markdown
领域术语以 `GLOSSARY.md`（多上下文的仓库看 `GLOSSARY-MAP.md`）为准，难以回退的决策记在 `docs/adr/`；讨论需求、改代码前先读，用词与其一致。
```

## 会话进行中

### 拿术语表来质疑

用户用的词和 `GLOSSARY.md` 里已有的说法冲突时，当场指出来。「你的术语表把『取消』定义为 X，但你这里好像指的是 Y。到底是哪个？」

### 把含糊的说法磨准

用户用了含糊或一词多义的说法时，提议一个精确的规范术语。「你说的『账户』，是指客户（Customer）还是用户（User）？这是两回事。」

### 拿具体场景来谈

讨论领域关系时，用具体场景给它们做压力测试。编一些试探边界情况的场景，逼用户把概念之间的边界说准。

### 和代码交叉核对

用户说某个东西怎么运作时，查一下代码是否一致。发现矛盾就摆出来：「你的代码取消的是整个订单，可你刚才说可以部分取消。哪个对？」

### 当场更新 GLOSSARY.md

一个术语定下来，就当场更新 `GLOSSARY.md`。别攒着一起写：随出随记。格式见 [GLOSSARY.md 格式](reference/glossary-format.md)。

`GLOSSARY.md` 里一点实现细节都不能有。不要把它当规格说明、草稿本或存放实现决策的地方。它就是术语表，别的什么都不是。

### ADR 少提

三条全部成立时才提出写 ADR：

1. **难以回退**：日后改主意的代价不小
2. **缺了上下文会让人意外**：未来的读者会纳闷「当初为什么这么做？」
3. **真实取舍的结果**：确实有别的选项，出于具体理由选了这一个

三条缺任何一条就不写 ADR。格式见 [ADR 格式](reference/adr-format.md)。