ubiquitous-language

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Ubiquitous Language

从当前 conversation 中提取并形式化 domain terminology，整理成一致 glossary，并保存到本地文件。

从当前 conversation 中提取并规范化领域术语（domain terminology），整理成统一的术语表（glossary），并保存至本地文件。

Process

Scan the conversation，寻找 domain-relevant nouns、verbs 和 concepts
Identify problems：
- 同一个词被用于不同 concepts（ambiguity）
- 不同词被用于同一个 concept（synonyms）
- 模糊或 overloaded terms
Propose a canonical glossary，对 term 选择保持 opinionated
Write to
UBIQUITOUS_LANGUAGE.md
，在 working directory 中使用下面格式
Output a summary，在 conversation 中内联总结

扫描对话（Scan the conversation）：寻找与领域相关的名词、动词和概念（concepts）
识别问题：
- 同一词汇被用于指代不同概念（ambiguity，歧义）
- 不同词汇被用于指代同一概念（synonyms，同义词）
- 模糊或语义过载的术语（overloaded terms）
提出标准术语表（canonical glossary）：在术语选择上保持明确立场（opinionated）
写入
UBIQUITOUS_LANGUAGE.md
：在工作目录（working directory）中采用以下格式
输出总结：在对话中以内联形式呈现总结

Output Format

写一个

UBIQUITOUS_LANGUAGE.md

文件，结构如下：

undefined

生成一个

UBIQUITOUS_LANGUAGE.md

文件，结构如下：

undefined

Ubiquitous Language

Order lifecycle

Term	Definition	Aliases to avoid
Order	A customer's request to purchase one or more items	Purchase, transaction
Invoice	A request for payment sent to a customer after delivery	Bill, payment request

Term	Definition	Aliases to avoid
Order	A customer's request to purchase one or more items	Purchase, transaction
Invoice	A request for payment sent to a customer after delivery	Bill, payment request

People

Term	Definition	Aliases to avoid
Customer	A person or organization that places orders	Client, buyer, account
User	An authentication identity in the system	Login, account

Term	Definition	Aliases to avoid
Customer	A person or organization that places orders	Client, buyer, account
User	An authentication identity in the system	Login, account

Relationships

An Invoice belongs to exactly one Customer
An Order produces one or more Invoices

An Invoice belongs to exactly one Customer
An Order produces one or more Invoices

Example dialogue

Dev: "When a Customer places an Order, do we create the Invoice immediately?" Domain expert: "No — an Invoice is only generated once a Fulfillment is confirmed. A single Order can produce multiple Invoices if items ship in separate Shipments." Dev: "So if a Shipment is cancelled before dispatch, no Invoice exists for it?" Domain expert: "Exactly. The Invoice lifecycle is tied to the Fulfillment, not the Order."

Flagged ambiguities

"account" was used to mean both Customer and User — these are distinct concepts: a Customer places orders, while a User is an authentication identity that may or may not represent a Customer.

undefined

"account" was used to mean both Customer and User — these are distinct concepts: a Customer places orders, while a User is an authentication identity that may or may not represent a Customer.

undefined

Rules

Be opinionated. 同一概念有多个词时，选择最好的一个，并把其他列为 aliases to avoid。
Flag conflicts explicitly. 如果 term 在 conversation 中被模糊使用，在 "Flagged ambiguities" section 中指出，并给出明确 recommendation。
Only include terms relevant for domain experts. 除非 module 或 class 名在 domain language 中有意义，否则跳过。
Keep definitions tight. 最多一句。定义它是什么，不定义它做什么。
Show relationships. 使用粗体 term names，并在明显时表达 cardinality。
Only include domain terms. 跳过 generic programming concepts（array、function、endpoint），除非它们有 domain-specific meaning。
Group terms into multiple tables，当自然 clusters 出现时使用（例如按 subdomain、lifecycle 或 actor）。每组有自己的 heading 和 table。如果所有 terms 属于一个 cohesive domain，一个 table 就够，不要强行分组。
Write an example dialogue. 写一段 dev 与 domain expert 之间的短对话（3-5 exchanges），展示 terms 如何自然互动。对话应澄清相关 concepts 的边界，并展示精确使用 terms。

立场明确：当同一概念对应多个词汇时，选择最优术语，将其他词汇列为需避免的别名（aliases to avoid）。
明确标记冲突：如果术语在对话中被模糊使用，在“Flagged ambiguities”章节中指出，并给出明确建议（recommendation）。
仅包含领域专家相关术语：除非模块（module）或类（class）名称在领域语言（domain language）中具有特定含义，否则不予收录。
定义简洁精准：每条定义不超过一句话，仅说明术语是什么，而非其功能。
展示关系：术语名称使用粗体，若关系的基数（cardinality）明确则予以说明。
仅收录领域术语：跳过通用编程概念（如array、function、endpoint），除非它们具有领域特定含义（domain-specific meaning）。
按自然分组整理术语：当出现自然聚类（clusters）时，将术语分为多个表格（例如按子域（subdomain）、生命周期（lifecycle）或角色（actor）分组）。每组有独立的标题和表格。若所有术语属于一个紧密关联的领域，使用单个表格即可，无需强行分组。
编写示例对话：撰写一段开发者（dev）与领域专家（domain expert）之间的简短对话（3-5轮交互），展示术语的自然使用场景。对话应明确相关概念的边界，并体现术语的精准使用。

Example dialogue

Dev: "How do I test the sync service without Docker?"

Domain expert: "Provide the filesystem layer instead of the Docker layer. It implements the same Sandbox service interface but uses a local directory as the sandbox."

Dev: "So sync-in still creates a bundle and unpacks it?"

Domain expert: "Exactly. The sync service doesn't know which layer it's talking to. It calls
exec
and
copyIn
— the filesystem layer just runs those as local shell commands."

</example>

开发者（Dev）：“我如何在不使用 Docker 的情况下测试 sync service？” 领域专家（Domain expert）：“使用 filesystem layer 替代 Docker layer。它实现了与 Sandbox service 相同的接口，但使用本地目录作为 sandbox。” 开发者（Dev）：“那 sync-in 仍然会创建 bundle 并进行解压吗？” 领域专家（Domain expert）：“没错。sync service 并不知晓它对接的是哪一层。它会调用
exec
和
copyIn
——filesystem layer 只是将这些操作作为本地 shell 命令执行。”

</example>

Re-running

在同一 conversation 中再次调用时：

读取已有
```
UBIQUITOUS_LANGUAGE.md
```
合并后续讨论中的新 terms
如果理解演进，更新 definitions
重新标记任何新 ambiguities
重写 example dialogue 以纳入新 terms

在同一对话中再次调用时：

读取已有的
```
UBIQUITOUS_LANGUAGE.md
```
文件
合并后续讨论中出现的新术语（terms）
若对术语的理解有所演进，更新定义（definitions）
重新标记所有新出现的歧义（ambiguities）
重写示例对话（example dialogue）以纳入新术语