Claude Codeのドメイン用語集をCLAUDE.mdに置く — 業務用語とコード名の対応表

業務の言葉とコード上の名前がずれているリポジトリでは、Claudeに「解約の処理を直して」と頼んでも、どのファイルを見ればよいかを毎回探させることになります。対策は、業務用語とクラス名・テーブル名の対応表をCLAUDE.mdから読める場所に置くことです。

この記事では、対応表に載せる語の選び方、grepで候補を拾う手順、docs/glossary.mdに置いて@で読み込ませる書き方、古くなったときの検出までを順に説明します。例に使うのは、定期購入サービスを想定した架空のリポジトリです。

用語集はCLAUDE.mdに書くべきものか

公式のベストプラクティスは、CLAUDE.mdに「コードを読んでも分からないこと」だけを書くよう求めています。具体的には、コードが紛らわしい箇所、リポジトリに残っていない決定事項、2回訂正したことのある内容です。逆に、アーキテクチャやファイル配置の説明は「Claudeがリポジトリ自体を読むので書かなくてよい」側に分類されています。

ここで用語集が分かれます。クラスの一覧やディレクトリ構成を写した用語集は、後者に当たるので載せる意味がありません。一方、業務の言葉とコードの名前が一対一で対応しない部分は、コードだけ見ても分からない情報です。

• 画面では「顧客」と呼ぶのに、コードではAccountになっている
• 「解約」と「休止」が、同じstatusカラムの別の値で表されている
• 同じCustomerが、自社と決済事業者で別の意味を持っている

この種のずれは、新しく入ったメンバーが最初に質問する部分でもあります。「新しいチームメンバーが生産的になるのに同じ文脈を必要とする」状況は、CLAUDE.mdに足す合図の1つです。人間向けの用語集とClaude向けの用語集を別々に作る必要はなく、1枚を両方で使えます。

載せる語は3種類に絞る

全クラス名を載せると200行をすぐ超えます。CLAUDE.mdは1ファイル200行未満が目安で、長いファイルはコンテキストを多く消費し、指示が守られにくくなります。載せる基準は、次の3種類のどれかに当てはまるかどうかです。

「出荷」をShipmentと書くような、辞書を引けば分かる対応は外します。Claudeが名前から推測できるからです。迷ったら、新メンバーが質問した語、レビューで名前の取り違えを指摘された語から始めるのが現実的です。

grepで「業務用語がコード上でどの名前か」を拾う

対応表の元データは、人間が用語を挙げ、Claudeにコード上の名前を探させる分担で作ります。業務用語の意味はコードに書かれていないので、語のリストは仕様書や問い合わせ履歴から人が用意します。コード側の探索は、grepが得意な仕事です。

探す順番は、画面文言、モデルやクラス、DBカラム、APIの項目名の順が拾いやすくなります。画面文言がロケールファイルに入っているプロジェクトなら、日本語の語から翻訳キーを経由して、実装の名前にたどり着けます。

# 「解約」を含む行を、日本語と英語の候補でまとめて探す
git grep -n -i -E '解約|cancel|terminate'
 
# ファイルごとのヒット数が多い順に並べ、中心になる場所を見つける
git grep -c -i -E 'cancel|terminate' \
  | sort -t: -k2 -nr | head

この操作自体はClaude Codeにそのまま頼めます。そのときは、推測を禁じる一文を必ず添えます。次の依頼文は、1回のセッションで複数の語をまとめて調べさせる例です。

次の業務用語がコード上でどの名前になっているか調べて、
docs/glossary.md の表に追記してください。
用語: 解約、休止、出荷
 
- 画面文言、モデル名、DBカラム、APIの項目名の順に git grep で探す
- 見つけた場所はファイルパスで書く
- 同じ語が別の意味で使われている箇所と、旧名が残っている箇所は
  「注意」欄に書く
- コードから意味を判断できないものは推測せず「要確認」と書く

「要確認」の指示を入れないと、名前の近さだけで対応を決めてしまうことがあります。返ってきた表は、そのまま信じず、業務を知っている人が目を通してからコミットします。

docs/glossary.mdの書き方

対応表は、列を4つに抑えると読みやすくなります。次は、架空の定期購入サービスを想定した例です。

# ドメイン用語集
 
<!-- 追加するときは、新メンバーが質問した語を優先する -->
 
| 業務用語 | コード上の名前 | 場所 | 注意 |
|---|---|---|---|
| 顧客 | `Account` | `app/models/account.rb` | `Customer` は決済事業者側のIDを持つ別クラス |
| 定期便 | `Subscription` | `app/models/subscription.rb` | APIのパスは `/subscriptions` |
| 解約 | `cancel` | `Subscription` の `cancel` メソッド | `terminate` は運営都合の強制終了 |
| 休止 | `paused_at` | `subscriptions` テーブル | 解約ではない。`status` は変えない |
| 発送 | `Dispatch` | `lib/legacy/dispatch.rb` | 旧名。新しいコードは `Shipment` を使う |

識別子は1つずつバッククォートで囲んでおきます。後で説明する検査スクリプトが、バッククォート内の文字列を取り出して照合するためです。

コメントは<!-- -->で書けます。CLAUDE.mdのブロックレベルのHTMLコメントは、コンテキストに注入される前に取り除かれます。人間の保守者向けの注意書きがトークンを消費しません。

