Claude Codeが用語を誤解する理由——AI時代にユビキタス言語が必須になった

「Client」という単語をめぐるインシデントがある。あるプロジェクトでClaude Codeにコードを書かせたところ、生成されたコードのいたるところで「Client」が「個人顧客」として扱われていた。しかしそのプロジェクトにおける「Client」は「法人顧客」を意味すると明確に定義されていた言葉だった。この齟齬がコード全体に波及し、大規模な書き直しが発生した（Zenn・Minedia記事より）。

なぜこうなるのか。Claude Codeは各セッションで文脈を引き継がない。ドメイン辞書を渡されていない状態では、学習データの中で最も高い確率で使われている意味を選ぶ。「Client」の一般的な意味は「個人顧客」だ。プロジェクト固有の定義を知る術がなければ、それ以外の選択肢がない。

翻訳コストがかつての2者間から3者間になった、というのが私の見立てだ。以前はビジネス側とエンジニアの間に「翻訳の壁」が1枚あった。それだけでも十分に厄介だった。そこにAIという第三の翻訳者が加わり、ビジネス↔エンジニア↔AIの3者間で用語が乖離し始めている。辞書を持たないAIは確率的に「最もありそうな解釈」を選び続ける。その解釈がプロジェクトの意図と一致するとは限らない。

DDDが20年以上前に定義した「ユビキタス言語」という概念が、AI時代に入ってまったく別の重要性を帯びている。CLAUDE.mdにドメイン辞書を組み込む具体的な方法と、チームで定着させるロードマップをここでまとめておく。

  1. Claude Codeが「Client」を誤解した日: AIが用語を読み違える3つの実例
    1. 「Client」を個人顧客と解釈した失敗
    2. 「Tool」と「ツール」が同居して起きた広範な不具合
    3. なぜClaude Codeは曖昧な用語を独自解釈するのか
  2. ユビキタス言語とは何か: Eric Evansの定義を2分で
    1. 「コード・会話・ドキュメントすべてに同じ言葉を貫く」原則
    2. Bounded Contextとセットで理解する（Vernonの補正）
  3. なぜAI時代にユビキタス言語の価値が爆増したのか
    1. 翻訳コストが「ビジネス↔エンジニア」から「ビジネス↔エンジニア↔AI」の3者間に
    2. セッションをまたいで忘れるAIには「明文化された辞書」が必要
    3. コンテキストエンジニアリングとしての辞書設計
  4. CLAUDE.mdにドメイン辞書を書く: コピペで使える実装パターン
    1. 第1原則「作業開始時に @docs/ubiquitous-language.md を必ず読む」
    2. ubiquitous-language.md のテーブル設計（ステータス管理付き）
    3. コードへの反映: NG/OKの対比
  5. チームで辞書を作るプロセス: Event Stormingと用語ワークショップ
    1. Event Stormingで用語を「使いながら」発見する
    2. Glossaryの最低限の構成要素
    3. 国内事例: Mackerelのユビ会、SUZURI、LegalOn
  6. 日本語チームの落とし穴: 日本語ドメインと英語コードのギャップ
    1. 「受注」をOrderと訳すとニュアンスが失われる問題
    2. AIに英語名を相談する実践
  7. 形骸化させない: 使われないユビキタス言語7つのアンチパターン
    1. エンジニアだけで決める / 完璧な専門家を求める
    2. DBスキーマ用語がドメイン用語を侵食する
    3. 用語集を作ることが目的化する
  8. EMのための段階導入ロードマップ: Phase 1〜3で組織に根付かせる
    1. Phase 1（1〜2週間）: 既存コードから用語を抽出する
    2. Phase 2（1ヶ月）: コアドメインで初期Glossaryを作る
    3. Phase 3（継続）: PRレビューと週次MTGで文化にする
  9. AI時代のユビキタス言語が担う新しい役割
  10. 参考リンク

