领域建模
维护一个共享的、精炼的真相源,说明项目中事物的含义,使代码、文档、工单和对话使用相同的词汇描述相同的事物。
焦点:$ARGUMENTS(若为空,则为当前会话中讨论的任何内容建模)。
零隐性假设。 用户定义术语的含义。你从代码、文档或对话中推断出的定义、规范名称、同义词、关系、基数或不变量,在用户确认之前都是假设。将它们标记为 ✅ 已确认 · ❓ 未确认 · ❌ 拒绝,并将已确认的项作为事实写入领域文档。
模型存放位置
- 如果
GLOSSARY.md或docs/domain.md已存在,则使用该文件(优先使用已有文件;切勿同时创建两个文件)。 - 否则使用如下结构创建
docs/domain.md。
流程
- 读取当前的领域文档以及实现焦点概念的代码(类型、模式、数据库模型、API 契约)。代码是实际模型的证据;文档是预期模型——注意任何漂移。两者都不告诉你用户的意图;对任何漂移提出疑问,而非选择其一。
- 从对话、规格说明或工单中提取候选术语。针对每个术语,提议它是否为新术语、现有术语或现有术语的同义词,并请用户确认。两个看起来相似的词可能是不同的概念。
- 与用户解决歧义。 提出简短、具体的问题:
- “Workspace 是否等同于 Organisation,或者一个组织可以有多个 workspace?”
- “一个 Order 能否在没有 Customer 的情况下存在?关于 Order,哪些条件必须始终成立?” 与用户就每个概念达成一个规范名称(你可以推荐一个);将已拒绝的同义词列为 Avoid。
- 定义边界:标识(实体 vs 值对象)、所有权/聚合根、基数、生命周期/状态和不变量。如果项目有多个限界上下文,注明某个术语属于哪个限界上下文。如果代码有帮助,可以从代码中提出建议,但每一项都需用户确认。
- 仅将已确认的项更新到文档——最小化差异,在章节内按字母顺序排列,没有冗长叙述。如果某定义的含义发生变化,在提交/PR 中说明,并标记现在错误使用该术语的代码。如果用户希望停止但仍有未解决的项,则将其添加到
## Open Questions下标记为 ❓,切勿放入词汇表。 - 报告你添加/修改了什么以及发现的任何代码↔模型漂移(带
file:line),以及任何仍处于 ❓ 状态的项。
文档结构(保持精简)
# Domain Model
## Glossary
| Term | Definition | Avoid |
|------|------------|-------|
| Order | A customer's confirmed request to buy one or more Products. | purchase, cart |
## Entities & Aggregates
### Order (aggregate root)
- 标识:`OrderId`
- 包含:OrderLine (1..n)
- 状态:draft → placed → paid → shipped | cancelled
- 不变量:total ≥ 0;付款前无法发货
## Relationships
- Customer 1 — n Order
## Bounded Contexts (optional)
- Billing: Invoice, Payment
规则:每个定义尽量用一句话;使用词汇表中的其他术语来定义术语;不包含实现细节,除非它们就是领域本身(例如客户看到的 ID 格式)。