CLAUDE.mdとは？Claude Codeのプロジェクト設定ファイル完全解説

CLAUDE.mdとは何か——Claude Codeの「記憶」を支えるファイル

Claude Codeを使い始めると、毎回同じことを説明する必要がある——プロジェクトの構造、コーディング規約、使っているライブラリ。この「毎回説明する手間」を解消するのがCLAUDE.mdです。

CLAUDE.mdは、Claude Codeがセッション開始時に自動で読み込むプロジェクト設定ファイルです。マークダウン形式で書かれたこのファイルに、プロジェクトの情報やルールを記述しておくと、Claude Codeはそれを「前提知識」として持った状態で作業を開始します。

一言で言えば、新しく入ったメンバーに渡すオンボーディング資料のようなものです。ただし読むのはAIなので、人間向けの冗長な説明は不要。簡潔に、正確に書くことが重要です。

CLAUDE.mdの基本的な仕組み

CLAUDE.mdは特別なフォーマットや設定は不要で、プロジェクトのルートディレクトリにCLAUDE.mdというファイルを置くだけで機能します。

セッション開始時に自動で読み込まれる

Claude Codeを起動すると、カレントディレクトリから上位ディレクトリに向かってCLAUDE.mdを検索し、見つかったものをすべて読み込みます。設定ファイルをインポートする記述や、特別なコマンドは必要ありません。

マークダウン形式で自由に書ける

YAMLやJSONのような厳密な構文規則はなく、普通のマークダウンで書けます。見出し、箇条書き、コードブロックなど、読みやすい形式であれば何でも使えます。

/initコマンドで自動生成できる

白紙から書く必要はありません。Claude Codeで/initコマンドを実行すると、プロジェクトの構成（package.json、設定ファイル、ディレクトリ構造など）を解析して、CLAUDE.mdの初期版を自動生成してくれます。これをベースにカスタマイズするのが効率的です。

CLAUDE.mdの4つの階層

CLAUDE.mdには4つの階層があり、スコープの広さが異なります。これを理解すると、設定の使い分けが明確になります。

1. ユーザーレベル（~/.claude/CLAUDE.md）

ホームディレクトリの.claude/配下に置くCLAUDE.mdは、すべてのプロジェクトに共通で適用されます。たとえば「日本語で回答する」「コミットメッセージは日本語で書く」など、個人の好みに関するルールを書く場所です。

2. プロジェクトルート（./CLAUDE.md）

最も一般的な配置場所です。プロジェクトのルートに置き、チーム全体で共有します。Gitにコミットすることで、チームメンバー全員が同じコンテキストでClaude Codeを使えます。

3. ディレクトリ別（./backend/CLAUDE.md など）

サブディレクトリに置くCLAUDE.mdは、Claude Codeがそのディレクトリのファイルにアクセスしたときにオンデマンドで読み込まれます。モノレポ構成でフロントエンドとバックエンドの規約が異なる場合などに有効です。

4. ローカルオーバーライド（./CLAUDE.local.md）

.local.mdはgitignore対象の個人設定です。「自分だけ使うMCPサーバーの情報」「自分のローカル環境固有のパス」など、チームに共有する必要のない設定を書きます。

これらは上位から順に読み込まれ、より具体的な階層の記述が優先されます。ユーザーレベルで「英語で回答」と書いていても、プロジェクトルートで「日本語で回答」と書けばプロジェクト内では日本語になります。

.claude/ディレクトリとの関係

CLAUDE.mdと合わせて理解しておくべきなのが、.claude/ディレクトリです。これはClaude Codeのプロジェクト設定を格納するフォルダで、CLAUDE.mdと役割が異なります。

.claude/rules/ — モジュール化されたルール

CLAUDE.mdに全ルールを詰め込むと長くなりすぎます。.claude/rules/には、関心事ごとに分割したルールファイル（.md形式）を配置できます。「コーディング規約」「記事の書き方」「セキュリティルール」など、1ファイル1テーマで管理するのが推奨パターンです。

