Claude Codeの’CLAUDE.md’とは？必要性や書き方・活用法も解説
CLAUDE.mdって何のファイルなんだろう？
どう書けばいいのかな…
Claude Codeを使い始め「CLAUDE.md」という単語を見聞きする機会が増えた人も多いですよね。
「CLAUDE.mdは重要」そんな情報は聞くものの、実際にどう使えばいいかわからない人もいるはず。設定ファイルや指示書であることがわかっても、具体的にどう書けばいいのかイメージが湧かないですよね。
そこでこの記事では役割も交え、CLAUDE.mdの特徴を解説します。書き方やプロンプト例・効果的に活用するコツも紹介するので、ぜひ参考にしてください。
- CLAUDE.mdはClaude Codeに毎回読み込まれる永続的な指示書
- プロジェクトルート・サブディレクトリ・ホームの3階層に配置できる
- CLAUDE.mdは200行以内に収め、ルールに理由を添えると効果的
Claude Codeにおける’CLAUDE.md’とは
CLAUDE.mdとは、Claude Codeが自動的に読み込む指示書ファイルです。
CLAUDE.mdへプロジェクトのルールやコーディング規約、禁止事項などをMarkdown形式で記述しておくと、Claude Codeは会話を始めるたびに内容を参照します。毎回「このプロジェクトではTypeScriptを使ってください」などと入力する必要がありません。
Anthropicの公式ドキュメントでは、CLAUDE.mdを「メモリファイル」と位置づけています。Claude Codeにはセッションをまたいだ記憶機能がないため、CLAUDE.mdがその代替として機能します。チーム開発では、全員が同じルールのもとでAIを使えるようになる点も大きなメリットです。
CLAUDE.mdの仕組み
CLAUDE.mdは、配置する場所によって参照される範囲が変わります。
ここからは下記のディレクトリ別に、読み込まれる範囲の違いを解説します。
プロジェクトルートの’CLAUDE.md’
プロジェクトのルートディレクトリに置いたCLAUDE.mdは、プロジェクト全体に適用される指示として読み込まれます。
最もよく使われる配置場所でプロジェクト固有のルール、使用技術、コーディング規約などを記述することが多いです。Claude Codeはプロジェクトを開いた瞬間にファイルを検出し、すべての会話に反映します。
たとえば、Reactプロジェクトのルートに置いたCLAUDE.mdに「関数コンポーネントのみ使用する」と書いておくと、AIはプロジェクト内のコード生成でクラスコンポーネントを避けます。
サブディレクトリごとの’CLAUDE.md’
プロジェクト内のサブディレクトリにCLAUDE.mdを置くと、ディレクトリ配下だけに適用される指示を追加できます。
ルートのCLAUDE.mdの内容を上書きするのではなく、追記する形で機能します。
ディレクトリ構成の例は、次のとおりです。
```
my-project/
├── CLAUDE.md # プロジェクト全体のルール
├── src/
│ ├── api/
│ │ └── CLAUDE.md # APIディレクトリ固有のルール
│ └── components/
│ └── CLAUDE.md # コンポーネント固有のルール
└── tests/
└── CLAUDE.md # テスト用のルール
```たとえば、`/src/api/` ディレクトリに置いたCLAUDE.mdには「APIディレクトリではREST APIの命名規則に従う」と記載すると、ディレクトリ配下でのみルールを適応可能です。フロントエンドとバックエンドで、ルールを分けたい場合などに役立ちます。
ホームディレクトリ(~/.claude/CLAUDE.md)
ホームディレクトリの `~/.claude/CLAUDE.md` に置いたファイルは、すべてのプロジェクトに共通して適用される指示として機能します。
個人の作業スタイルや好みのコードフォーマット、言語設定などを書くのに適した場所です。たとえば「常に日本語で回答する」「コメントはJSDoc形式で書く」などの使いやすさに関する設定を記述できます。
プロジェクトごとにCLAUDE.mdを作らなくても、個人の基本ルールは常に適用される点が便利です。チーム共有するプロジェクトのCLAUDE.mdには書きづらい個人的な好みの設定を、ホームディレクトリで管理できます。
Claude Codeに’CLAUDE.md’は必要？
結論として、継続的に使うプロジェクトには作成をおすすめします。一方で、一時的な用途では不要なケースもあります。
ここからはClaude Codeに’CLAUDE.md’は必要か、作成の判断基準を解説します。
作成すべきケース
次のいずれかに当てはまる場合は、CLAUDE.mdを作成すべきです。
- 同じプロジェクトに繰り返しアクセスする
- チームで複数人がClaude Codeを使う
- コーディング規約や命名ルールが決まっている
- 特定のフレームワークやライブラリを固定して使う
- テストやデプロイの手順を標準化したい
とくにチーム開発では、CLAUDE.mdがないとメンバーごとに異なる指示をAIに与えてしまい、コードのスタイルがばらつきます。CLAUDE.mdをGitリポジトリで共有すれば、同じルールのもと安定した運用が可能です。
個人開発でも週に複数回同じプロジェクトを触るなら、毎回指示を入力する手間が省けるため、作成するメリットが多いです。
作成が不要なケース
次のような状況では、CLAUDE.mdを作成しなくても問題ありません。
- 1回限りのスクリプト作成や試作
- 特定のルールが不要な簡単な質問・調査
- チャット内で毎回指示を与えられる短期プロジェクト
CLAUDE.mdの作成・管理にも、一定のコストがかかります。使い捨てのコードを書くだけなら、チャット内でその都度指示した方が効率的です。
「とりあえず作ってみる」という姿勢は悪くありませんが、内容が薄すぎるCLAUDE.mdは逆に使いにくい場合も。書くべき内容が3項目以上ある段階で、作成を検討するのがおすすめな判断基準です。
Claude Code・’CLAUDE.md’の作り方
ここからは、Claude Code・CLAUDE.mdの作り方を解説します。
1.’/init’コマンドで自動生成する
Claude Codeのチャット欄に `/init` と入力すると、Claude Codeがプロジェクトを自動で分析してCLAUDE.mdを生成します。
手順は、次のとおりです。
- ターミナルでプロジェクトのルートディレクトリに移動する
- `claude` コマンドでClaude Codeを起動する
- チャット欄に `/init` と入力してEnterを押す
- 生成されたCLAUDE.mdの内容を確認・編集する
`/init` コマンドを実行すると、Claude Codeはプロジェクト内のファイル構成や `package.json`、既存のコードを読み取ります。使用技術やディレクトリ構成を自動で把握し、ひな形を作成します。
ゼロから書く手間が省けるため、初めてCLAUDE.mdを作る場合はこの方法がおすすめです。生成後はAIの判断に任せた部分を自分でチェックし、実際のルールに合うよう修正してください。
2.手動でファイルを作成する
プロジェクトのルートディレクトリに `CLAUDE.md` という名前でファイルを作成し、テキストを書くだけで完成します。
VSCodeを使っている場合は、エクスプローラーからファイルを新規作成するだけです。コマンドラインで作成するなら、次のコマンドを使います。
```bash
touch CLAUDE.md
```手動作成のメリットは、最初から自分の意図したルールだけを書ける点です。
基本的な構成例は、次のとおりです。
“`markdown
# プロジェクト概要
このプロジェクトはReact + TypeScriptで構築されたECサイトです。
使用技術
React 18
TypeScript 5
Tailwind CSS
コーディング規約
関数コンポーネントのみ使用する
Propsの型定義は必ずinterfaceで書く
ファイル名はPascalCaseにする
禁止事項
any型の使用
console.logの本番コードへの混入
“`
`/init` で生成したファイルには不要な情報が含まれることもあるため、シンプルな構成にしたい場合は手動の方が向いています。
CLAUDE.mdのプロンプト例
ここからはCLAUDE.mdのプロンプト例を、3つにまとめて解説します。
コーディング規約を指示する例
コーディング規約の指示は、CLAUDE.mdの中で最も使用頻度が高い記述の一つです。AIが自動生成するコードのスタイルを統一できます。
“`markdown
コーディング規約
言語・構文
・TypeScriptを使用する（JavaScriptは使わない）
・型アサーション（as）は使用しない。型ガードで代替する
・enumは使用しない。union型またはconstオブジェクトで代替する
命名規則
・変数・関数名: camelCase
・コンポーネント名・型名・インターフェース名: PascalCase
・定数: SCREAMING_SNAKE_CASE
・ファイル名: コンポーネントはPascalCase、ユーティリティはcamelCase
関数
・関数は原則として純粋関数にする
・1つの関数に責務は1つだけ持たせる
・引数が3つ以上になる場合はオブジェクトにまとめる
“`
規約を書く際は「〜を使う」という肯定形と「〜を使わない」という否定形をセットで書くと、AIが迷いなく判断できます。
エラー対応の方針を指示する例
エラーハンドリングの方針をCLAUDE.mdに書いておくと、AIが生成するエラー処理のコードが一貫します。
“`markdown
エラーハンドリング方針
基本原則
・エラーは握りつぶさない。必ずログ出力かユーザーへの通知を行う
・try-catchのcatchブロックを空にしない
・ユーザーに見せるエラーメッセージは日本語にする
APIエラー
・HTTPステータスコード別に処理を分岐する
・4xx: ユーザーへのフィードバックを表示する
・5xx: リトライ処理を最大3回行ったうえでエラー画面を表示する
・タイムアウトは10秒に設定する
エラーの種類と対応
・ネットワークエラー: オフライン状態のメッセージを表示する
・認証エラー: ログイン画面にリダイレクトする
・バリデーションエラー: 入力フォームの該当箇所にインラインで表示する
“`
「エラーを握りつぶさない」のように抽象的な原則だけでなく、具体的な条件分岐の例を添えることで、AIはより意図に沿ったコードを生成します。
出力フォーマットを指定する例
コード以外の出力フォーマット、たとえば回答の構成や説明の形式もCLAUDE.mdで制御できます。
“`markdown
出力・回答の形式
コード生成時
・変更箇所には必ずコメントで「// 変更」と記載する
・新規追加箇所には「// 追加」と記載する
・削除した箇所は残さず、コード全体をクリーンな状態で出力する
説明・解説時
・最初に変更の要約を3行以内で述べる
・理由や背景は「なぜなら」から始めて1文で説明する
・コードブロックと説明文を交互に配置する
コミットメッセージ
・プレフィックス: feat / fix / docs / style / refactor / test / chore
・日本語で書く
・50文字以内に収める
・例: feat: ユーザー認証機能を追加する
“`
出力フォーマットを統一しておくと、複数のAI生成ファイルをマージする際に差分が見やすいです。
効果的なCLAUDE.mdを書く7つのポイント
CLAUDE.mdの内容が曖昧だったり冗長だったりすると、AIの動作が安定しません。
ここからはCLAUDE.mdを効果的に作成するポイントを、7つにまとめて解説します。
1.「What→Why→How」の3層で構成する
CLAUDE.mdの全体構成は「何をするプロジェクトか（What）」「なぜそのルールがあるか（Why）」「具体的にどうするか（How）」の3層で整理すると、AIの出力精度を高められます。
最初にプロジェクトの概要を書き、次にそのルールが生まれた背景を示し、最後に具体的な指示を並べます。AIはファイルを上から順に読むため、冒頭にプロジェクトの目的と全体像を置くと、後続のルールを正しく解釈しやすいです。
たとえば「TypeScriptを使う」とだけ書くより、「型安全性を担保するためにTypeScriptを使う。バックエンドチームとの型共有が目的のため、型定義ファイルは `src/types/` に集約する」と書いた方が、AIはより適切なコードを生成します。
2.検証可能な指示にする
実行後に生成内容を検証できるように、より具体的な指示を出しましょう。
「わかりやすいコードを書く」「丁寧にコメントを書く」のような曖昧な指示は避けてください。AIが「わかりやすい」の基準を判断できないためです。
代わりに、次のような検証可能な形式で書きます。
- 「関数は1つにつき30行以内に収める」
- 「コメントはすべての関数に1行以上書く」
- 「変数名は略語を使わず、フルスペルで書く（例：`btn` → `button`）」
「守られているかどうかを客観的に判断できる指示」にすることで、AIの出力が安定します。レビュー時にもルール違反を指摘しやすいです。
3.200行以内に収める
CLAUDE.mdは、200行以内に収めましょう。
CLAUDE.mdが長すぎると、Claude Codeのコンテキストウィンドウを圧迫します。内容が多いほど後半の指示が無視されやすくなるため、200行（約4,000文字）を上限の目安にしてください。
Anthropicの公式ドキュメントでも、メモリファイルを簡潔に保つことを推奨しています。200行を超えそうになった場合は、次の優先順位で削減します。
- 重複している指示を統合する
- 現在のプロジェクトで発生していない仮定のルールを削除する
- チャット内で毎回指示できるものをCLAUDE.mdから外す
- サブディレクトリのCLAUDE.mdに分割する
CLAUDE.mdは「書けば書くほど良い」ではありません。重要なルールを絞り込む方が、AIの動作は安定します。
4.「やるな」リストを明示する
精度を高めるために、CLAUDE.mdに禁止事項を明記しましょう。
「〜しない」「〜を使わない」という禁止事項のリストは、ポジティブな指示と同じかそれ以上に重要です。AIはデフォルトの動作で「良かれと思って」不要な処理を追加することがあります。
禁止事項の例は、以下の通りです。
“`markdown
禁止事項
・console.logを本番コードに残さない
・any型を使わない
・ファイルを新規作成する前に確認を取る
・依存パッケージを無断で追加しない
・既存のテストを削除しない
“`
とくに「ファイルを新規作成する前に確認を取る」「依存パッケージを無断で追加しない」のような指示は、予期しない変更を防ぐために効果的です。初めてCLAUDE.mdを書く場合も、禁止事項から先に考えると整理しやすくなります。
5.ルールには理由を添える
ルールを書く際は「なぜそのルールがあるのか」を1行で添えることをおすすめします。理由があると、AIがルールの意図を理解したうえで例外判断を適切に行えます。
ルールの理由を記載する例は、以下の通りです。
“`markdown
データ取得
・データ取得にはSWRを使う（理由：キャッシュとリバリデーションを統一するため）
・fetchを直接呼ばない（理由：エラーハンドリングの一元管理のため）
“`
理由なしで「SWRを使う」とだけ書くと、AIは場合によってはAxiosやfetchで代替してしまうことも。理由を書くことで「例外なく守るべきルール」として扱われる確率が上がります。
6.繰り返し起きた修正を追記する
AIが生成したコードに同じ修正を3回以上加えていたら、修正内容をCLAUDE.mdに追記するサインです。「毎回この指示をしている」と気づいた時点で、ファイルを更新してください。
たとえば、次のようなパターンが繰り返された場合は追記対象です。
- 「絶対パスでimportしてほしいのに毎回相対パスになる」
- 「日付フォーマットが `YYYY/MM/DD` になってほしいのに `MM/DD/YYYY` で出てくる」
- 「レスポンスのネスト構造を毎回修正している」
繰り返しの修正は、CLAUDE.mdを更新すべきシグナルです。修正をCLAUDE.mdに蓄積していくと、時間の経過とともに指示精度が上がります。
7.矛盾を定期的に棚卸しする
Claude Codeを効率的に使うには、CLAUDE.mdの定期的な見直しが大切です。
CLAUDE.mdは更新を重ねると、古いルールと新しいルールが矛盾するケースも出てきます。「〜を使う」と「〜は使わない」が同じファイルに共存していると、AIが混乱して動作が不安定になりやすいです。
月に1回程度、次の観点でCLAUDE.mdを見直してください。
- 同じ対象について矛盾する指示がないか
- 実際には使っていない技術のルールが残っていないか
- すでに解決した問題へのルールが不要になっていないか
古くなったルールの削除は、新しいルールの追加と同じくらい重要です。棚卸しをしないまま更新し続けると、CLAUDE.mdの質が下がります。
Claude CodeのCLAUDE.mdによく抱く疑問
ここからは、Claude CodeのCLAUDE.mdによく抱く疑問へ回答します。
毎回読み込まれる？
Claude Codeは、セッション開始のたびにCLAUDE.mdを自動で読み込みます。
ただし、読み込む動作はトークンを消費。CLAUDE.mdの文字数はそのままコンテキストウィンドウを使うため、長くなるほど1回あたりのコストが上がります。無料プランや低コストプランで使う場合は、ファイルをコンパクトに保つことが節約には大切です。
手動で読み込みたい場合は、チャット内で `@CLAUDE.md` と入力することで任意のタイミングでファイルを参照させられます。
長すぎると逆効果になる？
長すぎるCLAUDE.mdは逆効果です。Claude Codeのコンテキストウィンドウには上限があり、ファイルが大きいほど後半の指示ほど無視されやすくなります。
Anthropicの公式ドキュメントでも、メモリファイルは簡潔に保つよう推奨されています。重要なルールは必ず上位に配置し、全体を200行以内に収めるのがおすすめです。
どうしても内容が多くなる場合は、サブディレクトリにCLAUDE.mdを分割し、関連するルールをそれぞれ近い場所に置く構成にしてください。
複数のプロジェクトでテンプレ化できる？
複数プロジェクトで、テンプレート化は可能です。
複数プロジェクトで共通するルールは `~/.claude/CLAUDE.md` に書き、プロジェクト固有のルールはプロジェクトルートのCLAUDE.mdに書く運用が効率的です。
チーム開発であれば、社内の共通テンプレートをGitリポジトリで管理し、新規プロジェクト開始時にコピーする運用も有効です。次のような3層構造を意識すると、管理しやすくなります。
- `~/.claude/CLAUDE.md`：個人の全プロジェクト共通ルール
- プロジェクトルートの`CLAUDE.md`：プロジェクト共通ルール
- サブディレクトリの`CLAUDE.md`：特定ディレクトリのルール
ホームディレクトリのCLAUDE.mdが個人テンプレートの役割を担うため、まずここに自分の基本スタイルを書いておくとすべてのプロジェクトに反映されます。
SkillsファイルやClaude/rulesと何が違う？
混同しやすいですが、それぞれ用途が異なります。
| 名前 | 対象 | 主な用途 |
|---|---|---|
| CLAUDE.md | Claude Code | プロジェクト・個人の永続指示 |
| Skillsファイル | Claude・Claude Code・API | ワークフローの自動化・専門タスクの定型化 |
| Claude/rules | Claude Code | ルールファイルのモジュール管理(プロジェクト単位・ユーザー共通の両方で配置可能) |
Skillsファイルは、Claude Code固有の機能です。Claudeにも「Skills」という名称の機能がありますが、Claude Codeとは別の仕組みであり、横断的に共有できるものではありません。主な用途はワークフローの自動化・繰り返し作業の効率化・専門知識のカプセル化であり、CLAUDE.mdとは設計の概念が異なります。
Claude/rules（`~/.claude/` 配下のファイル群）は、Claude Codeの設定ディレクトリです。CLAUDE.mdをこの中に置くことで全プロジェクト共通の指示として機能します。
CLAUDE.mdはClaude Code専用の指示ファイルであり、ウェブ版のClaudeには影響しません。
まとめるとプロジェクト単位でのルールや指示を記載したいならCLAUDE.md、ワークフローの自動化や専門タスクの定型化を進めたいならSkillsファイル。
全プロジェクト共通の設定を記載したいなら、Claude/rulesを活用してください。
Gitで管理した方がいい？
チーム開発では、CLAUDE.mdをGitで管理することをおすすめします。
Gitで管理するメリットは、次のとおりです。
- チームメンバー全員が同じCLAUDE.mdを使える
- 変更履歴を追跡できる
- 誤って削除・変更した場合に復元できる
- プルリクエストでCLAUDE.mdの変更をレビューできる
`.gitignore` に追加すると個人設定として使えますが、チーム用途ではリポジトリに含める方が運用しやすいです。
個人の好みに依存する設定は `~/.claude/CLAUDE.md` に、チーム共通のルールはプロジェクトルートのCLAUDE.mdに分けて管理するのがベストです。
なお、Claude CodeとGitの連携について知りたい人は、以下の記事を参考にしてください。
まとめ
今回は、CLAUDE.mdの概要と活用方法を解説しました。
CLAUDE.mdにプロジェクトのルールやコーディング規約、禁止事項を記載することで開発作業を効率化できます。さらにルールを規定しておけば、Claude Codeでの作業精度を高め、集団での業務も進めやすいです。
Claude Codeを継続的に活用する人や、ビジネスでチーム開発を行う人はCLAUDE.mdの活用を検討してください。