CLAUDE.mdから@importで読ませる

用語集は別ファイルに置き、CLAUDE.mdの側から@で参照します。

# 用語
 
業務用語とコード上の名前の対応は @docs/glossary.md を参照する。
新しい機能を実装する前に、依頼文の業務用語がこの表にあるか確認する。

読み込みの挙動は、次の点を押さえておけば足ります。

• 相対パスは、importを書いたファイルからの相対で解決される
• importしたファイルがさらにimportする再帰は、最大4段まで
• バッククォートやコードブロックの中の@はimportとして扱われない。パスを文字として書きたいときは囲む

そのため、用語集が数十行を超えたら置き場所を見直します。

用語集が長くなったら、領域ごとに分けて必要なときだけ読ませる

請求まわりの語は請求のコードを触るときにだけ必要、というように領域が分かれるなら、.claude/rules/にパス指定付きで置けます。pathsのfrontmatterがあるrulesファイルは、一致するファイルをClaudeが読んだ時点で読み込まれます。pathsのないrulesファイルは、importと同じく起動時に読み込まれます。必要なときだけ読ませられるのはpaths付きのrulesだけです。

---
paths:
  - "app/billing/**/*"
  - "lib/payments/**/*"
---
 
# 請求まわりの用語
 
| 業務用語 | コード上の名前 | 注意 |
|---|---|---|
| 請求確定 | `Invoice#finalize` | 取り消せない。訂正は `credit_note` を発行する |
| 与信 | `Authorization` | 売上計上とは別。キャプチャ前の状態 |

全体で共通する語はCLAUDE.mdからのimportに、領域限定の語はrulesに、と分ける形です。サブディレクトリのCLAUDE.mdに置く方法もありますが、あとから読み込まれるファイルには文字数の上限が掛かります。200Kコンテキストなら40,000文字で、超えると先頭部分だけがClaudeに渡されます。詳細はCLAUDE.mdが途中までしか読まれない上限と確認法にあります。

古くなった用語集を検出する

用語集は、コードをリネームした日から嘘をつき始めます。Claudeは対応表を信じて、存在しない名前をgrepする可能性があります。そこで、表に書いた名前がまだコードにあるかを機械的に調べるスクリプトを置きます。

# scripts/check-glossary.sh
grep -o '`[^`]*`' docs/glossary.md | tr -d '`' | sort -u \
  | while read -r name; do
    [ -e "$name" ] && continue
    git grep -q -F -e "$name" -- . ':!docs/glossary.md' \
      || echo "見つからない: $name"
  done

このスクリプトは、消えた名前を見つけるだけです。名前が残ったまま意味が変わった場合は検出できないので、レビュー時に用語集の差分を一緒に見る運用と組み合わせます。

CLAUDE.mdの記述の古さを調べる仕組みもあります。/doctor prompt-auditは、存在しないファイルを指す記述や、ファイル同士の矛盾を拾い、修正案を提示します。適用はユーザーが頼むまで行われません。v2.1.283以降の機能です。ただし、これが見るのは指示ファイルの書き方や参照先の実在で、用語の対応が現在のコードと合っているかまでは見ません。上のスクリプトとは役割が違います。

新メンバーの質問を用語集に還流させる

入れる語を決める一番確かな方法は、質問を拾うことです。同じ訂正を前回のセッションでも入力したときや、新しいメンバーに同じ文脈が必要なときは、CLAUDE.mdに足す合図になります。

• 新メンバーが「決済保留って何ですか」と聞いたら、答えを口頭で返さず用語集に1行足す
• 足した後、Claudeにその語を含む依頼をして、正しいファイルを開くか確かめる
• 開かなかった場合は、名前の候補が足りないか、注意欄が曖昧なので書き直す

質問が減るかどうかは、用語集の網羅性より、更新が質問のたびに行われるかで決まります。

オンボーディング資料そのものをClaudeに作らせたい場合は、/team-onboardingコマンドが別の手段です。そちらは直近の利用履歴から資料を生成するもので、業務用語の対応表を作るものではありません。

用語集に頼りすぎないための線引き

用語集は、CLAUDE.mdの指示の1つに過ぎません。CLAUDE.mdの内容はコンテキストとして渡されるだけで、強制される設定ではありません。次の使い分けを意識すると失敗が減ります。

公式のベストプラクティスも、例外のない規則はCLAUDE.mdではなくhookや拒否ルールに移すよう勧めています。「旧名のDispatchは新規コードで使わない」を例外なしにしたいなら、用語集の注意欄に書くだけでなく、編集後に旧名をgrepするhookも検討できます。実装はClaude CodeでValeを回すのhookと同じ型です。

まとめ

用語集に載せるのは、業務の言葉とコードの名前がずれている語だけです。ずれを拾うのはgrepとClaudeに任せ、意味の確認は業務を知る人が行います。置き場所は、共通ならCLAUDE.mdからのimport、領域限定ならパス指定のrulesで、importではコンテキストが減らないことを覚えておく必要があります。

運用の核は更新です。質問が出たら1行足し、リネームしたら検査スクリプトで見つけます。すでにCLAUDE.mdが育っているなら、先にclaude-md-managementプラグインで全体を棚卸ししてから、用語集を切り出すと行数を抑えやすくなります。担当者の交代で運用手順も渡すなら、社内ツールの引き継ぎ資料をコードとgit履歴から作る手順が参考になります。