私の運用では、CLAUDE.mdにはプロジェクトの全体像と構成だけを書き、具体的なルールはすべて.claude/rules/に分割しています。CLAUDE.mdが100行を超えたら、分割を検討するサインです。

.claude/commands/ — カスタムスラッシュコマンド

.claude/commands/にマークダウンファイルを置くと、独自のスラッシュコマンドを定義できます。たとえばdeploy.mdを置けば、/deployでデプロイ手順をClaude Codeに実行させられます。

.claude/skills/ — 自動実行されるワークフロー

Skillsは、SKILL.mdに定義した条件に合致するタスクを受けたとき、Claude Codeが自動的に読み込んで実行するワークフローです。「SEO記事を書いて」と言うだけで、キーワード調査→執筆→画像生成→CMS投稿まで一気に実行する——この記事自体もSkillを使って書かれています。

.claude/settings.json — 権限と動作設定

Permissions（allow/deny）やHooksの設定を記述するJSONファイルです。CLAUDE.mdが「何をすべきか」を伝えるのに対し、settings.jsonは「何をしてよいか」を制御します。

CLAUDE.mdに書くべきこと・書くべきでないこと

CLAUDE.mdの効果を最大化するには、何を書くかと同時に何を書かないかが重要です。

書くべきこと

プロジェクトの概要: 1〜2行で何のプロジェクトかを説明（「Next.js App Router製のコーポレートサイト」など）
ビルド・テスト・実行コマンド: npm run dev、npm run test、npm run buildなど
ディレクトリ構造: 主要なディレクトリと役割の一覧
コーディング規約のポイント: 言語・フレームワーク固有の方針（「サーバーコンポーネントをデフォルトとする」等）
やってはいけないこと: 禁止事項は明確に書く（「.envファイルをコミットしない」「本番DBに直接アクセスしない」等）

書くべきでないこと

コードを読めばわかること: ファイル内のインポート順序やインデント幅など、既存コードから推測できる規約
長い説明文や背景情報: CLAUDE.mdは簡潔であるほど効果的。長い説明が必要なら別ファイルに分割し、CLAUDE.mdからはパスだけ記述
頻繁に変わる情報: 現在のスプリントの内容や一時的なタスクリスト
Claude Codeがデフォルトでやること: 正しく動作している挙動をわざわざ記述すると、ファイルが無駄に長くなる

Anthropicの公式ドキュメントでも「CLAUDE.mdは短いほど良い」と明記されています。重要なルールが他の記述に埋もれないことが最も大切です。

実運用での目安

私の場合、CLAUDE.mdは50〜80行程度に収め、詳細ルールは.claude/rules/に4〜5ファイル配置しています。最初は「あれもこれも」と書きたくなりますが、数週間運用すると「Claude Codeが既にわかっていること」と「明示的に伝えないとズレること」の区別がつくようになります。

定期的に/initを実行して現状のCLAUDE.mdと比較し、不要な記述を削除するメンテナンスも効果的です。

CLAUDE.mdの注意点：「お願い」であって「強制」ではない

CLAUDE.mdに書いた内容は、Claude Codeに対する「お願い」や「ガイドライン」であり、100%遵守される保証はありません。公式にも「約80%の精度で従う」とされています。

絶対に守らせたいルール——たとえば「特定のファイルを編集させない」「コミット前にテストを実行する」——は、CLAUDE.mdではなくHooksで制御すべきです。Hooksはsettings.jsonに設定するスクリプトで、ツールの実行前後に確実に実行されます。

CLAUDE.mdが「方針」、Hooksが「法律」——この使い分けが、実務では非常に重要です。以前、CLAUDE.mdに「robots.txtを変更しない」と書いていたのにAIが独断で変更してしまったインシデントがありました。以降、この種の重要ルールはHooksとPermissions（deny設定）で強制するようにしています。