domain-modeling

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Domain Modeling

在设计过程中主动构建并打磨项目的 domain model。这是 active discipline：挑战术语、发明 edge-case scenarios，并在概念成形的当下写入 glossary 和 decisions。（仅仅读取

CONTEXT.md

来获取词汇，不是这个 skill；那只是任何 skill 都能做的一行习惯。这个 skill 用于改变 model，而不是消费 model。）

Proactively build and refine the project's domain model during the design process. This is an active discipline: challenge terminology, invent edge-case scenarios, and document them in the glossary and decisions as concepts take shape. (Simply reading

CONTEXT.md

to obtain vocabulary is not this skill; that's just a basic practice any skill can perform. This skill is for modifying the model, not consuming it.)

File structure

多数 repos 只有一个 context：

text

/
|- CONTEXT.md
|- docs/
|  `- adr/
|     |- 0001-event-sourced-orders.md
|     `- 0002-postgres-for-write-model.md
`- src/

如果 root 有

CONTEXT-MAP.md

，说明 repo 有多个 contexts。map 指向每个 context 的位置：

text

/
|- CONTEXT-MAP.md
|- docs/
|  `- adr/                          -> system-wide decisions
`- src/
   |- ordering/
   |  |- CONTEXT.md
   |  `- docs/adr/                  -> context-specific decisions
   `- billing/
      |- CONTEXT.md
      `- docs/adr/

按需懒创建文件：只有在有内容要写时才创建。如果没有

CONTEXT.md

，当第一个 term 被解决时创建它。如果没有

docs/adr/

，当第一个 ADR 需要出现时创建它。

Most repos have only one context:

text

/
|- CONTEXT.md
|- docs/
|  `- adr/
|     |- 0001-event-sourced-orders.md
|     `- 0002-postgres-for-write-model.md
`- src/

If there is a

CONTEXT-MAP.md

in the root, it means the repo has multiple contexts. The map points to the location of each context:

text

/
|- CONTEXT-MAP.md
|- docs/
|  `- adr/                          -> system-wide decisions
`- src/
   |- ordering/
   |  |- CONTEXT.md
   |  `- docs/adr/                  -> context-specific decisions
   `- billing/
      |- CONTEXT.md
      `- docs/adr/

Create files lazily as needed: only create a file when there is content to write. If there is no

CONTEXT.md

, create it when the first term is resolved. If there is no

docs/adr/

, create it when the first ADR needs to be documented.

During the session

Challenge against the glossary

当用户使用的术语与

CONTEXT.md

中既有语言冲突时，立即指出。"Your glossary defines 'cancellation' as X, but you seem to mean Y - which is it?"

Immediately point out when the terminology used by the user conflicts with the existing language in

CONTEXT.md

. For example: "Your glossary defines 'cancellation' as X, but you seem to mean Y - which is it?"

Sharpen fuzzy language

当用户使用模糊或过载术语时，提出一个精确的 canonical term。"You're saying 'account' - do you mean the Customer or the User? Those are different things."

When the user uses vague or overloaded terminology, propose a precise canonical term. For example: "You're saying 'account' - do you mean the Customer or the User? Those are different things."

Discuss concrete scenarios

讨论 domain relationships 时，用具体场景做压力测试。发明能探测 edge cases 的场景，迫使用户精确定义概念之间的 boundaries。

When discussing domain relationships, use concrete scenarios to conduct stress tests. Invent scenarios that probe edge cases to force the user to precisely define the boundaries between concepts.

Cross-reference with code

当用户描述某事如何工作时，检查代码是否同意。如果发现矛盾，要指出："Your code cancels entire Orders, but you just said partial cancellation is possible - which is right?"

When the user describes how something works, check if the code aligns with the description. If a contradiction is found, point it out: "Your code cancels entire Orders, but you just said partial cancellation is possible - which is right?"

Update CONTEXT.md inline

当一个 term 被解决时，立刻更新

CONTEXT.md

。不要批量攒到最后；随着概念出现就捕获。使用 CONTEXT-FORMAT.md 中的格式。

CONTEXT.md

必须完全不包含 implementation details。不要把

CONTEXT.md

当 spec、scratch pad 或 implementation decisions 的仓库。它只是一份 glossary。

Immediately update

CONTEXT.md

when a term is resolved. Don't batch updates until the end; capture concepts as they emerge. Follow the format in CONTEXT-FORMAT.md.

CONTEXT.md

must contain no implementation details at all. Do not use

CONTEXT.md

as a spec, scratch pad, or repository for implementation decisions. It is only a glossary.

Offer ADRs sparingly

只有以下三项都成立时，才提出创建 ADR：

Hard to reverse - 之后改变主意的成本有意义
Surprising without context - 未来读者会疑惑 "why did they do it this way?"
The result of a real trade-off - 确实存在替代方案，而你基于具体理由选择了其中一个

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

Propose creating an ADR only when all three of the following conditions are met:

Hard to reverse - The cost of changing your mind later is significant
Surprising without context - Future readers will wonder "why did they do it this way?"
The result of a real trade-off - There are actual alternatives, and you chose one based on specific reasons

Skip creating an ADR if any of the conditions are not met. Follow the format in ADR-FORMAT.md.