Domain Modeling 是一个用于主动构建并打磨项目领域模型的技能。它面向的不是“读一下词汇表”这种任何技能都能养成的习惯,而是领域模型正在发生变化、需要参与设计和澄清的时刻。
用途
在设计过程中持续挑战术语、发明边界场景、并在决策成形的瞬间把决策写下来。
文档放置
技能约定如下结构:
docx/ ├── glossary.md ← canonical terms, one project-wide file └── decisions/ ├── 0001-event-sourced-orders.md └── 0002-postgres-for-write-model.md
强调惰性创建:在第一个术语被确定之前不创建 docx/glossary.md,在第一份真正够格的 ADR 出现之前不创建 docx/decisions/。空的脚手架只是噪音。如果仓库已经把决策放在别处(如 docs/adr/ 或某个 ADR 工具),就沿用该位置;在第一次写入时确认一次,之后不再反复询问。
四项动作
- 对照词汇表挑战:当术语与 docx/glossary.md 冲突时立即指出,例如“词汇表把 cancellation 定义为 X,但这里读起来是 Y。到底是哪一个?”
- 收敛模糊语言:术语含糊或过载时,提出精确的规范术语,例如“你说的 account 是 Customer 还是 User?它们是不同的东西,设计会因此分叉。”
- 与代码交叉核对:有人陈述某事物如何运作时,检查代码是否一致,暴露矛盾而非默默纠正,例如“计划说可以部分取消,但 cancelOrder 只处理整单。哪个对?”
- 就地写入:术语一旦确定就追加记录,不要批量处理,因为推理只在讨论现场是新鲜的。
词汇表条目示例:
Cancellation
A customer-initiated reversal of an unfulfilled Order. Distinct from a Refund, which reverses payment on an Order that already shipped.
docx/glossary.md 只是词汇表,不放实现细节、规范或草稿笔记;描述某事物如何构建的条目应放在 design.md。
限界上下文
一个术语在某个限界上下文(模块、服务或团队负责的区域)内只有一个含义,同一个词在两个上下文中可以正确地表示不同事物。示例:Catalog 的 Product(上架销售的商品,含名称、价格、描述)与 Warehouse 的 Product(货架上的库存项,含 SKU、货位、数量)都正确;把它们合并成一个定义会混合两个模型,基于其构建的代码也会开始混用。
上下文应从代码中寻找(顶层模块、服务、独立 schema),而不是从常会模糊它们的文档中寻找。遇到过载的词,先问“哪个上下文”,再问“哪个含义”。如果各用法都停留在自己的上下文内,那就是两个术语,而不是需要解决的冲突。
存在两个上下文后,词汇表按上下文分组,每个上下文一个 ## <Context> 小节;在所有地方含义相同的术语放在 ## Shared 下。只有一个上下文的项目保持平铺列表。
术语跨越上下文时,在第二个条目下增加一行说明两者关系及转换位置,例如:“A Catalog Product maps to one or more Warehouse Products by SKU (catalog/stock.py).”
不要为了显得周全而拆分;在各处用法相同的词就是一个条目。
分组示例:
Catalog
Product
What a shopper can buy: a name, a price, and a description.
Warehouse
Product
A stock item on a shelf: a SKU, a bin, and a quantity. A Catalog Product maps to one or more Warehouse Products by SKU.
ADR 的克制使用
仅在三个条件同时成立时记录决策:难以逆转(以后改变主意有真实成本);缺少上下文会令人意外(未来的读者会问“为什么他们要这样做”);存在真实取舍(确实有备选方案,且基于陈述的理由选择了其中一个)。任一条缺失就跳过;被显而易见的选择填充的决策日志将不再被阅读。
ADR 写入 docx/decisions/NNNN-kebab-slug.md,编号从现有最大文件继续。编号是永久地址——只能取代,绝不重新编号。
ADR 模板:
NNNN. <Decision title>
- Status: accepted
- Date: YYYY-MM-DD
Context
The situation that forced a decision. What constraint made this hard.
Decision
What was chosen, in the active voice.
Alternatives considered
Each real option and the specific reason it lost. An ADR with no alternatives is a note, not a decision record — that was the third test, and it failed.
Consequences
What this makes easy, what it makes hard, and what would have to be true to revisit it.
ADR 与 post-mortem 不同:后者记录某事物为何出故障,ADR 记录为何选择某种做法。
适用场景
适用于领域模型正在演进、术语需要统一、口头设计与代码实现可能不一致、以及需要为关键架构选择留下理由的项目设计与开发过程。
限制
资料未说明该技能的安装方式、依赖环境、平台支持、收费模式或价格;也未说明其与具体工具链的集成方式,这些信息暂未提供。