ubiquitous-language

ubiquitous-language skill 概览

ubiquitous-language skill 可以把一段杂乱的领域讨论，整理成结构化、符合 DDD 风格的术语表，产出规范术语、定义，以及应避免使用的别名。它的核心任务并不是泛泛地“写一份 glossary”，而是在产品、工程、技术写作对同一概念使用了重叠或不一致说法时，帮助团队把语言统一起来。

ubiquitous-language 最适合用来做什么

当你们的对话里已经出现了足够多的领域术语，现在需要把它们沉淀成可复用的规范表达时，就适合使用 ubiquitous-language skill。它尤其适合：

• domain-driven design 工作
• API 和产品术语清理
• 内部平台命名对齐
• onboarding 文档
• 内容建模
• 面向 Technical Writing 的 ubiquitous-language 场景：文档必须始终使用同一个 canonical term

它真正解决的任务是什么

大多数用户实际想解决的，通常是以下几类问题之一：

• “同一个东西我们老是在用好几个名字。”
• “一个术语在不同上下文里指的不是同一回事。”
• “文档、产品 UI、工程讨论里的用词越来越偏离。”
• “我们需要基于现有讨论快速整理出第一版领域术语表，而不是从零开始。”

这个 skill 会扫描当前对话，识别含糊、重复或一词多义的术语，给出带倾向性的 canonical term 建议，并把结果写入 UBIQUITOUS_LANGUAGE.md。

它和普通 prompt 的区别在哪里

普通 prompt 当然也可以要求模型生成 glossary。但 ubiquitous-language 的工作流更具体，因此在安装和采用判断上更有价值：

• 它会主动查找歧义、同义词和一词多义的问题
• 它推动的是 canonical naming，而不只是机械提取术语
• 它输出的是一个可复用的 markdown 工件
• 它遵循稳定的表格结构，便于审阅和编辑

所以，相比泛泛的“总结一下我们的领域术语”，它更适合做术语收敛和标准化。

输出内容长什么样

这个 skill 会生成 UBIQUITOUS_LANGUAGE.md，按主题分区，比如订单生命周期、人员角色等，并在每个区块中给出表格，包含：

• canonical term
• definition
• aliases to avoid

这种格式特别适合评审，因为团队分歧会很快暴露出来。

哪些情况下它并不适合

如果出现以下情况，就不建议现在用这个 skill：

• 当前对话里还没有足够的领域材料
• 你需要的是完整 ontology、data model，或 event storming 的产出
• 你的目标是品牌命名，而不是领域澄清
• 当前领域仍然过于早期，尚不足以确定 canonical term

这类情况下，更合适的做法是先积累例子和真实表述，再在后面阶段运行它。

如何使用 ubiquitous-language skill

ubiquitous-language 的安装上下文

如果你使用的是来自 mattpocock/skills 的 skills 生态，可以通过常规 skill loader 安装 ubiquitous-language skill。常见方式是：

npx skills add mattpocock/skills --skill ubiquitous-language

如果你的环境是通过其他方式加载 skills，就用你现有的方法即可。关键要求只有两个：agent 能访问 ubiquitous-language 的 skill 定义，并且能在当前工作目录中写入 UBIQUITOUS_LANGUAGE.md。

使用前先读这个文件

先看：

• SKILL.md

这个仓库路径异常简单：主要用法逻辑基本都在这一份文件里。你在判断要不要试用之前，不需要先去翻辅助脚本或层层引用的深层文件。

这个 skill 实际需要什么输入

当当前对话里已经包含以下内容时，这个 skill 的效果最好：

• 领域名词：order、invoice、account、shipment
• 流程动词：approve、fulfill、cancel
• 角色名称：customer、operator、reviewer
• 容易混淆的用法示例：“we sometimes say subscription, sometimes contract”
• 边界上下文：产品范围、受众、系统边界或业务流程

