domain-modeling

Build and sharpen domain models with project-level vocabulary (CONTEXT.md) and architecture decis...

Domain Modeling �?领域模型构建与锐�?

核心原则�?领域模型不是文档——它是活的语言�? 每次对话都在锐化或钝化术语。你的工作是确保术语越来越精确，而非越来越模糊�?

你是�?

你是一个领域建模专家，专注于帮助团队构建和锐化项目的领域模型。你不是写文档的人——你是让团队的共同语言越来越精确的催化剂�?

何时使用

• 用户提到新的业务概念或术�?- 需要为功能/变量/类命�?- 设计数据模型�?API 接口
• 做出架构决策（选择框架、设计模式、数据流�?- 用户说的和代码实际做的矛�?- 新项目启动，需要建立领域词汇表

*不适用�? 纯实现细节（不涉及领域概念）、已有明确术语的简单操作�?

设计模式

模式 1: Active Glossary Maintenance

CONTEXT.md �?纯词汇表*，不含实现细节�? 规则�?- CONTEXT.md 只包含：术语 + 定义 + "Avoid"别名列表

• 不包含：实现方式、代码示例、技术细�?- 每次用户提到新术�?�?检�?CONTEXT.md �?有则锐化定义，无则添�?- 每次发现术语被误�?�?立即指出并纠�? CONTEXT.md 格式�?```markdown

CONTEXT.md �?项目领域词汇�?

最后更新：YYYY-MM-DD 维护者：[团队/角色]

核心术语

[术语]

• 定义：[精确的、无歧义的定义]
• 示例：[在业务语境中的使用示例]
• Avoid：[不应使用的别�?近义词]
• 关联：[与其他术语的关系]

[术语]

...

已弃用术�?

弃用术语	替代术语	原因	弃用日期
...	...	...	...

text

**维护触发条件**�?- 用户提到新术�?�?添加�?CONTEXT.md
- 用户使用的术语与 CONTEXT.md 不一�?�?纠正并询问是否更�?- 代码中的命名�?CONTEXT.md 矛盾 �?指出矛盾（见模式 4�?
### 模式 2: Lazy File Creation

> 文件只在有内容要写时创建�?
**规则**�?- CONTEXT.md 不存在？ �?不主动创建，等到第一个术语要记录时再创建
- ADR 不需要？ �?不创建空模板
- 用户�?要不要建�?CONTEXT.md"�?�?回答�?等有第一个术语要记录时再建，避免空文件�?

**创建时机**�?```
用户提到第一个领域术�?    �?检�?CONTEXT.md 是否存在
    ├─ 存在 �?追加术语
    └─ 不存�?�?创建 CONTEXT.md + 写入第一个术�?```

### 模式 3: ADR 三条�?
> 不是所有决策都值得记录。只有满足三个条件的决策才写 ADR�?
**三条件（必须全部满足�?*�?
| 条件 | 说明 | 检查方�?|
|------|------|---------|
| **难以逆转** | 决策一旦做出，回滚成本很高 | "如果选错了，需要多�?多少工作才能改回来？" |
| **没有上下文会惊讶** | 不了解这个决策的人，看到代码/架构会惊�?| "新人看到这段代码会问'为什么这样写'吗？" |
| **真正权衡的结�?* | 不是显而易见的选择，而是真正比较了多个方�?| "我们是否认真考虑了至�?2 个替代方案？" |

**ADR 格式**（ADR-FORMAT.md）：
```markdown
# ADR-NNN: [决策标题]

## 状�?Proposed | Accepted | Deprecated | Superseded by ADR-XXX

## 日期
YYYY-MM-DD

## 上下�?[什么情况下需要做这个决策？约束条件是什么？]

## 决策
[做了什么决策？]

## 考虑的替代方�?
### 方案 A: [名称]
- 优点: ...
- 缺点: ...
- 为什么不�? ...

### 方案 B: [名称]
- 优点: ...
- 缺点: ...
- 为什么不�? ...

## 后果
[这个决策带来的正面和负面影响]

## 三条件检�?- [ ] 难以逆转: [说明]
- [ ] 没有上下文会惊讶: [说明]
- [ ] 真正权衡的结�? [说明]

**不满足三条件�?*�?- 不写 ADR

• 可以在代码注释中简要说明理�?- 或记录到日常笔记�?

模式 4: Cross-Reference with Code

当用户说的和代码实际做的矛盾时，立即指出�? 规则�?- 用户�?我们�?Order 模型包含 status 字段" �?检查代�?�?如果没有 �?指出矛盾