Claude Codeが「Client」を誤解した日: AIが用語を読み違える3つの実例

「Client」を個人顧客と解釈した失敗

Minedia（Zenn記事）が報告した事例では、プロジェクト定義で「法人顧客」を指すはずの「Client」が、Claude Codeによって一貫して「個人顧客」として実装された。問題はコードの1箇所にとどまらず、クラス名・変数名・コメント・テスト名にまで波及した。原因は単純だ。CLAUDE.mdにドメイン辞書が存在しなかった。

「Tool」と「ツール」が同居して起きた広範な不具合

NCDC（Zenn記事）が報告した別の事例では、「Tool」と「ツール」の2表記がコードベースに混在していた状態で開発を進めたところ、Claude Codeがこれを区別できず広範な不具合を生み出した。「LLMは何も覚えられない」という前提に立てば当然の結果だが、気づいた時点ですでに多くのコードが生成された後だった。

なぜClaude Codeは曖昧な用語を独自解釈するのか

Claude Codeが用語を「誤解」するのは、AIの能力が低いからではない。用語の文脈が渡されていないからだ。LLMはコード生成における主要なハルシネーションとして「プロジェクトコンテキストとの衝突」を引き起こすことがarXivの研究（2025年）でも指摘されている。ドメイン固有の意味が未定義な状態では、確率的に「最も一般的な解釈」が選ばれる。それがプロジェクトの意図と一致するかどうかは、運次第だ。

ユビキタス言語とは何か: Eric Evansの定義を2分で

「コード・会話・ドキュメントすべてに同じ言葉を貫く」原則

ユビキタス言語（Ubiquitous Language）は、Eric Evansが2003年の著書『Domain-Driven Design』（通称「青本」）で提唱した概念だ。定義はシンプルで力強い。

"To communicate effectively, the code must be based on the same language used to write the requirements—the same language that the developers speak with each other and with domain experts."

コード・要件定義書・会議・チャット・テスト、すべてに同一の言語が貫かれている状態を指す。「ubiquitous（あらゆる場所に存在する）」という語が示す通り、特定の場所だけで使う用語集ではない。

Martin Fowlerは自身のBlogsで補足している。「ユビキタス言語は言語とモデルが共に進化するもの」だと。ドメインエキスパートとの対話の中でその言語を使い続けることが、ドメインモデル自体を鍛える。

Bounded Contextとセットで理解する（Vernonの補正）

重要な誤解を一つ先に払拭しておく。ユビキタス言語は「全社で同じ用語を使う」ことを意味しない。Vaughn Vernonが2013年の著書『Implementing Domain-Driven Design』で明確に示したように、ユビキタス言語はBounded Context（境界づけられたコンテキスト）の内側でのみ「ubiquitous」であればよい。

同じ「在庫アイテム」という言葉が、在庫管理コンテキストでは「棚にある商品」を指し、出荷コンテキストでは「送り出すもの」を意味していても問題ない。コンテキストをまたぐ際に翻訳が必要になるが、その橋渡し役をAnti-Corruption Layer（ACL）と呼ぶ。境界の外側との変換ロジックを専用のレイヤーに閉じ込める設計パターンだ。

なぜAI時代にユビキタス言語の価値が爆増したのか

翻訳コストが「ビジネス↔エンジニア」から「ビジネス↔エンジニア↔AI」の3者間に

ユビキタス言語が長年解決してきたのは「翻訳コストの削減」だ。VMware Tanzuのブログが指摘するように、ビジネス用語とエンジニア用語の間を往復するたびに情報が劣化する。FLINTERS社のブログはこれを「情報が100%→50%→...と劣化していく通信ゲーム」と表現した。

AI時代に加わった新しい問題は、この翻訳コストが3者間になったことだ。人間同士の翻訳コストは以前からあった。しかし今は、その翻訳されたコードをClaude Codeが読み取り、さらに独自解釈を重ねる。ドメイン辞書のないAIは、そのプロセスの最後に「もう一枚のノイズ」を追加する。

