株式会社マインディア テックブログPublicationへの投稿
📚

Claude Codeで開発する時こそ「ユビキタス言語辞書」を作ろう！

しゅん@元ギタリストのデータエンジニア
に公開
AI
ドメイン駆動開発
Claude
Claude Code
ユビキタス言語辞書
tech

3秒まとめ 📝

Claude Codeと一緒にユビキタス言語辞書を自動更新する仕組みを実装してみました！

  • AIツール時代の新たな課題は「用語の齟齬によるAIの誤った解釈」だった！
  • AIの「忘れっぽさ」への対処法が意外すぎる
  • 既存システムとの整合性は段階的移行で解決できる

どんな人向けの記事？ 🎯

この記事は、以下のような方に読んでもらいたいです！

  • システム開発のチームリーダーの方: 「チーム内で用語がバラバラで困ってる...」でお困りの方
  • AI活用エンジニアの方: 「Claude Codeが思った通りに動いてくれない！」に興味がある方
  • DDD実践者の方: 「ユビキタス言語の管理が大変すぎる...」を検討中の方

なぜユビキタス言語辞書の自動更新を試したのか 🤔

実はつい先日、ぼくのプロジェクトでClaude Codeを使って実装してたら、とんでもないことが起きたんです。プロジェクト内で「Client」って言ったら「法人顧客 = 会社」のことを指してたんですけど、Claude Codeは当然のように「個人顧客」として扱っていて、Client の属性として company を扱っていて、話が全く噛み合わない...

結果、プロンプトで明確に指示出ししたり、CLAUDE.md で定義したりしてみたんですが、それでも話が全く噛み合わない...
Claude codeが忘れちゃうし、管理が大変...

でもこれ、よく考えたらAIツールだけじゃなくて、新メンバーが入ってきたときや、
エンドユーザー〜ビジネス担当者〜開発者など、プロジェクトに関わる全員を巻き込んで共通化したいことです。

実際に手を動かしてこれらの疑問を検証してみようと考えました。

この記事では、Claude Codeを使ったユビキタス言語辞書の自動更新の実装から検証まで、ぼくが体験したリアルな内容をお伝えします！

環境構築編：実際に手を動かしてみた 🛠️

まずは環境セットアップから始めていきます。

検証環境

項目 詳細
OS macOS 15.6
Claude Code 最新版（2025年9月時点）
プロジェクト構成 TypeScript + Python
エディタ Cursor

セットアップ手順

1. CLAUDE.mdに第1原則を設定

CLAUDE.md
# CLAUDE.md

## 第1原則：ユビキタス言語の厳守

AIは作業開始時に必ず `@docs/ubiquitous-language.md` を読み込み、以下を遵守する：

- コード内の全ての用語は辞書の定義に従って使用する
- 新しい用語が必要な場合：
  1. 既存辞書で代替可能か検討
  2. 本当に必要ならユーザーに確認
  3. 承認後に辞書へ追記
- 用語の変更・修正が必要な場合：
  1. 影響範囲を説明
  2. ユーザーに確認
  3. 承認後に辞書を更新（状態を🔴非推奨に）
  4. コードベース全体を修正

原則は明確に、かつ実行可能な形で書くのがめっちゃ大事！曖昧な指示だとAIも困っちゃいます。

2. ユビキタス言語辞書ファイルの作成

基礎とあるユビキタス言語辞書の初版を作成しましょう！
この作成自体もClaude Codeを活用してみましょう！どのように管理をしたいのかを説明し、作成をお願いします。

docs/ubiquitous-language.md
# ユビキタス言語辞書

このドキュメントは、プロジェクトで使用される用語とその意味を定義した辞書です。
チーム内での認識の齟齬をなくし、一貫性のあるコミュニケーションを促進することを目的としています。

## 用語の状態管理

- **🟢 現在使用中**: 現在のコードベースで積極的に使用されている用語
- **🟡 議論中**: 使用するかどうか議論中の用語
- **🔴 非推奨**: 過去に使用されていたが現在は非推奨となった用語

