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 conversationto find 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, with explicit term choices
4. Write to the working directory using the following format UBIQUITOUS_LANGUAGE.md
5. Output the summary inline in the conversation

Output Format

Write using the following structure UBIQUITOUS_LANGUAGE.md file:

# 通用语言

## 订单生命周期

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

## 人员

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

## 关系

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

## 示例对话

> **Dev:** "当 **Customer** 下 **Order** 时，我们是否立即创建 **Invoice**？"
> **Domain expert:** "不——只有在确认 **Fulfillment** 后才生成 **Invoice**。如果商品分多个 **Shipments** 发货，单个 **Order** 可以产生多个 **Invoices**。"
> **Dev:** "所以如果 **Shipment** 在发货前被取消，它就没有 **Invoice**？"
> **Domain expert:** "没错。**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.
• Mark conflicts explicitly. If a term is used ambiguously in the conversation, call it out clearly in the "Flagged Ambiguities" section and provide a clear recommendation.
• Include only terms relevant to domain experts. Skip names of modules or classes unless they are meaningful in the domain language.
• Keep definitions compact. At most one sentence. Define what it is, not what it does.
• Show relationships. Use bold term names and express cardinality where obvious.
• Include only domain terms. Skip generic programming concepts (arrays, functions, endpoints) unless they have domain-specific meaning.
• When natural clusters emerge, group terms into multiple tables(for example by subdomain, lifecycle, or actor). Each group has its own heading and table. If all terms belong to one cohesive domain, one table is enough—do not force grouping.
• Write an example dialogue. A short conversation (3-5 turns) between a developer and a domain expert showing how the terms naturally interact. The dialogue should clarify the boundaries between related concepts and demonstrate precise use of the terms.

Example Dialogue

Dev: "How do you test without Docker 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 still creates bundle and unpacks it?"

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

Rerun

When invoked again in the same conversation:

1. Read the existing UBIQUITOUS_LANGUAGE.md
2. Merge any new terms from subsequent discussion
3. Update definitions if understanding has evolved
4. Re-flag any new ambiguities
5. Rewrite the example dialogue to incorporate the new terms