跳转至

领域建模

边设计边主动构建、打磨项目的领域模型。这是一门主动的功夫:质疑术语,编造试探边界的场景,术语和决策一成形就当场写下来。(只是读 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;文件不存在就新建,已经有这一行就跳过:

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

会话进行中

拿术语表来质疑

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

把含糊的说法磨准

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

拿具体场景来谈

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

和代码交叉核对

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

当场更新 GLOSSARY.md

一个术语定下来,就当场更新 GLOSSARY.md。别攒着一起写:随出随记。格式见 GLOSSARY.md 格式。

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

ADR 少提

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

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

三条缺任何一条就不写 ADR。格式见 ADR 格式。