CLAUDE.md（クロード・エムディー）とは？Claude Codeを賢くする設定ファイルの書き方・配置・活用法を完全解説

CLAUDE.mdとは

CLAUDE.md（クロード・エムディー）とは、Anthropic社のClaude Codeが起動時に自動的に読み込み、システムプロンプトの一部として扱うMarkdown形式の設定ファイルである。プロジェクトごとに置けるため、コードベース固有のビルドコマンド、コーディング規約、テスト方法、注意点などをClaudeに「永続的に覚えさせる」ことができる。

身近な例えで言うと、CLAUDE.mdは新人エンジニアが最初に渡される「社内ルールブック」のようなものだ。毎回口頭で説明する代わりに、ルールを文書化しておけば、新しいセッションが始まるたびにClaudeがそれを読んで作業に活かしてくれる。実務では、TypeScript版のlinterルール、テスト用のmockファイルの場所、API認証の儀式など、初見では気付きにくい知識をここに集約する。

CLAUDE.mdの読み方

CLAUDE.mdの仕組み

Claude Codeは起動時に、カレントディレクトリから親ディレクトリへとさかのぼってCLAUDE.mdファイルを探索し、見つかったすべてを順番にコンテキストへ読み込む。これは「階層的読み込み」と呼ばれる仕組みで、ユーザー全体に効くグローバル設定とプロジェクト固有設定を分離して管理できるよう設計されている。重要なポイントですが、Claudeはこの内容を「ユーザーが書いた指示」と同等の重みで扱うため、書きぶりがそのまま挙動に反映されます。

読み込みの優先順位

下層のCLAUDE.mdほど後から読み込まれ、より具体的な指示として上書きされる。重要な点は、Claude Codeはこのファイルを「ユーザーが書いた指示」と同等の重みで扱うことだ。曖昧な書き方をすると、Claudeが意図を取り違える可能性がある。実務では、複数の階層を併用するのが一般的で、共通設定は ~/.claude/CLAUDE.md、リポジトリ全体のルールは root の CLAUDE.md、サブシステム固有の規約はそれぞれのディレクトリに置く運用が多い。

歴史的背景

CLAUDE.mdが導入された背景には、コーディングエージェントの「文脈喪失」問題がある。LLMはセッションごとに記憶がリセットされるため、毎回同じ前提条件（このプロジェクトはTypeScriptで書かれている、テストはvitestで実行する、など）を説明する必要があった。CLAUDE.mdはこの煩わしさを解消するために生まれた、いわば「永続記憶のためのインタフェース」である。注意しておきたいのは、CLAUDE.mdが取り扱うのは「常識化されたチームルール」であり、特定のタスクごとの指示はチャット内に書くのが筋という整理である。

CLAUDE.mdの使い方・実例

基本的な使い方（Quick Start）

プロジェクトのルートディレクトリに CLAUDE.md を作成し、Claudeに覚えてほしい情報を書く。最小例は次のとおり。

# プロジェクト概要
Next.js 14（App Router）+ TypeScript + Tailwind CSSで書かれたECサイト。

# ビルド・テスト
- 開発: `npm run dev`
- 本番ビルド: `npm run build`
- テスト: `npm run test` (Vitest)
- リント: `npm run lint` (ESLint + Prettier)

# コーディング規約
- 関数コンポーネントのみ使用。クラスコンポーネントは禁止
- 状態管理はZustand。Reduxは使わない
- API呼び出しは `lib/api/` 以下に集約

よくある実装パターン

パターンA: コマンド辞書型

# プロジェクトでよく使うコマンド
- DB マイグレーション: `pnpm db:migrate`
- 型生成: `pnpm typegen`
- 開発サーバー: `pnpm dev`

向いているケース: モノレポやマイクロサービスなど、コマンドが多くて覚えきれない大規模プロジェクト。

避けるべきケース: コマンドが3〜4個しかない単純なプロジェクト。冗長になる。

パターンB: 設計判断（ADR）リンク型