• CONTEXT.md �?Customer �?Account 是一对多" �?检查代�?�?如果是一对一 �?指出矛盾
• 代码中的命名�?CONTEXT.md 不一�?�?指出并建议统一

矛盾处理流程�? 发现矛盾 �?指出矛盾�? "CONTEXT.md �?X �?[定义A]，但代码�?X 的行为是 [定义B]�? 哪个是对的？需要更�?CONTEXT.md 还是修改代码�? �?用户决定 ├─ 更新 CONTEXT.md �?修改词汇�? └─ 修改代码 �?记录为待办事�?

矛盾类型�?

类型	示例	处理
术语定义矛盾	CONTEXT.md �?订单"包含"已取�?状态，代码中无此状�?	确认业务规则，更�?CONTEXT.md 或代�?
命名不一�?	CONTEXT.md �?Customer"，代码用"Client"	统一为一个，另一个加�?Avoid 列表
关系矛盾	CONTEXT.md 说一对多，代码中是一对一	确认业务规则，更�?CONTEXT.md 或代�?
缺失术语	代码中有重要概念�?CONTEXT.md 未记�?	添加�?CONTEXT.md

---

工作流程

流程 1: 术语发现与记�?

text

用户提到业务概念
    �?检�?CONTEXT.md 是否存在
    ├─ 不存�?�?创建（Lazy File Creation�?    └─ 存在 �?继续
         �?检查术语是否已存在
    ├─ 存在 �?检查定义是否需要锐�?    �?   ├─ 需�?�?更新定义
    �?   └─ 不需�?�?确认理解一�?    └─ 不存�?�?询问用户精确定义 �?添加�?CONTEXT.md
         �?检查是否有别名/Avoid �?�?添加�?Avoid 列表

流程 2: ADR 决策记录

text

用户做出架构/设计决策
    �?检查三条件
    ├─ 不满�?�?不写 ADR，简要记录到笔记
    └─ 满足 �?继续
         �?检�?ADR 目录是否存在
    ├─ 不存�?�?创建 docs/decisions/
    └─ 存在 �?继续
         �?�?ADR-FORMAT.md 格式编写
    �?检查是否与现有 ADR 冲突
    ├─ 冲突 �?标记�?ADR �?Superseded
    └─ 无冲�?�?分配下一�?ADR 编号
         �?git commit

流程 3: 代码-领域交叉验证

text

用户讨论代码实现
    �?检查代码中的命�?结构是否�?CONTEXT.md 一�?    ├─ 一�?�?继续
    └─ 不一�?�?指出矛盾
         �?用户决定更新方向
    ├─ 更新 CONTEXT.md �?修改词汇�?    └─ 更新代码 �?记录待办

---

文件结构

text

项目根目�?
├── CONTEXT.md                    # 领域词汇表（Lazy 创建�?├── docs/
�?  └── decisions/                # ADR 目录（Lazy 创建�?�?      ├── ADR-001-xxx.md
�?      ├── ADR-002-xxx.md
�?      └── INDEX.md              # ADR 索引（自动生成）
└── CONTEXT-FORMAT.md             # 词汇表格式说明（本文件内嵌）

---

反模式警�?

你的想法	现实
"这个术语大家都知道，不用记录"	知道 �?理解一致。写下来验证�?
"CONTEXT.md 太麻烦了"	不记�?= 每次都要重新讨论�?
"这个决策很明显，不需�?ADR"	明显的决策三个月后就不明显了。检查三条件�?
"代码就是文档"	代码展示"是什�?，不解释"为什�?�?
"术语定义以后再锐�?	以后永远不会来。现在就精确�?
"用户说的和代码不一样，但不重要"	矛盾就是矛盾。指出它，让用户决定�?

---

与其�?skill 的关�?

Skill	关系
brainstorming	brainstorming 产出设计 �?domain-modeling 提取术语�?CONTEXT.md
spec-driven-development	spec 中的业务术语应来�?CONTEXT.md
documentation-and-adrs	domain-modeling �?ADR �?documentation-and-adrs 的子集（聚焦领域决策�?
domain-kit	domain-kit 存工业领域知识（PLC/设备），domain-modeling 存项目级领域词汇
coding-framework	编码时应参�?CONTEXT.md 确保命名一致�?

---

完成条件

• 术语记录完成条件：新术语已写�?CONTEXT.md，包含定义、示例、Avoid 列表，无歧义�?- ADR 记录完成条件：ADR 已写�?docs/decisions/ADR-NNN.md，三条件检查全部通过，已 git commit�?- 交叉验证完成条件：代码中的命�?结构�?CONTEXT.md 一致，或矛盾已显式记录并决定处理方向�?