ubiquitous-language

ubiquitous-language スキルの概要

ubiquitous-language が何をするか

ubiquitous-language スキルは、雑然とした会話を DDD 風の用語集に変換します。ドメイン用語を抽出し、曖昧さや同義語の揺れを見つけ、正規化された UBIQUITOUS_LANGUAGE.md を作成します。プロダクト、エンジニアリング、Technical Writing で共通語彙が必要なら、この ubiquitous-language スキルは、モデルに勝手な表現をさせるのではなく、用語を明示化するのに役立ちます。

どんな人がインストールすべきか

ドメインモデルを定義している、製品領域のドキュメントを書いている、チーム間で用語を揃えたい、仕様書やドキュメント全体の紛らわしい言葉を整理したい、という場合にこの ubiquitous-language スキルをインストールしてください。すでに会話ログ、インタビュー記録、要件スレッドがあり、用語をすばやく正規化したいときに特に有効です。

なぜ役立つのか

本当の仕事は「用語集を作ること」ではなく、「意味のズレを防ぐこと」です。このスキルが強いのは、最大のリスクが命名の不一致、1語に複数の意味が載っている状態、同じものに複数の呼び方があること、という場面です。文章を量産するためというより、採用する正規名称を1つ決め、避けるべき表現をはっきりさせるためのスキルです。

ubiquitous-language スキルの使い方

スキルをインストールしてファイルの場所を確認する

スキルマネージャーから ubiquitous-language install の流れを使うか、mattpocock/skills の skills/deprecated/ubiquitous-language からインストールしてください。まずは SKILL.md を確認します。ここには補助スクリプト、参照ファイル、リソースフォルダはないため、主な挙動はこの1ファイルに集約されています。

適切な元資料を渡す

ubiquitous-language をうまく使うには、実際のドメイン用語が入った会話、メモ、チケットスレッド、ドラフト仕様を渡すのが基本です。強いプロンプトでは、文脈と判断対象を明示します。たとえば、次のように指示します。「この注文管理アプリのプロダクトディスカバリー会話から ubiquitous-language の用語集を抽出してください。customer、order、invoice、shipment、refund を優先し、曖昧に使われている語も指摘してください。」

出力品質に合わせてプロンプトを整える

このスキルは、重視したい用語と、用語集の読み手を伝えると最も効果を発揮します。Technical Writing 向けの ubiquitous-language にしたいなら、その点を明示し、ドキュメント、UI ラベル、API ドキュメントで再利用できる用語を求めてください。さらに、「正規名称を優先する」「避けるべき別名を明記する」「ユーザー向けの影響がある用語に絞る」といった条件も添えると精度が上がります。

シンプルなワークフローで進める

まず、元の会話やメモを貼り付けます。次に、用語集と、見つかった曖昧さを出力するよう依頼します。その後、生成された UBIQUITOUS_LANGUAGE.md を製品の実態と照らし合わせて確認します。各用語が本当に別概念か、同義語をまとめるべきか、チームの実際の語彙に合わせて名称を変えるべきかをチェックしてください。

ubiquitous-language スキルの FAQ

通常のプロンプトより優れているのか？

はい。単発の要約ではなく、再現性のある用語整理が欲しいときに向いています。通常のプロンプトでも用語一覧は作れますが、ubiquitous-language スキルは曖昧さを見つけ、正規表現を提案し、結果を再利用しやすいファイル形式で保存することを前提にしています。

何をしないのか？

関係者によるドメイン検証の代わりにはなりません。会話から用語を推測して整理することはできますが、チームが正式に採用しているラベルまでは分かりません。元資料が薄い、または矛盾している場合、出力は正解ではなくレビュー用の下書きとして扱うべきです。

初心者でも使いやすいのか？

はい。明確な元テキストと対象ドメインを用意できるなら使いやすいです。初心者がやりがちな失敗は、十分なドメイン文脈を渡さずに「用語集を作って」とだけ頼むことです。会話が具体的で、対象読者が明確なほど、ubiquitous-language の精度は上がります。

どんなときに使わないほうがいいのか？

短いマーケティング文言、一般的な用語集ページ、用語の衝突がない大まかな分類だけが必要なら、このスキルは省いて構いません。実装、ドキュメント、部門横断の認識合わせに言葉の選択が影響する場合にこそ、最も価値を発揮します。

ubiquitous-language スキルを改善する方法

余計な装飾ではなく、ドメインの証拠を増やす

最も効果が大きいのは、元の言葉を豊かにすることです。ユーザーストーリー、サポートチケット、オンボーディング文面、プロダクト議論などが役立ちます。ubiquitous-language では、抽象的な機能一覧より、具体例に囲まれた用語のほうが正規化しやすくなります。

本当に重要な判断を指定する

何を最適化したいのかをスキルに伝えてください。たとえば、ドキュメント全体の一貫性、UI 内の同義語削減、API 命名の明確化、DDD との整合性強化などです。ubiquitous-language を Technical Writing に使うなら、見出し、ラベル、表の行、各ドキュメント間で再利用しやすい用語を優先するよう依頼するとよいです。

よくある失敗パターンを確認する

別概念をまとめすぎる、チームが決して使わない造語を作る、ドメイン固有のニュアンスを一般的な言葉に潰してしまう、という失敗に注意してください。最初のドラフトが抽象的すぎると感じたら、境界事例の例を返し、それらの違いを軸に用語集を組み直すよう依頼します。

具体的な修正で反復する

出力を改善する最短ルートは、どの用語選択がどう間違っているかを具体的に示すことです。たとえば、「account ではなく customer を使う」「purchase と order は分ける」「refund と credit は別概念として扱う」と伝えます。こうしたフィードバックがあると、次回の ubiquitous-language スキルの出力は格段に鋭くなります。