ubiquitous-language

ubiquitous-language スキルの概要

ubiquitous-language スキルは、ドメインに関する散発的でまとまりのない議論を、正規の用語・定義・避けるべき別名を備えた、DDDスタイルの構造化された用語集に変換します。単に「用語集を書く」ための汎用ツールではありません。プロダクト、エンジニアリング、テクニカルライティングの各チームが、同じ概念に対して重複したり食い違ったりする表現を使っているときに、チーム内の言葉を標準化するのがこのスキルの中心的な役割です。

ubiquitous-language が特に向いている用途

ubiquitous-language skill は、すでに会話の中にドメイン固有の話題があり、それを再利用できる形に整理・明文化したいときに特に有効です。たとえば次のような用途に向いています。

• ドメイン駆動設計の検討
• API やプロダクト用語の整理
• 社内プラットフォームの命名統一
• オンボーディング用ドキュメント
• コンテンツモデリング
• ドキュメント全体で1つの正規用語を一貫して使いたい ubiquitous-language for Technical Writing

実際に解決したい課題

多くのユーザーは、実際には次のような問題を解消したいと考えています。

• 「同じものに対して複数の呼び方をしてしまっている」
• 「1つの用語が文脈によって違う意味になっている」
• 「ドキュメント、プロダクト UI、エンジニア間の会話で使う言葉がずれてきている」
• 「ゼロから考えるのではなく、既存の議論から最初のドメイン用語集を作りたい」

このスキルは現在の会話を読み取り、曖昧だったり重複していたりする用語を見つけ、判断を伴う正規用語を提案し、その結果を UBIQUITOUS_LANGUAGE.md に書き出します。

通常のプロンプトと何が違うのか

通常のプロンプトでも用語集の作成は依頼できます。ただし ubiquitous-language のワークフローはそれより具体的で、導入判断の材料としても有用です。

• 曖昧さ、同義語、意味の過積載が起きている用語を見つける
• 単なる抽出ではなく、正規の命名に寄せる
• 再利用しやすい markdown の成果物を出力する
• レビューや編集がしやすい、予測可能な表形式の構造に従う

そのため、単なる「ドメイン用語を要約して」という依頼よりも、用語の固定・整理には適しています。

出力される内容

このスキルは UBIQUITOUS_LANGUAGE.md を生成し、その中に order lifecycle や people のようなトピック別セクションを作成し、各セクションに次の項目を含む表を出力します。

• canonical term
• definition
• aliases to avoid

この形式はレビューに特に向いています。意見の食い違いがすぐ見えるからです。

このスキルが向かないケース

次のような場合は、このスキルをすぐ使わないほうがよいです。

• 会話の中に、まだ十分なドメイン情報がない
• 必要なのが完全な ontology、data model、event storming の成果物である
• 目的がドメインの明確化ではなくブランド名の検討である
• まだドメイン仮説の段階で、正規用語を決めるには早すぎる

このような場合は、まず具体例を集めてから、後でこのスキルを実行するほうが適しています。

ubiquitous-language スキルの使い方

ubiquitous-language の導入前提

mattpocock/skills の skills ecosystem を使っている場合は、通常の skill loader から ubiquitous-language skill をインストールします。よくあるパターンは次のとおりです。

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

環境によって別の方法で skills を読み込む場合は、その方法を使って構いません。重要なのは、エージェントが ubiquitous-language の skill definition にアクセスでき、作業ディレクトリに UBIQUITOUS_LANGUAGE.md を書き込めることです。

使う前にまず読むべきファイル

最初に確認するのは次のファイルです。

• SKILL.md

このリポジトリは構成がかなりシンプルで、主な使い方のロジックはこの1ファイルにまとまっています。試すかどうかを判断する段階で、helper script や深い参照先まで追いかける必要はありません。

実際に必要な入力

このスキルは、現在の会話の中に次のような材料がすでに含まれているときに最も力を発揮します。

• ドメイン名詞: order, invoice, account, shipment
• プロセスを表す動詞: approve, fulfill, cancel
• ロール名: customer, operator, reviewer
• 混乱している使い方の例: “we sometimes say subscription, sometimes contract”
• 境界に関する文脈: product area, audience, system, or business process

こうした材料がないと、出力は薄くなったり、推測に寄りすぎたりします。

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.”

この言い方なら、単にその場しのぎで用語集を作るのではなく、意図された ubiquitous-language の使い方としてエージェントに伝わります。

曖昧な目的を質の高いプロンプトに変える

良い ubiquitous-language usage プロンプトには、通常次の4要素が入ります。

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. 承認した用語集を docs、APIs、UI copy、issue templates に反映する

このスキルの価値が最も高いのは、実際の議論がある程度進んだ「後」です。議論の前段階ではありません。

出力品質を上げる実践的なコツ

より良い結果を得るには、次の点が効果的です。

• 抽象的なカテゴリだけでなく、具体例を入れる
• 用語の衝突を明示する
• 何を優先するかを伝える: engineers, users, support, writers
• その用語が internal-only なのか public-facing なのかを示す
• 何でも1つのラベルにまとめるのではなく、意味のある違いは残すよう依頼する

