ubiquitous-language

ubiquitous-language skill 概覽

ubiquitous-language skill 會把一段凌亂的領域討論，整理成具備 DDD 風格的結構化詞彙表，包含標準術語、定義，以及應避免使用的別名。它的核心工作不是泛泛地「寫一份詞彙表」，而是協助團隊在 product、engineering 與 technical writing 對同一概念使用重疊或不一致術語時，把語言統一起來。

ubiquitous-language 最適合用在哪些情境

當你手上已經有一些領域相關的討論內容，現在需要把它正式整理成可重複使用的成果時，就很適合使用 ubiquitous-language skill。它特別適合：

• domain-driven design 工作
• API 與產品術語清理
• 內部平台命名對齊
• onboarding 文件
• content modeling
• 用於 Technical Writing 的 ubiquitous-language，也就是文件必須一致使用單一標準術語的情境

真正要解決的工作是什麼

大多數使用者其實是在處理以下其中一種問題：

• 「同一件事我們一直在用好幾種不同名字。」
• 「同一個詞在不同情境下代表不同意思。」
• 「我們的文件、產品介面和工程討論用語開始分岔了。」
• 「我們需要根據既有討論先整理出第一版領域詞彙表，而不是從空白開始硬寫。」

這個 skill 會掃描目前的對話內容，找出有歧義或重複的術語，提出帶有明確取向的標準術語建議，並把結果寫入 UBIQUITOUS_LANGUAGE.md。

它和一般 prompt 的差異在哪裡

一般 prompt 也能要求模型產出 glossary，但 ubiquitous-language 的流程更具體，因此在評估是否要採用時更有參考價值：

• 它會主動找出歧義、同義詞與一詞多義的情況
• 它會推動你做出標準命名，而不只是抽取詞彙
• 它會輸出可重複使用的 markdown 成果
• 它採用固定、可審閱、可編修的表格結構

因此，相較於泛泛的「幫我們整理領域術語」，它更適合拿來強化與穩固術語體系。

輸出結果長什麼樣子

這個 skill 會產出 UBIQUITOUS_LANGUAGE.md，內容通常會依主題分段，例如訂單生命週期或人員角色，並在各段中用表格列出：

• 標準術語
• 定義
• 應避免使用的別名

這種格式特別適合審閱，因為只要有分歧，通常很快就會在表格裡暴露出來。

哪些情況不適合使用這個 skill

若遇到以下情況，建議先不要用：

• 目前對話裡還沒有足夠的領域素材
• 你需要的是完整 ontology、data model，或 event storming 輸出
• 你的目標是品牌命名，而不是釐清領域語言
• 這個領域仍處於太多假設、還不適合定標準術語的階段

這些情況下，最好先蒐集更多例子，再晚一點執行這個 skill。

如何使用 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

這個 repository 的路徑設計相當單純：主要使用邏輯就在那一個檔案裡。你不需要在決定要不要試用之前，先去翻一堆 helper scripts 或很深的參照鏈。

這個 skill 實際需要什麼輸入

如果目前對話中已經包含以下內容，這個 skill 的效果會最好：

• 領域名詞：order、invoice、account、shipment
• 流程動詞：approve、fulfill、cancel
• 角色名稱：customer、operator、reviewer
• 容易混淆的用法範例：「我們有時說 subscription，有時又說 contract」
• 邊界脈絡：產品範圍、受眾、系統，或商業流程

少了這些材料，輸出就很容易變得單薄，或帶有過多推測。

如何更有效觸發 ubiquitous-language

一個偏弱的請求會像這樣：

• 「幫我做一份 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 的設計來做，而不是即興寫一份詞彙表。

把模糊需求改寫成高品質 prompt

一個好的 ubiquitous-language usage 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. 審閱提出的標準術語
5. 修正業務層面的錯誤
6. 把核准後的詞彙表用到文件、API、UI 文案與 issue templates

這個 skill 在經過一些真實討論之後最有價值，而不是在那之前。

能提升輸出品質的實用技巧

如果想要得到更好的結果，建議：

• 提供具體例子，不要只給抽象分類
• 明確指出哪些術語有衝突
• 說清楚哪一類受眾最重要：engineers、users、support、writers
• 註明某個術語是僅供內部使用，還是會對外公開
• 要求模型保留有意義的區別，不要把所有東西硬併成同一個標籤

這些資訊會明顯提升詞彙表品質，因為它們能減少把其實不同的概念誤判成同義詞的情況。

做 Technical Writing 時，ubiquitous-language 要怎麼調整