セッションをまたいで忘れるAIには「明文化された辞書」が必要

人間のエンジニアは暗黙知として用語の意味を学習し、記憶する。Claude Codeはセッションが変わるたびに文脈をリセットする。つまり、口頭や慣習で共有されてきたドメイン知識はClaude Codeには届かない。AIにとって、明文化されていない知識はアクセスする手段がない。口頭で共有した慣習も、チームの暗黙知も、ファイルに書かれていなければ次のセッションには届かない。

ユビキタス言語の辞書を書くことは、そのまま「チームの暗黙知をAIが読める形に変換する」作業だ。

コンテキストエンジニアリングとしての辞書設計

Anthropicの公式ブログ「Effective context engineering for AI agents」（2025年）は、コンテキストエンジニアリングを「LLM推論時に最適なトークン（情報）を整備する戦略」と定義する。ユビキタス言語の辞書はその中核的なコンポーネントだ。

CLAUDE.mdにドメイン辞書を定義することは「Static Context（静的文脈）」として機能する。毎セッション自動的に読み込まれ、AIに一貫したドメイン知識を供給し続ける。詳しくはコンテキストエンジニアリングの基本「何を入れるか」より「何を入れないか」でも扱っている。

CLAUDE.mdにドメイン辞書を書く: コピペで使える実装パターン

第1原則「作業開始時に @docs/ubiquitous-language.md を必ず読む」

Minediaの実装をベースにした具体的なCLAUDE.md設定を示す。

# CLAUDE.md

## 第1原則: 用語管理
AIは作業開始時に必ず @docs/ubiquitous-language.md を読み込むこと。
コード内の全用語は辞書の定義に従うこと。
新しい用語が必要な場合、既存辞書で代替できないか検討し、
必要であればユーザーに確認の上、辞書に追記してから使用すること。

## 第2原則: 確認の徹底
会話冒頭に原則を画面出力し、AIの「忘れやすさ」に対処する。

この設定により、Planモードで動作させた場合にClaude Codeが自律的にタスクリストへ「辞書更新」を組み込む動作が確認されている（Minedia検証結果より）。

ubiquitous-language.md のテーブル設計（ステータス管理付き）

辞書ファイルはシンプルなMarkdownテーブルで十分だ。ステータスを絵文字で管理することで、議論中の用語と確定済みの用語を即座に区別できる。

# ドメイン用語辞書

| 用語 | 状態 | 定義 | 非推奨の同義語 |
|------|------|------|--------------|
| Client | 🟢現在使用中 | 法人顧客を指す。個人ユーザーは User と呼ぶ | customer, user（Client文脈では使わない） |
| Subject | 🔴非推奨 | Target に移行済み | — |
| Target | 🟢現在使用中 | 調査対象の法人を指す | Subject（非推奨） |
| Feature Flag | 🟡議論中 | フィーチャーフラグ。Toggle と統合予定 | toggle, flag |

「✅ Do」と「❌ Don't」を同じ行に入れることで、Claude Codeが辞書を参照した際に「使ってよい言葉」と「使ってはいけない言葉」を同時に把握できる。

コードへの反映: NG/OKの対比

ユビキタス言語はコードに直接反映される。下記はPythonでの対比例だ。

# NG: 技術用語でコードを書く（ドメイン語が失われている）
class ItemList:
    def add(self, item):
        ...
    def submit(self):
        ...

# OK: ユビキタス言語でコードを書く
class ShoppingCart:
    def add_product(self, product):
        ...
    def checkout(self):
        ...

checkout() という動詞は、ユーザーストーリー・設計会議・コードで同じ言葉が使われる。Claude Codeがこのコードを読んだとき、辞書に ShoppingCart の定義があれば文脈を正確に保てる。翻訳レイヤーが消える。

CLAUDE.mdの書き方全般についてはCLAUDE.mdを使い倒すフィードバックループの作り方も参照してほしい。