こうした情報があると、誤って同義語として統合してしまうケースが減り、用語集の品質が大きく上がります。

テクニカルライターが変えるべき点

ubiquitous-language for Technical Writing として使う場合は、次のような制約を追加すると有効です。

• 読者にとって自然な推奨語彙
• 禁止したい社内 jargon
• UI label の制約
• API term の制約
• docs が product language をそのまま踏襲すべきか、正規化すべきか

例:

“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 スキル FAQ

ubiquitous-language は初心者向けですか？

はい。すでにドメインについての会話があるなら、DDD の深い知識がなくても十分役立ちます。出力は読みやすい markdown で、表形式なので認識のズレも見つけやすくなります。初心者が見落としがちなのは、出力品質が元の会話の具体性に大きく左右される点です。

直接「用語集を作って」と頼むより何が良いのですか？

ubiquitous-language skill は用途が絞られているぶん、用語の整合性を取る目的にはより安定しています。曖昧さ、同義語、意味が重なった用語を検出し、正規の用語を決める方向に持っていく設計だからです。汎用的な glossary プロンプトだと、衝突を解消しないまま単に用語を列挙して終わることがよくあります。

DDD チームにしか役立ちませんか？

いいえ。DDD の語彙を枠組みとして使っているだけで、用語のずれが摩擦を生む場面なら広く有効です。たとえば technical documentation、APIs、support operations、product design、internal tooling などでも役立ちます。特に、複数チームが同じワークフローを別の言葉で説明しているときに効果的です。

どんなときは ubiquitous-language をインストールしないほうがいいですか？

主な目的が次のいずれかなら、ubiquitous-language install を優先する必要はありません。

• product names のブレインストーミング
• エンドユーザー向けドキュメントのゼロからの生成
• database schema の構築
• business rule を細部まで網羅的に整理すること

このスキルが担うのは language normalization であり、完全な domain modeling ではありません。

小さな会話からでも使えますか？

使えますが、結果は弱くなりやすいです。このスキルは現在の会話から抽出するため、入力が少ないと定義が汎用的になり、意味のある衝突検出も減ります。短いチャットしかない場合は、先に examples、edge cases、competing terms を足しておくのがおすすめです。

documentation workflows にも合いますか？

はい。出力ファイルは version 管理しやすく、pull requests でレビューしやすく、style guides、architecture docs、onboarding material、API references へ再利用しやすい形式です。そのため、用語に関する意思決定を code や docs と並べて運用したいチームにとって、ubiquitous-language usage は実務に組み込みやすい選択肢です。

ubiquitous-language スキルを改善するには

より豊かなドメイン根拠を与える

出力品質に最も効くのは、元になる材料の質です。ubiquitous-language を実行する前に、次のような情報を会話に含めておきましょう。

• 実際にユーザー向けに使っている用語
• 社内で使う shorthand
• プロセスの各ステップ
• edge cases
• 同じものに対して2人が別の言葉を使った具体例

このスキルが正規化できるのは、見えているものだけです。

本当の同義語と重要な違いを分ける

よくある失敗は、近いけれど別物の概念を1つに潰してしまうことです。これを防ぐには、対比を明示してください。たとえば次のように伝えます。

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

こうした対比があると、過度に単純化せず、ドメインの境界を保ったまま ubiquitous-language が整理しやすくなります。

どの言葉を優先するかを伝える

正規用語の選定には判断が入ります。希望を伝えないと、技術的には正しくても、実際の運用には合わない語が選ばれることがあります。結果を改善したいなら、次の点を明示してください。

• external vs internal vocabulary
• engineering vs business terminology
• UI labels vs back-office labels
• 互換性のために残す必要がある用語

このガイドがあると、生成後の用語集が実務でずっと使いやすくなります。

曖昧さの強いドメインでは、より強いプロンプトを使う

ドメインに意味の重なりが多いなら、曖昧性分析を明示的に依頼してください。例:

“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 ではまだ必要か
• ある audience では許容され、別の audience では不適切ではないか

2回目の見直しでは、canonical term は維持しつつ、alias guidance だけを少し柔らかくするほうがよいこともあります。

初回ドラフトのあとに反復する

最良の ubiquitous-language guide は、一度で完成させるものではなく反復的に育てるものです。

1. スキルを実行する
2. 争点のある用語をマークする
3. 会話に補足例を追加する
4. スキルを再実行する
5. 用語集を承認する
6. docs や product language 全体に適用する

最初の1回で、すべての命名判断が確定するとは考えないでください。

結果をドキュメント運用に接続する

UBIQUITOUS_LANGUAGE.md が安定してきたら、実際の編集フローに組み込むことで ubiquitous-language skill の価値はさらに高まります。

• docs style guide からリンクする
• PR review で参照する
• 見出しや UI references を canonical terms に合わせる
• 古い docs に banned aliases が残っていないか監査する

そうして初めて、この用語集は飾りではなく、実際に機能する運用資産になります。