领域建模
边设计边主动构建、打磨项目的领域模型。这是一门主动的功夫:质疑术语,编造试探边界的场景,术语和决策一成形就当场写下来。(只是读 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 里已有的说法冲突时,当场指出来。「你的术语表把『取消』定义为 X,但你这里好像指的是 Y。到底是哪个?」
把含糊的说法磨准
用户用了含糊或一词多义的说法时,提议一个精确的规范术语。「你说的『账户』,是指客户(Customer)还是用户(User)?这是两回事。」
拿具体场景来谈
讨论领域关系时,用具体场景给它们做压力测试。编一些试探边界情况的场景,逼用户把概念之间的边界说准。
和代码交叉核对
用户说某个东西怎么运作时,查一下代码是否一致。发现矛盾就摆出来:「你的代码取消的是整个订单,可你刚才说可以部分取消。哪个对?」
当场更新 GLOSSARY.md
一个术语定下来,就当场更新 GLOSSARY.md。别攒着一起写:随出随记。格式见 GLOSSARY.md 格式。
GLOSSARY.md 里一点实现细节都不能有。不要把它当规格说明、草稿本或存放实现决策的地方。它就是术语表,别的什么都不是。
ADR 少提
三条全部成立时才提出写 ADR:
- 难以回退:日后改主意的代价不小
- 缺了上下文会让人意外:未来的读者会纳闷「当初为什么这么做?」
- 真实取舍的结果:确实有别的选项,出于具体理由选了这一个
三条缺任何一条就不写 ADR。格式见 ADR 格式。