domain-modeling

领域建模

在设计过程中，主动构建并完善项目的领域模型。这是一项主动实践——质疑术语、构思边界场景，并在概念一经明确时立即记录词汇表和决策。（仅仅为了了解词汇而阅读 CONTEXT.md 并不属于这项技能——这是任何技能都能做到的一行习惯。这项技能适用于你正在更改模型，而不仅仅是使用它的时候。）

文件结构

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

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

如果根目录下存在 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.md，则在第一个术语确定时创建。如果不存在 docs/adr/，则在需要记录第一个 ADR 时创建。

会话期间

对照词汇表进行质疑

当用户使用的术语与 CONTEXT.md 中现有的术语不一致时，立即指出。“你的词汇表将‘取消’定义为 X，但你似乎指的是 Y——到底是哪一种？”

明确模糊的语言

当用户使用含糊或有多种含义的术语时，提出一个精确的规范术语。“你说的是‘账户’——指的是 Customer 还是 User？两者并不是一回事。”

讨论具体场景

讨论领域关系时，用具体场景对其进行压力测试。构思探查边界情况、促使用户明确概念间界限的场景。

与代码交叉核对

当用户陈述某项功能的工作方式时，检查代码是否一致。如果发现矛盾，就指出来：“你的代码会取消整个 Order，但你刚才说可以部分取消——到底哪一种才对？”

直接更新 CONTEXT.md

确定某个术语后，立即在 CONTEXT.md 中更新。不要攒着以后再写——应在术语确定时记录。使用 CONTEXT-FORMAT.md 中的格式。

CONTEXT.md 不应包含任何实现细节。不要把 CONTEXT.md 当作规范、草稿或实现决策存储库。它只是词汇表，仅此而已。

酌情提出 ADR

只有同时满足以下三个条件时，才提出创建 ADR：

1. 难以撤销——日后改变主意的代价很大
2. 没有上下文就会令人意外——未来的读者会疑惑“为什么要这样做？”
3. 源于真实的权衡——确实存在其他选择，而你基于具体原因选定了其中一种

如果缺少任何一项，就跳过 ADR。使用 ADR-FORMAT.md 中的格式。

编写 ADR 文档时：

• 评估该功能是否有任何部分被认为难以实现（即小型 AI Agent/子 Agent 在没有具体指导的情况下可能难以实现或无法实现），或者会话期间是否提出了特定的类、数据结构或设计。
• 如果有，则在 ADR 中加入相关代码片段（例如接口、数据结构、关键类或算法框架），以指导未来的实现。
• 明确列出当前工作区内相关文件或项目的路径或引用，以便负责实现的子 Agent 提高编码准确性。
• 对于简单任务/设计，沿用当前的最简格式即可。