# 設計判断
- 認証: Clerkを採用（[ADR-002](docs/adr/002-auth.md)）
- データベース: PlanetScaleではなくSupabaseを採用（[ADR-005](docs/adr/005-db.md)）
- 状態管理: Zustand（[ADR-008](docs/adr/008-state.md)）

これらの決定の背景は各ADRを参照。**変更時は必ずADRを更新すること**。

向いているケース: チーム開発で重要な設計決定が複数あり、後から「なぜこう決めたのか」を辿りたい場合。

避けるべきケース: 個人開発の小さなプロジェクト。ADRを書くオーバーヘッドが大きすぎる。

パターンC: アンチパターン警告型

# してはいけないこと
- `any` 型の使用（unknownを使い、型ガードで絞り込むこと）
- `console.log` を本番コードに残すこと（debugライブラリを使う）
- `process.env.SECRET` をクライアント側で参照すること

向いているケース: 過去に同じミスを繰り返したくない場合。Claude Codeが事前に避けてくれる。

避けるべきケース: ルールが曖昧で「ケースバイケース」と書きたくなる場合。曖昧な指示はかえって混乱を招く。

アンチパターン: 何でも詰め込みすぎ

# 絶対NG（CLAUDE.mdが膨大になりすぎ）
<3000行のコードベースの全関数の説明>
<全ライブラリの使い方マニュアル>
<社内Wiki全体のコピペ>

CLAUDE.mdに書いた内容は毎セッションでコンテキストウィンドウを消費するため、巨大化させると本来のコードを読む余地が減ってしまう。経験則として、CLAUDE.mdは200〜500行に収めるのが望ましい。長くなる場合は docs/ 配下に分割し、CLAUDE.mdから「詳細はXXX.mdを参照」とリンクで案内するほうが効率的だ。

機密情報の取り扱い

注意点として、APIキー、データベース接続文字列、社内システムの脆弱性情報などはCLAUDE.mdに書いてはいけない。CLAUDE.mdはGitリポジトリにコミットされるのが一般的で、書いた瞬間に誰でも読める状態になる。秘密情報は .env や Secret Manager で管理し、CLAUDE.mdには「環境変数 DATABASE_URL を使う」とだけ書く。覚えておきたいのは、CLAUDE.mdは「公開されることを前提に書く」というスタンスです。

CLAUDE.mdのメリット・デメリット

メリット

• セッション間の文脈共有: 「このプロジェクトはどう動くのか」を毎回説明し直す必要がない
• チーム標準化: 全員が同じルールでClaudeを使える。新人オンボーディングも兼ねる
• バージョン管理: GitでCLAUDE.mdの履歴を追えるため、ルールがいつ変わったか可視化できる
• 意思決定の透明化: 「なぜこの設計にしたか」を残せる
• /clearで消えない: /clearコマンドで会話履歴を消しても、CLAUDE.mdは次セッションでも読み込まれる

デメリット

• コンテキスト消費: 内容に比例してトークンを消費する。長すぎるとコード読解の余地が減る
• 陳腐化リスク: コードベースの変更にCLAUDE.mdが追随していないと、誤情報をClaudeに伝えてしまう
• 過度な依存: ルールを細かく書きすぎると、Claudeが創造的な提案をしにくくなる
• 機密情報漏洩リスク: 公開リポジトリにうっかり機密を書くと露出する

CLAUDE.mdとREADME.md・.cursorrulesの違い

初学者がよく混同するのが、プロジェクトに置く「指示系ファイル」の使い分けだ。READMEは人間向け、CLAUDE.mdはClaude向け、Cursor用の .cursorrules はCursor向けと、それぞれ対象が異なる。下記の比較表で整理する。

つまり、CLAUDE.mdは「Claude専用の社内マニュアル」、READMEは「外部公開する案内文」、.cursorrulesは「Cursor用の社内マニュアル」と覚えれば混乱しない。三者は併存可能で、内容の重複も問題ない。

CLAUDE.mdに関するよくある誤解

誤解1: 「CLAUDE.mdに書けばClaudeが100%守ってくれる」