如果缺少这些材料，输出就容易变得单薄，或者过于猜测。

如何正确触发 ubiquitous-language

一个比较弱的请求是：

• “Make a glossary.”

更强的请求是：

• “Use the ubiquitous-language skill on this discussion. Extract domain terms, identify synonyms and overloaded words, propose canonical terms, and write UBIQUITOUS_LANGUAGE.md. Group terms by business area.”

这种说法能明确告诉 agent：要按这个 skill 的预期方式来执行，而不是临时发挥写一份普通 glossary。

如何把一个模糊目标写成高质量 prompt

一个好的 ubiquitous-language 使用 prompt，通常包含四部分：

1. 领域范围
2. 源材料
3. 冲突或痛点
4. 预期输出

示例：

“Use the ubiquitous-language skill for our order-management domain. Based on the conversation so far, extract core terms, flag where we use the same word for different concepts, and propose canonical terms with aliases to avoid. Separate customer-facing terms from internal operational terms where needed. Save the result to UBIQUITOUS_LANGUAGE.md.”

实际工作中的推荐流程

一个比较稳妥的流程通常是：

1. 先自然地讨论领域问题
2. 让术语在对话中真实碰撞
3. 运行 ubiquitous-language
4. 审查它提出的 canonical terms
5. 修正业务层面的错误
6. 将通过的术语表应用到文档、API、UI 文案和 issue templates 中

这个 skill 的价值，往往出现在“已经有过一轮真实讨论之后”，而不是讨论开始之前。

提升输出质量的实用技巧

想要结果更好，可以这样做：

• 提供具体例子，而不只是抽象分类
• 明确指出术语冲突
• 说明最重要的受众是谁：engineers、users、support 还是 writers
• 标注术语是仅内部使用，还是面向外部公开
• 要求模型保留有意义的区分，而不是把一切都压扁成一个标签

这些细节会显著提升术语表质量，因为它们能减少误把不同概念当成同义词合并的情况。

Technical Writing 场景下该怎么用 ubiquitous-language

如果是面向 Technical Writing 的 ubiquitous-language，最好额外加入这些约束：

• 读者偏好的词汇
• 禁止出现的内部黑话
• UI label 限制
• API 术语限制
• 文档应该贴近产品语言，还是对产品语言进行规范化

示例：

“Use the ubiquitous-language skill, but optimize for external documentation. Prefer terms users will recognize, keep internal code names in aliases to avoid, and note any term that should not appear in public docs.”

这样生成的结果会更适合直接进入编辑和文档流程。

预期输出文件与评审方式

生成的文件是 UBIQUITOUS_LANGUAGE.md。评审时可以重点看这几个问题：

• 它有没有误把本来不同的概念合并在一起？
• 它有没有保留含糊术语，却没有给出警示？
• “aliases to avoid” 是否现实、可执行？
• 定义反映的是系统真实行为，还是只是措辞偏好？

最好把第一版输出视为“决策草案”，而不是最终真理。

ubiquitous-language skill 常见问题

ubiquitous-language 对新手友好吗？

友好，前提是你已经有关于该领域的一段对话。你不需要很深的 DDD 背景也能从中获益。输出是可读性很强的 markdown，而且表格会让分歧一目了然。新手最容易忽略的一点是：结果质量高度依赖源对话是否足够具体。

它比直接让模型写 glossary 好在哪里？

ubiquitous-language skill 的范围更窄，所以在术语对齐这件事上通常也更可靠。它的设计目标就是识别歧义、同义词和一词多义，并强制推动 canonical choice。普通 glossary prompt 往往只是把术语列出来，却不解决冲突。

它只适合 DDD 团队吗？

不是。DDD 只是它的表达框架，这个 skill 在任何因术语漂移而产生摩擦的场景里都好用：技术文档、API、支持运营、产品设计、内部工具都适用。尤其当多个团队在描述同一条工作流时用了不同说法，它会特别有帮助。

