domain-modeling

领域建模

在设计过程中，主动构建并完善项目的领域模型。这是需要主动实践的环节：质疑术语、设想边缘场景，并在术语和决策刚明确时就将术语表和决策记录下来。（仅仅为了了解词汇而阅读 CONTEXT.md 并不属于这项技能：任何技能都可以养成这种一行就能说明的习惯。这项技能适用于你正在更改模型，而不只是使用模型的情况。）

这项技能负责领域词汇和持久化决策记录。shape-design 负责功能行为和需求。ADR 记录难以逆转的决策为何作出；它不是规格说明或实施计划。

这项技能是 planning-contract 捕获检查点中词汇和决策部分的执行环节（契约版本：1）：在厘清术语或需要记录符合条件的决策时，shape 会调用它。加载该契约，以了解分类、限定范围的权威来源和交接规则；如果尚未安装，请停止并要求安装 planning-contract，不要依据继承或臆造的规则继续操作。

文件结构

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

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

如果根目录下存在 CONTEXT-MAP.md，或项目明确声明存在多个上下文，则该代码库包含多个上下文。映射文件会指明每个上下文所在的位置：

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

按需创建文件：只有需要写入内容时才创建。如果不存在 CONTEXT.md，则在第一个术语厘清时创建，无论单上下文项目是否已配置。对于已配置的多上下文项目，绝不创建根目录下的 CONTEXT.md。如果不存在 ADR 目录（默认是 project/adr/；旧版路径为 docs/adr/），则在需要记录第一个 ADR 时创建。

确定上下文归属

编写术语表之前，如果存在 project/agents/domain.md（旧版路径为 docs/agents/domain.md），请先阅读。将其中明确声明的单上下文或多上下文设置视为配置，而不是臆造名称的理由。然后：

1. 如果存在 CONTEXT-MAP.md，请阅读并遵循其中的实际路径。
2. 检查相关的包或上下文目录，以及其中已有的 CONTEXT.md 或术语表文件。
3. 如果某个术语可能属于多个上下文，请询问它实际归属哪个上下文，不要默默自行决定。
4. 如果明确配置与现有映射或术语表中的证据冲突，请指出冲突并询问负责人应更新哪一来源；不要自动重写任何一方。
5. 对于明确配置为多上下文、但既无映射文件也无法确定归属的项目，请停止并询问实际的上下文归属。不要仅仅因为缺少映射文件就创建根目录下的 CONTEXT.md。 确定归属后，再按需记录映射或上下文术语表。
6. 对于配置为单上下文的项目，或没有配置且不存在映射文件的项目，沿用单上下文回退方式：使用根目录下的 CONTEXT.md，并在第一个术语实际厘清时按需创建。对于尚无术语表、但已配置为单上下文的代码库，也应以相同方式创建第一份真实术语表；无需创建上下文映射文件。

安装程序不会创建占位术语表或虚构的领域名称。上下文映射只有在写入真实上下文及其关系时才有意义。

会话期间

对照术语表进行质疑

用户使用的术语与 CONTEXT.md 中现有的用语冲突时，请立即指出。“你的术语表将‘取消’定义为 X，但你似乎指的是 Y。究竟是哪一个？”

让模糊表述更明确

用户使用含糊或多义的术语时，提出精确的规范术语。“你说的是‘账户’：指客户还是用户？这是两个不同的概念。”

讨论具体场景

讨论领域关系时，请用具体场景进行压力测试。设想一些检验边缘情况的场景，促使用户明确概念之间的界限。

与代码交叉核对

当用户说明某项功能的工作方式时，请检查代码是否与之相符。如果发现矛盾，请指出：“你的代码会取消整个 Order，但你刚才说可以部分取消。哪个说法是对的？”

直接更新 CONTEXT.md

当某个术语得到确认时，立即更新其所属的 CONTEXT.md。不要积攒起来一起处理：确认时就记录。请使用 context-format.md 中的格式。

CONTEXT.md 中不得包含任何实现细节。不要把 CONTEXT.md 当作规范、草稿或实现决策的存放处。它只是一本术语表，仅此而已。

谨慎提出 ADR

只有以下三项条件全部满足时，才提出创建 ADR：

1. 难以撤销：日后改变主意的成本很高
2. 缺少背景时会令人意外：未来的读者会想知道“为什么要这么做？”
3. 源于真实的权衡：确实存在多个备选方案，而你出于特定原因选择了其中一个

如果缺少任何一项，就跳过 ADR。当记录检查点询问时，应说明无需 ADR，而不是为了有而有。请使用 adr-format.md 中的格式。

记录 ADR 后，返回调用方的设计工作流。如果该决策会改变可观察行为、不变量或验收标准，请将这些内容记录在规范中，而不是扩充 ADR。

来源

改编自 mattpocock/skills，对应提交 3cca18b368ae95cdbdebbff572ccafa662551015（MIT）。