チームで辞書を作るプロセス: Event Stormingと用語ワークショップ

Event Stormingで用語を「使いながら」発見する

用語集を座って考えるだけでは限界がある。Alberto Brandoliniが考案したEvent Stormingは、付箋を使って時系列でドメインイベントを洗い出すことで、参加者全員が用語を「使いながら」定義していくワークショップ手法だ。

オレンジ付箋でドメインイベント（「注文が完了された」）、青付箋でコマンド（「注文を完了する」）を書いていくプロセスで、自然とユビキタス言語の候補が浮かび上がる。議論の中で「注文を完了する」と「注文を確定する」のどちらが正確か問うことで、チームの暗黙知が言語化される。

Glossaryの最低限の構成要素

Tokium・SUZURI（ペパボ）・LegalOn Technologiesなど複数の国内企業の実践から浮かび上がる構成要素がある。

項目内容
正式名称使うべき用語
非推奨名称使ってはいけない同義語・誤用
ソースコード上の名称クラス名・変数名との対応
ステータス議論中 / 確定 / 非推奨
定義・備考意味の説明、使用文脈

TokiumはGitHub Actionsでプルリクエストのdiffに対して辞書の記載漏れを自動検出するCLIツールを開発しており、2ヶ月で100件の用語が蓄積された。辞書をCIに組み込んでおけば、PRを出すたびに確認が走る。「辞書が腐る」前に気づける仕組みだ。

国内事例: Mackerelのユビ会、SUZURI、LegalOn

Mackerelチーム（はてな）は2019年から「ユビキタス言語を決める会」（ユビ会）を隔週で開催している。4名・1時間・Google Hangoutsという小さな取り組みが、6年以上継続してチームの用語文化を形成した。

SUZURI（ペパボ）はNotionでGlossaryを管理し、デザイナー主導で始まった取り組みが開発組織全体に波及した事例として参考になる。

LegalOn Technologiesは2025年2月の記事で、「フィーチャーフラグ」から「Toggle」への用語移行プロセスを詳細に記録した。用語変更がコードベースにどう波及するか、追跡の具体的な手順が書かれていて参考になる。

日本語チームの落とし穴: 日本語ドメインと英語コードのギャップ

「受注」をOrderと訳すとニュアンスが失われる問題

日本語話者チームが直面する固有の課題がある。ビジネス用語は日本語（「受注」「在庫引当」「支払督促」）だが、コードは英語が慣習だ。翻訳のたびに認知コストが発生し、「英語版ユビキタス言語」と「日本語版」の2つが暗黙的に生まれる。

GitHub Issue（little-hands/ddd-q-and-a）での議論が参考になる。現実的な解決策は「日英対応表をGlossaryに並列で管理する」ことだ。受注 → Order という対応を明記しておくことで、どちらの言語で会話していてもドメインの意図が保たれる。

AIに英語名を相談する実践

CADDiが2026年5月に公開したアンチパターン集では、「AIに相談せず英語名を決める」ことをアンチパターン#4として挙げている。

不自然な和製英語がコードに入り込むことを防ぐために、「ChatGPTやClaude Codeに英語候補を複数生成させ、業界で実際に使われている用語かを確認する」プロセスを推奨している。英語が母語でない日本語話者が英語コードを書く、その課題への回答として腑に落ちた。

形骸化させない: 使われないユビキタス言語7つのアンチパターン

CADDiが2026年5月に公開した「使われないユビキタス言語はなぜ生まれるのか」は、実践から積み上げたアンチパターン集だ。7つのアンチパターンのうち、特にチームで踏みやすい3つを取り上げる。

エンジニアだけで決める / 完璧な専門家を求める

PMやデザイナーなど「顧客言語」を持つ人が不在のまま用語を決めると、実装寄りの技術用語になる。一方で「完璧なドメインエキスパート」を待ち続けると永遠に始められない。現実的な代替者（PdMや業務担当者）を活用して始める。

