Ubiquitous Language

概要

このスキルは、エリック・エヴァンスが提唱したユビキタス言語（Ubiquitous Language）の 実践方法を提供します。ドメインエキスパートと開発者が共有する厳密な語彙体系を構築し、 コミュニケーションの齟齬を防ぎ、コードがドメインを正確に表現することを目指します。

主要な価値:

• ドメインエキスパートと開発者間のコミュニケーション向上
• コードの可読性と理解容易性の向上
• 誤解に起因するバグの削減
• ドメイン知識の明示的な文書化

対象ユーザー:

• ドメインモデルを設計するエージェント
• チーム全体で用語を統一したい開発者
• ビジネスと技術の橋渡しをする人

リソース構造

ubiquitous-language/
├── SKILL.md                                    # 本ファイル
├── resources/
│   ├── terminology-extraction.md              # 用語抽出の手法
│   ├── naming-conventions.md                  # コードの命名規則
│   └── glossary-maintenance.md                # 用語集の維持管理
├── scripts/
│   └── analyze-terminology.mjs                # 用語一貫性分析スクリプト
└── templates/
    └── domain-glossary-template.md            # ドメイン用語集テンプレート

コマンドリファレンス

リソース読み取り

# 用語抽出の手法
cat .claude/skills/ubiquitous-language/resources/terminology-extraction.md

# コードの命名規則
cat .claude/skills/ubiquitous-language/resources/naming-conventions.md

# 用語集の維持管理
cat .claude/skills/ubiquitous-language/resources/glossary-maintenance.md

スクリプト実行

# 用語一貫性の分析
node .claude/skills/ubiquitous-language/scripts/analyze-terminology.mjs src/shared/core/

テンプレート参照

# ドメイン用語集テンプレート
cat .claude/skills/ubiquitous-language/templates/domain-glossary-template.md

核心概念

1. ユビキタス言語とは

定義: ドメインエキスパートと開発者がプロジェクト全体で使用する共通の語彙体系

特徴:

• ドメインの概念を正確に表現
• 技術用語と明確に区別
• チーム全体で一貫して使用
• コード、ドキュメント、会話すべてに適用

2. ユビキタス言語の原則

原則 1: ドメインエキスパートの言葉を採用

• 技術的な言い換えを避ける
• ビジネスで実際に使われている用語を使用
• 専門用語はそのまま採用

原則 2: 一つの概念に一つの用語

• 同義語を排除
• 曖昧さを避ける
• 用語の意味を明確に定義

原則 3: コードに反映

• クラス名、メソッド名に用語を使用
• コードがドキュメントとして機能
• ドメインエキスパートがコードを読める

原則 4: 境界を意識

• コンテキストごとに用語が異なる場合がある
• 同じ用語でも意味が異なることを認識
• コンテキストマップで用語の対応を管理

ワークフロー

Phase 1: 用語の収集

目的: ドメインで使用される用語を網羅的に収集

ステップ:

1. ドメインエキスパートとの会話から用語を抽出
2. 既存ドキュメントから用語を収集
3. 要件定義書から用語を特定
4. 用語候補リストを作成

判断基準:

• 主要なドメイン概念が網羅されているか？
• ビジネスプロセスで使用される用語が含まれているか？
• 状態や遷移を表す用語が特定されているか？

Phase 2: 用語の定義

目的: 各用語の意味を明確に定義

ステップ:

1. 各用語の定義を記述
2. 用語間の関係性を明確化
3. 同義語・類義語を整理
4. 曖昧な用語を排除または明確化

定義テンプレート:

用語名: [用語]
定義: [簡潔な定義]
コンテキスト: [使用されるコンテキスト]
関連用語: [関連する他の用語]
コード対応: [クラス名/型名]
例: [使用例]

判断基準:

• 定義が曖昧でないか？
• ドメインエキスパートが同意する定義か？
• 技術的な解釈と一致しているか？

Phase 3: コードへの反映

目的: 用語をコードに正確に反映

ステップ:

1. クラス名を用語に合わせる
2. メソッド名にドメインの動詞を使用
3. プロパティ名にドメインの属性名を使用
4. コメントや型定義でも一貫して使用

命名対応表:

ドメイン用語	コード要素	例
名詞	クラス名、型名	Workflow, Order
動詞	メソッド名	execute(), approve()
形容詞/状態	列挙値	PENDING, COMPLETED
属性	プロパティ名	userId, createdAt

判断基準:

• ドメインエキスパートがコードを読めるか？
• 技術用語とドメイン用語が混在していないか？
• 命名が一貫しているか？

Phase 4: 用語集の維持

目的: 用語集を最新の状態に維持

ステップ:

1. 新しい用語の追加プロセスを確立
2. 定期的なレビューサイクルを設定
3. 変更履歴を記録
4. チーム全体への周知

判断基準:

• 新しい概念が追加されているか？
• 用語の定義が最新か？
• チーム全体が最新の用語集にアクセスできるか？

いつ使うか

シナリオ 1: 新プロジェクトの開始

状況: 新しいドメインでプロジェクトを始める

適用条件:

• ドメインが複雑または専門的
• 複数のステークホルダーが関与
• 長期的なプロジェクト

期待される成果: ドメイン用語集の初版

シナリオ 2: 既存コードのリファクタリング

状況: レガシーコードの命名を改善したい

適用条件:

• 技術用語とドメイン用語が混在
• 命名に一貫性がない
• コードの理解が困難

期待される成果: 命名規則の統一、用語集との整合

シナリオ 3: チーム間の認識統一

状況: チーム内で用語の解釈が異なる

適用条件:

• 同じ概念に異なる用語を使用
• ドメインエキスパートと開発者で認識が違う
• ドキュメントとコードで用語が不一致

期待される成果: 用語集の共有、認識の統一

ベストプラクティス

すべきこと

1. ドメインエキスパートとの協力:

   • 用語定義はドメインエキスパートと共同で
   • 技術者だけで決めない
   • 定期的なレビューを実施

2. 用語集の可視化:

   • アクセスしやすい場所に配置
   • 検索可能な形式で管理
   • 変更通知の仕組みを用意

3. コードでの一貫性:

   • 同じ概念に同じ名前を使用
   • 略語は避ける（または用語集で定義）
   • コメントでも用語を使用

避けるべきこと

1. 技術用語への言い換え:

   • ❌ 「ワークフロー」→「プロセスオブジェクト」
   • ✅ 「ワークフロー」→「Workflow」

2. 同義語の乱用:

   • ❌ 「ユーザー」「顧客」「アカウント」を混用
   • ✅ 一つの概念に一つの用語を決定

3. 用語集の放置:

   • ❌ 作成して終わり
   • ✅ 継続的な更新とレビュー

トラブルシューティング

問題 1: ドメインエキスパートと用語が合わない

症状: 開発者の使う用語とビジネスの用語が異なる

原因: 技術的な抽象化が過度

解決策:

1. ドメインエキスパートとのセッションを設定
2. ビジネスで実際に使われている用語を聞く
3. コードの命名を修正

問題 2: コンテキストで用語の意味が異なる

症状: 同じ用語が異なる意味で使用されている

原因: 境界付けられたコンテキストの未定義

解決策:

1. コンテキスト境界を明確化
2. 各コンテキストで用語を定義
3. コンテキストマップで対応を管理

問題 3: 用語集が更新されない

症状: 用語集が古くなり参照されなくなる

原因: 更新プロセスの不在

解決策:

1. 更新責任者を明確化
2. 定期レビューサイクルを設定
3. PR レビュー時に用語チェックを追加

関連スキル

• .claude/skills/domain-driven-design/SKILL.md (.claude/skills/domain-driven-design/SKILL.md): DDD の戦術的パターン
• .claude/skills/bounded-context/SKILL.md (.claude/skills/bounded-context/SKILL.md): コンテキスト境界の定義
• .claude/skills/value-object-patterns/SKILL.md (.claude/skills/value-object-patterns/SKILL.md): ドメイン概念の型定義

参考文献

• 『エリック・エヴァンスのドメイン駆動設計』

  • 第 2 章: コミュニケーションと言語の使用

• 『実践ドメイン駆動設計』

  • 第 2 章: ドメイン、サブドメイン、境界付けられたコンテキスト

変更履歴

バージョン	日付	変更内容
1.0.0	2025-11-25	初版作成 - ユビキタス言語の確立と適用