CLAUDE.md の書き方ガイド － Claude Code にプロジェクトのルールを教える
はじめに
Claude Code を使い始めてしばらくすると、こんな不満を感じることがあります。「コーディング規約を毎回説明するのが面倒くさい」「テストの実行コマンドを何度も教えている」「プロジェクトの構成を一から説明しなければいけない」。
Claude Code はセッションを開始するたびに、コンテキストがリセットされます。前回のセッションで伝えた情報は次回には引き継がれないため、同じ説明を繰り返す手間が生じます。
この問題を解決してくれるのが CLAUDE.md です。プロジェクトのルールや慣習を一度書いておけば、Claude Code はセッション開始時に自動でそのファイルを読み込み、毎回同じ内容を説明する必要がなくなります。
この記事では CLAUDE.md の役割と配置場所、効果的な書き方のコツ、そして Auto memory との使い分けまでを順を追って説明します。
CLAUDE.md とは何か
CLAUDE.md は、Claude Code のセッション開始時に自動で読み込まれるマークダウンファイルです。プロジェクト固有のルール、ビルドコマンド、コーディング規約などを記述しておくと、Claude Code はセッションを通じてその内容を参照しながら作業を進めてくれます。
通常のプロンプト指示との大きな違いは「永続性」です。チャットで渡したプロンプトは、セッションが終わると消えてしまいます。一方、CLAUDE.md に書いた内容はファイルとして残り、次回のセッションでも自動的に適用されます。
ただし、CLAUDE.md の指示はシステムプロンプトの一部ではなく、システムプロンプトの後に続くユーザーメッセージとして渡される仕組みです。強制的に実行させる設定ファイルではなく、Claude Code が参考にするコンテキストとして扱われます。そのため、内容が具体的で簡潔であるほど、より一貫した動作が期待できます。
公式ドキュメントでは「新しいチームメンバーが生産性を発揮するために必要なコンテキスト」を書く場所として CLAUDE.md を位置づけています。つまり、プロジェクトの「オンボーディングドキュメント」に近い役割を担っています。
配置場所とスコープの使い分け
CLAUDE.md はいくつかの場所に置くことができ、それぞれスコープが異なります。
プロジェクトルートの CLAUDE.md は、そのプロジェクト内でのみ有効なルールを書く場所です。チームで Git 管理することで、全員が同じルールで Claude Code を使えるようになります。プロジェクト固有のコーディング規約やフォルダ構成の説明はここに書くのが適切です。
~/.claude/CLAUDE.md（ユーザーレベル） は、すべてのプロジェクトに横断して適用されるルールを書く場所です。個人的な作業スタイルや、どのプロジェクトでも共通で使うツールの設定などを記述しておくと便利です。
.claude/CLAUDE.md は、プロジェクト内の .claude ディレクトリに置くファイルです。用途はプロジェクトルートの CLAUDE.md とほぼ同じですが、.claude ディレクトリにまとめて管理したい場合に使います。
CLAUDE.local.md（ローカル個人設定） は、プロジェクトルートに置く個人用ファイルです。CLAUDE.md とは異なり、.gitignore に追加してチームには共有しない運用を前提としています。ローカル環境固有の設定（自分だけのサンドボックス URL、テスト用データのパスなど）を書く場所として公式に案内されています。チーム開発では「CLAUDE.md にチーム共通ルール、CLAUDE.local.md に個人設定」という使い分けが推奨されています。
また、サブディレクトリに CLAUDE.md を置くことで、そのディレクトリ配下に特化したルールを定義することもできます。ただし、サブディレクトリの CLAUDE.md は起動時に一括でロードされるわけではなく、Claude Code がそのサブディレクトリ内のファイルを読み込んだタイミングで初めてロードされます（オンデマンドロード）。たとえば src/api/CLAUDE.md は、Claude Code が src/api/ 配下のファイルを読み込んだときに反映されます。
これらは排他ではなく、すべて連結されてコンテキストに追加されます。ディレクトリツリーのルートから作業ディレクトリに向かって順番に読み込まれるため、作業ディレクトリに近いファイルほど後に読まれます。また、同一ディレクトリ内では CLAUDE.md が先に読まれ、CLAUDE.local.md はその後に追加されます。「グローバルで大まかなルール、プロジェクトで詳細なルール、個人設定は最後」という階層設計はこの挙動に沿ったものです。
なお、Claude Code で /init を実行すると、プロジェクトをスキャンして初期の CLAUDE.md を自動生成してくれます。すでに CLAUDE.md が存在する場合は上書きせず、改善提案を提示するモードに切り替わるため、既存プロジェクトでも安心して実行できます。
効果的な CLAUDE.md の書き方
CLAUDE.md に書くべき内容は大きく4つのカテゴリに分けて考えると整理しやすいです。
ビルド・テストコマンド、コーディング規約、ディレクトリ構成の説明、そしてプロジェクト固有の注意点です。
以下は TypeScript プロジェクトを想定した CLAUDE.md の記述例です。
## ビルドとテスト - ビルド: `npm run build` - テスト全件: `npm test`（コミット前に必ず実行する） - 特定ファイルのテスト: `npm test -- --testPathPattern=<ファイル名>` - リント: `npm run lint`（ファイル変更後に必ず実行する） - 型チェック: `npm run typecheck` ## プロジェクト固有のルール - データベースへのアクセスは必ず `src/repositories/` 配下のクラスを経由する。ドライバを直接呼び出すことは禁止 - 環境変数は必ず `src/config/env.ts` から読み込む。コード中で `process.env` を直接参照しない - 新しい機能は `src/features/<機能名>/` ディレクトリに追加する。`src/services/` に直接追加しない - 自動生成コードは `src/generated/` に置く。このディレクトリのファイルは直接編集しない ## ディレクトリ構成（非自明な部分のみ） - `src/features/`: 機能単位のモジュール（ルーター・サービス・型を一箇所に集約） - `src/shared/`: 複数の features をまたいで使うユーティリティのみ配置 - `src/generated/`: OpenAPI や Prisma による自動生成ファイル
このように、CLAUDE.md に書くべきなのは Claude がコードベースを読んでも知ることができない「プロジェクト固有のルール」 です。Prettier や ESLint、tsconfig.json がすでに管理しているコーディング規約（インデント幅、クォートスタイル、any 禁止など）は、Claude Code が設定ファイルを読めば把握できるため重複して書く必要はありません。また、「データベースへの直接アクセス禁止」のような制約は「〜すること」という説明形よりも「〜を直接呼び出すことは禁止」という命令・禁止の形で書くと Claude の遵守率が上がります。テストコマンドも「コミット前に必ず実行する」のように実行タイミングを添えるのが公式推奨の書き方です。
ファイルの長さについては、200行以内に収めることが推奨されています。これを超えると、コンテキストの消費が増加し、指示の遵守率が下がる可能性があります。内容が増えてきた場合、@path/to/file 構文で別ファイルをインポートする方法もありますが、インポートされたファイルは起動時に展開されてコンテキストに読み込まれるため、コンテキストの削減にはなりません。コンテキストを実際に削減したい場合は、.claude/rules/ ディレクトリにルールファイルを分割し、paths frontmatter でパス固有ルールとして定義する方法が公式に推奨されています。これにより、Claude Code が対象のファイルを読み込んだときだけルールがロードされるようになります。
Auto memory との使い分け
Claude Code には CLAUDE.md のほかに Auto memory という仕組みが搭載されています（Claude Code v2.1.59 以降）。Auto memory はデフォルトでオンになっており、セッション内で /memory コマンドのトグルを使うか、プロジェクト設定で autoMemoryEnabled: false を指定することで無効化できます。
Auto memory は、Claude Code がセッションを通じて得た知見を、保存する価値があると判断したときに自動で記録していく機能です。毎セッション必ず書き込まれるわけではなく、将来のセッションで役立つかどうかを Claude Code 自身が判断します。
保存先は ~/.claude/projects/<プロジェクト>/memory/ ディレクトリです。MEMORY.md はインデックス（エントリーポイント）として機能し、詳細なメモは debugging.md や api-conventions.md のようなトピックファイルに分けて保存されます。MEMORY.md を肥大化させないよう、詳細は個別ファイルに切り出す設計になっています。
CLAUDE.md と Auto memory の違いをまとめると次のとおりです。
| 項目 | CLAUDE.md | Auto memory |
|---|---|---|
| 誰が書くか | 開発者（手動） | Claude Code（自動） |
| 書く内容 | プロジェクトのルールや規約 | 作業を通じて学んだ知見や設定 |
| スコープ | プロジェクト・ユーザー・組織 | 同一 git リポジトリ単位 |
| 起動時のロード | ファイル全文 | MEMORY.md の先頭200行または25KB（先に達したほう） |
| トピックファイル | なし | あり（オンデマンドでロード） |
| 管理方法 | テキストファイルを直接編集 | /memory コマンドで確認・編集 |
| Git 管理 | チームで共有可能 | ローカルのみ（個人向け） |
両者は補完関係にあります。CLAUDE.md には「開発者がチームに伝えたいルール」を、Auto memory には「Claude Code が作業を通じて習得したナレッジ」が蓄積されます。
Auto memory の内容が間違っていると感じた場合は、/memory コマンドでメモリフォルダを開き、MEMORY.md やトピックファイルの内容を確認・修正できます。すべてのプレーンテキストのマークダウンファイルなので、読んで内容を把握したり、不要な情報を削除したりすることも簡単です。
やってはいけない書き方
効果的な CLAUDE.md を維持するために、避けるべきパターンも把握しておきましょう。
曖昧な指示 は最も多いアンチパターンです。「品質の高いコードを書くこと」「読みやすい変数名を使うこと」といった指示は解釈の幅が広く、Claude Code が一貫した動作をしにくくなります。代わりに「変数名はcamelCase、定数はUPPER_SNAKE_CASEを使う」のように具体的に書くようにしましょう。
長すぎるファイル も問題です。200行を超えると、コンテキストの消費量が増えるだけでなく、重要なルールが埋もれて遵守率が下がる傾向があります。なお、@path 構文で別ファイルをインポートしても起動時に展開されるためコンテキストは減りません。コンテキストを実際に削減したい場合は、.claude/rules/ に分割してパス固有ルールとして定義するのが正しい対処です。
手順書のような冗長な内容 も避けましょう。「新機能を追加する際は、まずブランチを作成し、次にテストを書き、その後実装して...」のような複数ステップの手順は、Skills として別途定義するほうが適切です。CLAUDE.md はあくまでも「常に参照すべきコンテキスト」を書く場所です。
また、複数の CLAUDE.md ファイルで矛盾する指示を書かないよう注意が必要です。同じ振る舞いに対して異なるルールが存在する場合、Claude Code がどちらを優先するか不明確になります。InstructionsLoaded フックを使うと、どのファイルがいつ・なぜ読み込まれたかをログで確認できるため、パス固有ルールやサブディレクトリのオンデマンドロードが期待通りに動いているかのデバッグに役立ちます。
まとめ
CLAUDE.md は、Claude Code に対してプロジェクトのルールや規約を「一度書けば毎回伝わる」ようにするための仕組みです。
まずは /init コマンドで自動生成された CLAUDE.md をベースに、プロジェクト固有のルールを少しずつ追記していくのがよいスタートです。最初から完璧なファイルを目指すよりも、「Claude Code に何度も説明したこと」を都度書き加えていくスタイルが、長続きするコツといえます。
この記事がどなたかのお役に立てれば幸いです。
◆ 塩野 正人
◆ マネージドサービス部 所属
◆ X（Twitter）：@shioccii
◆ 過去記事はこちら
前職ではオンプレミスで仮想化基盤の構築や運用に従事。現在は運用部隊でNew Relicを使ってサービス改善に奮闘中。New Relic User Group運営。