如果是要做 ubiquitous-language for Technical Writing，建議額外加上這些限制條件：

• 讀者偏好的用語
• 禁止出現在文件裡的內部術語
• 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.」

這樣輸出的結果會更適合直接拿來做 editorial 使用。

預期輸出檔案與審閱方式

產出的檔案會是 UBIQUITOUS_LANGUAGE.md。審閱時可以重點檢查以下問題：

• 這個 skill 有沒有不小心把不同概念合併在一起？
• 它有沒有保留含糊術語，卻沒有標示警告？
• 「aliases to avoid」是否切合實際？
• 定義反映的是系統真實行為，還是只是文字偏好？

請把第一版輸出視為決策草案，而不是最終真理。

ubiquitous-language skill 常見問題

ubiquitous-language 對新手友善嗎？

友善，前提是你已經有一些關於該領域的對話內容。你不需要很深的 DDD 背景也能受益。輸出是可讀性高的 markdown，表格也讓分歧很容易被看見。新手最常忽略的是：結果品質高度依賴來源討論是否夠具體。

它和直接要求做 glossary 相比，為什麼更好？

ubiquitous-language skill 的範圍更聚焦，因此在術語對齊上通常更可靠。它的設計目的就是找出歧義、同義詞與一詞多義，並逼你做出標準命名選擇。一般 glossary prompt 往往只是把詞列出來，卻沒有真正解決衝突。

它只有 DDD 團隊才用得到嗎？

不是。DDD 的詞彙只是它的框架，實際上凡是術語漂移會造成摩擦的地方都很適合用：technical documentation、API、support operations、product design，或 internal tooling。尤其當多個團隊在描述同一流程時各說各話，它會特別有幫助。

什麼情況下不該優先安裝 ubiquitous-language？

如果你的主要需求是以下其中之一，就不應優先考慮 ubiquitous-language install：

• 發想產品名稱
• 從零開始產出終端使用者文件
• 建立資料庫 schema
• 完整梳理每一條 business rule 的細節

這個 skill 是拿來做語言標準化，不是完整的領域建模工具。

它能靠一小段對話運作嗎？

可以，但結果會比較弱。這個 skill 是從目前對話中抽取內容，因此輸入太少時，定義容易流於籠統，也較難抓出真正有價值的衝突。如果你目前只有一小段聊天內容，建議先補上例子、邊界案例和彼此競爭的術語。

它適合放進文件工作流程嗎？

適合。輸出的檔案容易做版本控管、方便在 pull request 中審閱，也能重用在 style guides、architecture docs、onboarding material 與 API references。這讓 ubiquitous-language usage 很適合那些希望把術語決策和程式碼、文件一起維護的團隊。

如何改善 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 保住領域邊界，而不是過度簡化。

明確告訴它哪一套語言應該勝出

標準命名本來就帶有取向。如果你不先說清楚偏好，這個 skill 可能會選出技術上正確、但不適合你工作流程的術語。要改善結果，可以明講：

• 對外用語 vs 內部用語
• engineering terminology vs business terminology
• UI labels vs back-office labels
• 哪些術語因相容性因素必須保留

這些指引能讓產出的詞彙表在生成後更容易真正被使用。

面對高歧義領域時，請用更強的 prompt

如果你的領域本身就有很多一詞多義，請明確要求它做歧義分析。範例：

「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」這一欄通常是許多團隊收穫最大之處，但也最容易因判斷失準而造成混淆。請特別檢查這些被禁止的別名是否：

• 真的會誤導
• 在舊文件中仍然有保留必要
• 對某一類受眾可接受，但對另一類不適合

更好的第二輪修訂，往往不是改掉標準術語，而是把 alias guidance 調整得更細緻。

第一版之後要持續迭代

最好的 ubiquitous-language guide 通常都是迭代出來的：

1. 執行這個 skill
2. 標記有爭議的術語
3. 在對話中補上釐清用的例子
4. 再跑一次這個 skill
5. 核准詞彙表
6. 套用到文件與產品語言中

不要期待第一版就能一次定案所有命名決策。

把結果延伸進你的文件系統

當 UBIQUITOUS_LANGUAGE.md 穩定下來之後，想真正放大 ubiquitous-language skill 的價值，就要把它接進實際的 editorial 工作流程：

• 從 docs style guide 連到它
• 在 PR review 中使用它
• 讓 headings 與 UI references 對齊標準術語
• 稽核舊文件中是否仍有被禁用的別名

做到這一步，這份詞彙表才會從「擺設」變成真正能落地運作的規範。