Collection

---
name: .claude/skills/ubiquitous-language/SKILL.md
description: |
  ドメイン駆動設計におけるユビキタス言語の確立と適用を専門とするスキル。

  📚 リソース参照:
  このスキルには以下のリソースが含まれています。
  必要に応じて該当するリソースを参照してください:

  - `.claude/skills/ubiquitous-language/resources/glossary-maintenance.md`: Glossary Maintenanceリソース
  - `.claude/skills/ubiquitous-language/resources/naming-conventions.md`: Naming Conventionsリソース
  - `.claude/skills/ubiquitous-language/resources/terminology-extraction.md`: Terminology Extractionリソース

  - `.claude/skills/ubiquitous-language/templates/domain-glossary-template.md`: Domain Glossaryテンプレート

  - `.claude/skills/ubiquitous-language/scripts/analyze-terminology.mjs`: Analyze Terminologyスクリプト

version: 1.0.0
---

# 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            # ドメイン用語集テンプレート
```

## コマンドリファレンス

### リソース読み取り

```bash
# 用語抽出の手法
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
```

### スクリプト実行

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

### テンプレート参照

```bash
# ドメイン用語集テンプレート
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 | 初版作成 - ユビキタス言語の確立と適用 |