DBスキーマ用語がドメイン用語を侵食する

テーブル名: t_user_mst, t_order_detail
↓
クラス名: UserMst, OrderDetail
↓
会話: 「ユーザーマスタのオーダーディテールって何？」

「マスタ」「ディテール」「フラグ」はデータベース設計の概念であり、ドメイン概念ではない。これらがコードに定着し始めると、ビジネス側との会話でも使われ始め、本来のドメイン用語が失われていく。

用語集を作ることが目的化する

Leaner Technologiesの事例が率直に指摘しているように、用語集を完成させても誰も日常的に参照しなければ意味がない。辞書を頻繁にアクセスされる場所（GitHubリポジトリやNotion）に置き、PRレビューで「Glossaryにない用語が使われていないか」をチェックする文化が不可欠だ。

仕様駆動開発（SDD）でClaude Codeに正しく仕様を渡す実践では、ドメイン辞書を仕様書と組み合わせる方法も紹介している。

EMのための段階導入ロードマップ: Phase 1〜3で組織に根付かせる

Phase 1（1〜2週間）: 既存コードから用語を抽出する

最初のアクションは「棚卸し」だ。既存コードで使われているドメイン用語をClaude Codeに抽出させることができる。arXivの研究（2025年）では、LLMに「このコードベースから使われているドメイン用語を抽出してGlossaryを生成せよ」という指示を与えると高精度で実行可能と報告されている。

コードベースの読み解き方についてはClaude Codeで未知のコードベースを48時間で読み解く方法も参考になる。

チーム内で「これどういう意味？」と聞かれる用語をリストアップするだけでも、最初の棚卸しとして十分だ。

Phase 2（1ヶ月）: コアドメインで初期Glossaryを作る

プロジェクト全体ではなく、最重要機能のドメインに絞ってGlossaryを作る。エンジニア・PdM・デザイナーが集まるEvent Stormingを1回実施し、Notion・GitHubなどにGlossaryファイルを作成する。

その段階でCLAUDE.mdに @docs/ubiquitous-language.md の参照を追加する。次のセッションからClaude Codeは辞書を読んだ状態で動き出す。

Phase 3（継続）: PRレビューと週次MTGで文化にする

Glossaryを生き続けさせるには、日常の作業に組み込むしかない。PRレビュー時に「Glossaryと用語が一致しているか」を確認する習慣をつけることと、週次MTGで「新しく生まれた用語があれば共有」するルーティンを持つことだ。

Mackerelのユビ会モデルが示すように、4名・隔週・1時間という小さな取り組みで十分だ。「用語の警察」にならず、使い続けることで自然に定着させることを目標にする。

オンボーディングの観点では新入りエンジニアを3日で戦力化するClaude CodeオンボーディングでGlossaryを活用するパターンも紹介している。

AI時代のユビキタス言語が担う新しい役割

ユビキタス言語が定義されたドメインモデルは、今や2つの役割を同時に担っている。

ひとつは従来からの役割、人間チーム間の共通言語だ。そこにAI時代が新しい役割を加えた。AIエージェントへの仕様書としての機能だ。

TypeScriptエデュケーターのMatt Pocockが公開した .claude ディレクトリのリポジトリ（GitHub: mattpocock/skills）は135,000以上のスターを集めている（2026年6月時点）。そこに含まれていたubiquitous-languageスキルの説明には「会話からDDDスタイルのユビキタス言語Glossaryを抽出し、UBIQUITOUS_LANGUAGE.mdに保存する」とある。AIエージェント自身が用語の一貫性を保つための自己組織化ツールを求めている。

コミュニティはすでに、ユビキタス言語をAIへの「給餌」として捉え始めている。あなたのプロジェクトの ubiquitous-language.md は、今いくつのドメイン用語を定義しているか。

参考リンク

コメント

タイトルとURLをコピーしました