evanflow-glossary

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

EvanFlow: Ubiquitous Language

EvanFlow: 通用语言

Vocabulary

词汇

See

evanflow

meta-skill.

参见

evanflow

元技能。

When to Use

使用场景

Authoring
```
CONTEXT.md
```
for the first time (Phase B of EvanFlow rollout)
A new domain term emerged in conversation and should be added
Auditing existing terminology for ambiguity (same word, multiple meanings) or synonyms (different words, same meaning)
Before any architectural conversation that depends on shared language

首次编写
```
CONTEXT.md
```
时（EvanFlow部署的B阶段）
对话中出现新的领域术语，需要添加至文档
审核现有术语是否存在歧义（同一单词有多种含义）或同义词（不同单词表达同一概念）
在任何依赖共享语言的架构讨论之前

The Flow

流程

1. Read Current State

1. 读取当前状态

If
```
CONTEXT.md
```
exists: read it. Identify clusters and gaps.
Read recent code in the relevant area: router file, service file, schema, page. Names in code are the de facto terminology.
Read recent ADRs in
```
docs/adr/
```
for terms decided there.

若
```
CONTEXT.md
```
已存在：读取该文件，识别术语集群与空白点。
读取相关领域的近期代码：路由文件、服务文件、 schema、页面。代码中的命名是实际生效的术语。
读取
```
docs/adr/
```
目录下的近期ADR，查看其中已确定的术语。

2. Extract Terms

2. 提取术语

Walk the conversation + relevant code. Pull out:

Nouns — entities and value objects in your domain
Verbs — domain operations (e.g., negotiate, queue, withdraw, settle, escalate)
Status enums — explicit lifecycle states (e.g.,
```
OrderStatus
```
,
```
MessageStatus
```
)
Relationships — cardinalities between entities (one-to-many, many-to-many)

梳理对话内容及相关代码，提取以下内容：

名词 —— 领域中的实体和值对象
动词 —— 领域操作（例如：negotiate、queue、withdraw、settle、escalate）
状态枚举 —— 明确的生命周期状态（例如：
```
OrderStatus
```
、
```
MessageStatus
```
）
关系 —— 实体间的基数（一对多、多对多）

3. Flag Conflicts

3. 标记冲突

Two questions to ask the user for each conflict:

Ambiguity: "The word
```
X
```
is used for both A and B. Which canonical meaning, and what should the other one be renamed to?"
Synonyms: "The codebase uses both
```
User
```
and
```
Account
```
for the same concept. Which is canonical? The other becomes a deprecated alias."

Propose recommended answers. Don't just dump the conflicts on the user.

针对每个冲突，向用户询问两个问题：

歧义：“词汇
```
X
```
同时被用于指代A和B。哪个是规范含义，另一个应重命名为什么？”
同义词：“代码库中同时使用
```
User
```
和
```
Account
```
指代同一概念。哪个是规范术语？另一个将作为已弃用的别名。”

需给出建议性答案，不要仅向用户罗列冲突。

4. Write CONTEXT.md

4. 编写CONTEXT.md

Default location:

/CONTEXT.md

at repo root. (Mattpocock convention.)

Format:

markdown

undefined

默认位置：仓库根目录下的

/CONTEXT.md

（Mattpocock 约定）。

格式：

markdown

undefined

<Project> Domain Language

<项目名称> 领域语言

<Cluster Name> (e.g., "Identity & Accounts")

<集群名称>（例如："身份与账户"）

Term	Definition (one sentence)	Aliases to avoid
User	Canonical noun for an authenticated account.	Account (legacy), Customer (billing-layer only)
Category	A primary classification used for matching/filtering.	Type, Tag, Vertical

术语	定义（一句话）	应避免使用的别名
User	已认证账户的规范名词。	Account（旧称）、Customer（仅用于计费层）
Category	用于匹配/过滤的一级分类。	Type、Tag、Vertical

<Next Cluster>

<下一个集群>

...

Relationships

关系

EntityA → EntityB: many-to-many via a join table.
EntityA → EntityC: one-to-many; EntityCs are managed by an automated process.

undefined

EntityA → EntityB：通过关联表实现多对多。
EntityA → EntityC：一对多；EntityC由自动化流程管理。

undefined

5. Re-invoke Behavior

5. 重新调用时的行为

CONTEXT.md

already exists:

Read it
Add new terms in their existing cluster (or create a new cluster)
Update evolved definitions
Refresh the example dialogue if present
Don't duplicate; merge

若

CONTEXT.md

已存在：

读取该文件
将新术语添加至现有集群（或创建新集群）
更新已演变的定义
刷新示例对话（若存在）
避免重复；合并内容

Hard Rules

硬性规则

One sentence per definition. If you need a paragraph, the term is too vague — split it.
Domain terms only. Skip generic programming concepts (function, class, etc.).
Be prescriptive. Pick canonical synonyms; don't list every variant as equally valid.
Cardinality in bold. "User has many Orders."
Never auto-commit. Append CONTEXT.md changes to a stage; ask before commit.

每个定义一句话。若需要段落说明，说明该术语过于模糊——拆分它。
仅包含领域术语。跳过通用编程概念（如function、class等）。
具有规定性。选择规范同义词；不要将所有变体列为同等有效。
基数用粗体标注。例如：“User拥有多个Orders。”
绝不自动提交。将CONTEXT.md的更改添加至暂存区；提交前需征得用户同意。

Hand-offs

交接

New ADR needed (decision behind a term) → write under
```
docs/adr/
```
Terms reveal architectural friction →
```
evanflow-improve-architecture
```

若需要为术语编写决策依据的新ADR → 写入
```
docs/adr/
```
目录
术语暴露架构摩擦 → 调用
```
evanflow-improve-architecture
```
功能