ubiquitous-language

Ubiquitous Language

Extract and formalize domain terms from the current conversation into a consistent glossary, and save it to a local file.

Process

1. Scan the conversationfor domain-related nouns, verbs, and concepts
2. Identify problems：
   • The same word used for different concepts (ambiguity)
   • Different words used for the same concept (synonyms)
   • Vague or overloaded terms
3. Propose a canonical glossary, providing opinionated term choices
4. Write UBIQUITOUS_LANGUAGE.md to the working directory, using the following format
5. Output a summary in the conversation

Output format

Write the UBIQUITOUS_LANGUAGE.md file with the following structure:

# 通用语言

## 订单生命周期

| 术语          | 定义                                              | 应避免的别名            |
| ------------- | ------------------------------------------------- | ----------------------- |
| **Order**     | 客户购买一个或多个商品的请求                       | Purchase, transaction   |
| **Invoice**   | 交付后发送给客户的付款请求                         | Bill, payment request   |

## 人员

| 术语            | 定义                                  | 应避免的别名             |
| --------------- | ------------------------------------- | ------------------------ |
| **Customer**    | 下订单的个人或组织                     | Client, buyer, account   |
| **User**        | 系统中的认证身份                       | Login, account           |

## 关系

- 一个 **Invoice** 属于且仅属于一个 **Customer**
- 一个 **Order** 产生一个或多个 **Invoices**

## 示例对话

> **Dev：**"当 **Customer** 下了一个 **Order**，我们会立即创建 **Invoice** 吗？"
> **领域专家：**"不——**Invoice** 只有在 **Fulfillment** 确认后才会生成。如果商品分多个 **Shipments** 发货，一个 **Order** 可以产生多个 **Invoices**。"
> **Dev：**"那么如果 **Shipment** 在发货前被取消，就不会有对应的 **Invoice** 了？"
> **领域专家：**"正是。**Invoice** 的生命周期与 **Fulfillment** 绑定，而不是与 **Order** 绑定。"

## 已标记的歧义

- "account" 被用来既指代 **Customer** 又指代 **User**——这是两个不同的概念：**Customer** 下订单，而 **User** 是一种认证身份，可能代表也可能不代表一个 **Customer**。

Rules

• Be opinionated. When multiple words exist for the same concept, choose the best one and list the others as aliases to avoid.
• Clearly flag conflicts. If a term is used ambiguously in the conversation, point it out explicitly in the "Flagged Ambiguities" section and give a clear recommendation.
• Include only terms relevant to domain experts. Skip module or class names unless they are meaningful in the domain language.
• Keep definitions concise. At most one sentence. Define what itis, not what it does.
• Show relationships. Use bold term names and express cardinality relationships where obvious.
• Include only domain terms. Skip generic programming concepts (array, function, endpoint) unless they have domain-specific meaning.
• Group terms into multiple tableswhen natural clusters emerge (for example by subdomain, lifecycle, or role). Each group has its own heading and table. If all terms belong to the same cohesive domain, one table is enough—do not force grouping.
• Write example dialogue. A short dialogue (3-5 turns) between a developer and a domain expert showing how the terms are used naturally together. The dialogue should clarify the boundaries between related concepts and demonstrate precise use of the terms.

Example dialogue

Dev："How do I test sync service？"

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

Dev："So sync-in will still create bundle and unpack?"

Domain expert:"Exactly.sync service does not know which layer it is talking to. It calls exec and copyIn——filesystem layer and just executes these as local shell commands."

Rerun

When invoked again in the same conversation:

1. Read the existing UBIQUITOUS_LANGUAGE.md
2. Merge new terms from the subsequent discussion
3. If the understanding has evolved, update the definition
4. Relabel any new ambiguities
5. Rewrite the example dialogue to incorporate the new terminology