なぜそう誤解されるのか: CLAUDE.mdが「設定ファイル」と呼ばれるため、プログラム的なコンフィグ（true/falseで挙動が決まる）と同じ感覚で捉える人が多い。また、Anthropic公式が「Claudeが自動的に読む」と表現するため、強制力があるように見える。実際にはLLMの応答は確率的で、コンテキスト全体から最適な振る舞いを選ぶ仕組みだ。

正しい理解: CLAUDE.mdの内容はあくまで「システムプロンプトの一部」として渡されるだけで、Claudeはコンテキスト全体から最適な行動を選ぶ。100%守られるわけではなく、ユーザーの指示と矛盾した場合はユーザー指示が優先されることもある。重要なルールは複数回・複数箇所に書くと守られやすい。

誤解2: 「.claudeフォルダのCLAUDE.mdとプロジェクトrootのCLAUDE.mdは別物」

なぜそう誤解されるのか: ~/.claude/CLAUDE.md と ./CLAUDE.md という2つの場所があり、命名が似ていながら配置が違うため混乱する。Claudeのドキュメントでも両者の説明が分散しているケースが多く、片方しか知らないユーザーが「もう一方は別の機能」と推測してしまう背景がある。

正しい理解: ファイル形式は同じで、Claude Codeは両方を読み込む。違いは「適用範囲」だけだ。~/.claude/CLAUDE.mdはホームディレクトリにあるのですべてのプロジェクトで読まれ、./CLAUDE.mdは今いるプロジェクトでだけ読まれる。両方に同じ指示があった場合、プロジェクト側が後から読み込まれ、より優先される。

誤解3: 「CLAUDE.mdは長いほどClaudeが賢くなる」

なぜそう誤解されるのか: 「指示が多い＝Claudeが頑張る」というイメージは、人間相手のドキュメントの感覚を引きずっている結果だ。READMEなら詳しく書くほど親切とされるため、CLAUDE.mdも同じ感覚で扱ってしまう。実際にはトークン経済（コンテキストウィンドウの制限）が存在することを意識しない人が多い。

正しい理解: CLAUDE.mdは入力トークンを消費するため、長すぎると逆効果だ。本来コードを読むのに使うべきトークンが、設定ファイルで埋まってしまう。Anthropicも公式ブログで「簡潔に、必要なものだけ書く」ことを推奨している。300行を超えたら分割を検討すべきだ。

CLAUDE.mdの実務での活用シーン

• レガシーコードの引き継ぎ: 過去のコードベースを引き継ぐ際、独自のクセ（命名規則、deprecated APIの存在など）をCLAUDE.mdに書けば、Claudeが事前に把握した状態で作業を始められる
• マイクロサービスのモノレポ: 各サービスのサブディレクトリにCLAUDE.mdを置き、サービスごとの違い（言語、フレームワーク、デプロイ先）を記述できる
• OSSコントリビュート: 公開OSSのリポジトリでも、メンテナがCLAUDE.mdを置けば、PR提出者がClaude Codeを使う際の品質を底上げできる
• 新人オンボーディング: 入社直後のエンジニアがCLAUDE.mdを読むだけでチームのコーディング規約を素早くキャッチアップできる
• 規制対応プロジェクト: 金融・医療など規制業界では、生成コードに含めてはいけない関数や、必須のロギングルールをCLAUDE.mdで明文化することで、Claude経由のコード生成でも規約違反を防げる

CLAUDE.mdに関するよくある質問（FAQ）

まとめ

• CLAUDE.mdはClaude Codeが起動時に読むMarkdown設定ファイル。コードベース固有の知識をClaudeに永続化させる
• 配置場所は ~/.claude/CLAUDE.md（全プロジェクト共通）と各プロジェクトroot（プロジェクト固有）の2階層
• 記述内容はビルドコマンド・コーディング規約・注意点が中心。200〜500行が目安
• READMEやLLMプロンプトと違い、Claude Codeのシステムプロンプトに直接結合される
• 機密情報は絶対に書かない。Gitにコミットされる前提で記述する
• CLAUDE.mdが空でも動作するが、書き込むほどClaudeの精度・一貫性が向上する

参考文献・出典