---

## ユーザー管理

| 状態 | 日本語名 | 英語名（単数形） | 英語名（複数形） | 意味 | 例文 |
|------|----------|-----------------|------------------|------|------|
| 🟢 | ユーザー | User | Users | システムを利用する個人 | 「新規ユーザーを登録する」 |
| 🟢 | 顧客 | Customer | Customers | 契約関係にある法人（B2B専用） | 「顧客ID: customer_123の情報を取得」 |
| 🟡 | クライアント | Client | Clients | 法人顧客の別称（顧客を推奨） | 「クライアントとの契約更新」 |
| 🔴 | 会員 | ~~member~~ | ~~members~~ | ~~旧称、ユーザーに統一~~ | ~~「会員登録画面」~~ |

## 命名規則

### 言語別の命名規則
- **Python（バックエンド）**: snake_case
  - 例：`user_id`, `customer_name`, `created_at`
- **TypeScript（フロントエンド）**: camelCase
  - 例：`userId`, `customerName`, `createdAt`
- **共通ルール**: 辞書の英語名を基準に各言語の規則を適用

### 変換例
| 日本語 | 辞書の英語名 | Python (snake_case) | TypeScript (camelCase) |
|--------|-------------|---------------------|------------------------|
| ユーザーID | user + id | user_id | userId |
| 顧客名 | customerName | customer_name | customerName |
| 作成日時 | createdAt | created_at | createdAt |

---

## 更新履歴

- ユビキタス言語辞書に更新があった場合は、更新内容を `docs/changelog.md` に追記してください

## 非推奨用語

| 状態 | 日本語名 | 英語名（単数形） | 英語名（複数形） | 現在の代替用語 | 理由 |
|------|----------|-----------------|------------------|----------------|------|
| 🔴 | 会員 | member | members | User | より汎用的な名称に統一（2024-12-01より非推奨） |

---

## 使用上の注意

1. 新しい用語を追加する際は、必ず状態（🟢/🟡/🔴）を明記してください
2. 議論中（🟡）の用語は、チーム内で合意が取れ次第、現在使用中（🟢）または非推奨（🔴）に更新してください
3. コード内のコメントや変数名は、このユビキタス言語辞書に従って記述してください

この表形式、めちゃくちゃ見やすいでしょ？

ハマったポイント 😅

実装中にいくつかハマりポイントがありました...

問題 現象 解決策
AIの記憶力 会話が長くなると原則を忘れる 次のセクションの「忘れさせない対策」が重要でした

「忘れっぽいClaude Code」への対処

CLAUDE.md（追記）
## 第2原則：忘れっぽいClaude Codeのフォロー

AIは全てのチャットの冒頭にこの原則を逐語的に必ず画面出力してから対応する。

参考：Claude Codeの「すぐルール忘れる問題」を解決する超効果的な方法

※この原則以上に、適切にコンテキストを管理したり、実装毎にセッションを分けたりすることが重要でした！

実装検証編：ユビキタス言語辞書の実力を測ってみた ⚡

環境が整ったので、実際の性能を測定してみます！

検証内容

実際にユビキタス言語辞書の自動更新を検証しました。「対象者」を表す用語として使用していた Subject を、より直感的な Target に変更する過程で、辞書の状態管理システムがどのように機能するかを確認しました。

用語変更の実施内容

# プロンプト
本プロジェクトで使われている`subject`という用語を`target`に変更してください

※原則がきちんと出力されています

  1. 変更前の状態

    • Subject：🟢現在使用中として登録されていた
    • 「本プロジェクトの対象者」として定義

  2. 変更後の状態

    • Subject：🔴非推奨に変更し、変更理由「より直感的な名称に変更」を明記
    • Target：🟢現在使用中として新規登録
    • 同じ意味「対象者」を維持しながら、より分かりやすい英語名を採用

  3. 辞書の自動更新内容

    • 非推奨用語セクションにSubjectを追加
    • 現在の代替用語としてTargetを指定
    • 状態管理（🟢/🔴）が適切に機能していることを確認

