Back to Details

domain-modeling

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Domain Modeling

领域建模

Actively build and sharpen the project's domain model as you design. This is the active discipline: challenging terms, inventing edge-case scenarios, and writing the glossary and decisions down the moment they crystallise. (Merely reading 
GLOSSARY.md
for vocabulary is not this skill: that's a one-line habit any skill can do. This skill is for when you're changing the model, not just consuming it.)
在设计过程中主动构建并打磨项目的领域模型。这是一项主动实践：质疑术语、构造边界场景，并在术语和决策清晰成型时立即将其记录下来。（仅仅为了查阅词汇而阅读 
GLOSSARY.md
不属于这项 skill：那只是任何 skill 都能随手完成的一行操作。这项 skill 用于改变模型，而非只是使用现有模型。）

File structure

文件结构

Most repos have a single context:
/
├── GLOSSARY.md
├── docs/
│   └── adr/
│       ├── 0001-event-sourced-orders.md
│       └── 0002-postgres-for-write-model.md
└── src/
If a 
GLOSSARY-MAP.md
exists at the root, the repo has multiple contexts. The map points to where each one lives:
/
├── GLOSSARY-MAP.md
├── docs/
│   └── adr/                          ← system-wide decisions
├── src/
│   ├── ordering/
│   │   ├── GLOSSARY.md
│   │   └── docs/adr/                 ← context-specific decisions
│   └── billing/
│       ├── GLOSSARY.md
│       └── docs/adr/
Create files lazily: only when you have something to write. If no 
GLOSSARY.md
exists, create one when the first term is resolved. If no 
docs/adr/
exists, create it when the first ADR is needed.
大多数仓库只有一个上下文：
/
├── GLOSSARY.md
├── docs/
│   └── adr/
│       ├── 0001-event-sourced-orders.md
│       └── 0002-postgres-for-write-model.md
└── src/
如果根目录中存在 
GLOSSARY-MAP.md
，则仓库包含多个上下文。该映射文件会指出每个上下文所在的位置：
/
├── GLOSSARY-MAP.md
├── docs/
│   └── adr/                          ← 系统级决策
├── src/
│   ├── ordering/
│   │   ├── GLOSSARY.md
│   │   └── docs/adr/                 ← 上下文专属决策
│   └── billing/
│       ├── GLOSSARY.md
│       └── docs/adr/
按需创建文件：只有确实有内容可写时才创建。如果不存在 
GLOSSARY.md
，则在第一个术语确定后创建。如果不存在 
docs/adr/
，则在首次需要 ADR 时创建。

During the session

会话期间

Challenge against the glossary

对照 GLOSSARY.md 核查术语

When the user uses a term that conflicts with the existing language in 
GLOSSARY.md
, call it out immediately. "Your glossary defines 'cancellation' as X, but you seem to mean Y. Which is it?"
当用户使用的术语与 
GLOSSARY.md
中已有的表述冲突时，立即指出：“您的术语表将 ‘cancellation’ 定义为 X，但您似乎指的是 Y。究竟是哪一种？”

Sharpen fuzzy language

精确化模糊表述

When the user uses vague or overloaded terms, propose a precise canonical term. "You're saying 'account': do you mean the Customer or the User? Those are different things."
当用户使用含糊或含义过载的术语时，提出精确的规范术语：“您说的是 ‘account’：是指 Customer 还是 User？二者是不同的概念。”

Discuss concrete scenarios

讨论具体场景

When domain relationships are being discussed, stress-test them with specific scenarios. Invent scenarios that probe edge cases and force the user to be precise about the boundaries between concepts.
讨论领域关系时，使用具体场景进行压力测试。构造能够探查边界情况的场景，促使用户精确定义概念之间的边界。

Cross-reference with code

与代码交叉核对

When the user states how something works, check whether the code agrees. If you find a contradiction, surface it: "Your code cancels entire Orders, but you just said partial cancellation is possible. Which is right?"
当用户说明某项功能的运作方式时，检查代码是否与之一致。如果发现矛盾，直接指出：“您的代码会取消整个 Orders，但您刚才说可以 partial cancellation。哪一种才正确？”

Update GLOSSARY.md inline

就地更新 GLOSSARY.md

When a term is resolved, update 
GLOSSARY.md
right there. Don't batch these up: capture them as they happen. Use the format in GLOSSARY-FORMAT.md.
GLOSSARY.md
should be totally devoid of implementation details. Do not treat 
GLOSSARY.md
as a spec, a scratch pad, or a repository for implementation decisions. It is a glossary and nothing else.
一旦术语确定，立即就地更新 
GLOSSARY.md
。不要批量积压：应在术语确定当下就记录下来。使用 GLOSSARY-FORMAT.md 中规定的格式。
GLOSSARY.md
不应包含任何实现细节。不要将 
GLOSSARY.md
当作规格说明、草稿本或存放实现决策的仓库。它只是术语表，别无其他用途。

Offer ADRs sparingly

谨慎建议创建 ADR

Only offer to create an ADR when all three are true:
  1. Hard to reverse: the cost of changing your mind later is meaningful
  2. Surprising without context: a future reader will wonder "why did they do it this way?"
  3. The result of a real trade-off: there were genuine alternatives and you picked one for specific reasons
If any of the three is missing, skip the ADR. Use the format in ADR-FORMAT.md.
只有以下三项条件全部成立时，才建议创建 ADR：
  1. 难以逆转：以后改变决定的成本显著
  2. 脱离上下文后令人意外：未来读者会问：“为什么要这样做？”
  3. 源于真实权衡：确实存在其他可行方案，而你出于具体原因选择了其中一个
如果缺少其中任何一项，就不要创建 ADR。使用 ADR-FORMAT.md 中规定的格式。