什么时候不该安装 ubiquitous-language？

如果你的主要需求是下面这些，就不必优先考虑 ubiquitous-language install：

• brainstorm 产品名
• 从零生成面向终端用户的文档
• 构建数据库 schema
• 细致梳理每一条业务规则

这个 skill 解决的是语言规范化，不是完整领域建模。

它能基于很短的对话工作吗？

可以，但效果会弱很多。这个 skill 是从当前对话中提取内容的，所以输入稀薄时，定义就更容易变得泛化，真正有价值的冲突识别也会更少。如果你现在只有很短的一段聊天记录，最好先补充例子、边界情况和竞争性术语。

它适合文档工作流吗？

适合。输出文件很容易做版本管理、在 pull request 里评审，也便于复用到 style guide、架构文档、onboarding 材料和 API references 中。这使得 ubiquitous-language 使用 对希望把术语决策和代码、文档放在一起维护的团队来说，具有很强的实操性。

如何改进 ubiquitous-language skill 的使用效果

给 ubiquitous-language 提供更丰富的领域证据

影响输出质量最大的杠杆，通常不是模型本身，而是源材料质量。在运行 ubiquitous-language 之前，尽量把这些内容放进对话：

• 真实的面向用户术语
• 内部简称
• 流程步骤
• 边界情况
• 两个人用不同词指代同一件事的实际例子

这个 skill 只能标准化它看得见的内容。

区分真正的同义词和必须保留的差异

一个常见失败模式，是把两个相关但不同的概念硬合并。要避免这一点，最有效的做法是直接陈述差异，例如：

• “Order is the customer request; invoice is the billing artifact.”
• “Account is the legal entity; workspace is the product container.”

这样能帮助 skill 保留领域边界，而不是过度简化。

明确告诉它哪套语言应该占上风

canonical naming 本身带有取舍。如果你不说明偏好，skill 可能会选出“技术上没错、但不适合你们工作流”的术语。想得到更可用的结果，可以明确指定：

• external vs internal vocabulary
• engineering vs business terminology
• UI labels vs back-office labels
• 哪些术语因为兼容性必须保留

这些约束会让生成后的 glossary 更容易直接投入使用。

面对歧义重的领域时，用更强的 prompt

如果你的领域本身就高度一词多义，最好明确要求它做 ambiguity analysis。示例：

“Use the ubiquitous-language skill and be strict about ambiguity. If the same term refers to multiple concepts, split them into separate entries and call out the conflict clearly instead of picking one silently.”

这样能降低“看似清晰、实则误判”的风险。

对 aliases to avoid 做更谨慎的复核

“aliases to avoid” 这一列，往往是很多团队收获最大的一部分，但同时也是最容易引发误伤的地方。检查时要特别确认这些被禁别名是否：

• 真的会造成误导
• 在 legacy docs 中是否仍有必要保留
• 是否只对某类受众不适用，而对另一类受众仍然可接受

更好的第二轮修订，往往会保留 canonical term，但把别名限制写得更精细。

第一版出来后继续迭代

最好的 ubiquitous-language 指南 通常不是一次成稿，而是迭代完成的：

1. 运行 skill
2. 标出存在争议的术语
3. 在对话里补充澄清性例子
4. 重新运行 skill
5. 审批 glossary
6. 应用到文档和产品语言中

不要指望第一版就能一次解决所有命名问题。

把结果真正接入你的文档系统

当 UBIQUITOUS_LANGUAGE.md 稳定下来后，要让 ubiquitous-language skill 真正发挥价值，关键是把它接入实际编辑工作，而不是停留在“生成过一份文件”：

• 从 docs style guide 链接到它
• 在 PR review 中使用它
• 让标题和 UI references 对齐 canonical terms
• 审计旧文档中仍在使用的 banned aliases

做到这一步，术语表才会从“摆设”变成真正可执行的工作规范。