planモードで計画を立てた時のタスクリスト

ユビキタス言語辞書の更新がタスクの中にも入っていますね 🎉

パフォーマンスの詳細分析

実際に運用してみると、以下のような効果がありました：

  1. 新規用語の追加時: Claude Codeが「〇〇という用語が定義されていません。新規追加しますか？」と確認してくれる（planのタスクに入っている）
  2. 非推奨用語の検出時: 「Subject（非推奨）→ Target（推奨）に変更する必要があります」と警告
  3. 辞書の自動更新:
    • 非推奨用語テーブルに自動的にSubjectが追加される
    • 状態が🔴（非推奨）として適切にマークされる
    • 代替用語としてTargetが明記される

これ、本当に助かる！手作業でやってたら絶対忘れますし、管理工数もかかりますし！
特に状態管理（🟢/🔴）のおかげで、どの用語が現在推奨されているか一目瞭然になりました。

変更履歴

docs/changelog.md
## 2025-09-16

### Subject → Target への命名変更
- **[非推奨]** Subject（対象者）を非推奨化
  - Target（対象者）に変更
  - より直感的な命名として「Target」を採用
- **[変更]** ファイル名の変更
  - `front/types/subject.types.ts` → `front/types/target.types.ts`
  - `front/services/subject.service.ts` → `front/services/target.service.ts`
  - `front/hooks/useSubjects.ts` → `front/hooks/useTargets.ts`
  - `front/components/subject-management.tsx` → `front/components/target-management.tsx`
  - `front/mocks/subjects.mock.ts` → `front/mocks/targets.mock.ts`
- **[変更]** 型定義・関数名・変数名の変更
  - Subject関連の全ての型、関数、変数をTarget に変更
  - APIエンドポイントも`/subjects`から`/targets`に変更
- **[影響]** フロントエンド約15ファイルに影響
  - バックエンドは現時点でsubject関連の実装なしのため影響なし
- **[注意]** メール件名の「subject」フィールドは変更対象外

うんうん、ちゃんと変更履歴も残せてます！

開発体験編：実際に使ってみてどうだった？ 💭

実際に使ってみた開発体験について書いてみます。

良かった点 ✨

  • 用語の一貫性向上: AI が常に辞書を参照するため、コード全体で統一された用語が使用される
  • 自動的な用語更新: 新しい用語が必要な際、AI が適切にユーザーに確認し、承認後に辞書を更新
  • 言語間の一貫性: フロントエンド と バックエンド で一貫した用語統一が実現

うーん、と思った点 😐

  • AIの記憶力問題: 第2原則なしだと原則を忘れがち

Next Action

  • ビジネスサイドの方々、ステークホルダー方々等との相互的な更新やレビュー
  • Claude code以外のツールを使っている場合のワークフローとルール決め

まとめ：結局ユビキタス言語辞書の自動更新はどうなのか 📊

実際に検証してみた結果をまとめます！

総合評価

ユビキタス言語辞書自動更新システムの総合スコア: 8.5/10点

評価項目 スコア コメント
実装しやすさ 10/10 CLAUDE.mdとMarkdownだけで実装できる！超簡単
開発体験 8/10 AIが賢い相棒になってくれる感じが最高
学習コスト 8/10 DDDの基礎知識があればすぐ理解できる
実用性 9/10 不要やプロンプトやラリーが減る

こんな人におすすめ 👍

  • チームリーダー: 用語統一でチームの生産性を上げたい方
  • AI活用推進者: Claude Codeをもっと賢く使いたい方
株式会社マインディア テックブログ
株式会社マインディア テックブログPublication

株式会社マインディアのテックブログになります。LLMによってエンジニアリングをレバレッジできると考えているので、Gemini, OpenAI, AnthropicなどのメジャーなLLMはもちろん利用中、その他のLLMサービスも申請すれば基本的に通ります。

Discussion