「Claude CodeのCLAUDE.mdって何？」と気になっている方は少なくありません。
CLAUDE.mdはClaude Codeに渡すルール集を書いた設定ファイルで、配置するだけでAIに指示を毎回伝えなくて済みます。
Claude CodeはAnthropicの開発支援AIで、コード作業を自然な言葉で任せられるツールです。
たとえば「コメントは日本語で」と書くだけで、AIがそのルールを踏まえて回答してくれます。
この記事では、設置パターンから書き方、失敗例までまとめて紹介します。
生成AIパスポート取得者が内容をチェック
当サイトの記事は、生成AIに関する基礎知識やリスク、適切な活用方法などを学ぶ「生成AIパスポート」の取得者が内容を確認しています。情報の正確性や分かりやすさを意識した記事づくりに努めています。
Claude CodeのCLAUDE.mdとは
CLAUDE.mdはClaude Codeに「このプロジェクトではこういうルールで作業してね」と伝えるための設定ファイルです。
Claude Codeを起動するとAIが自動でこのファイルを読み込み、書かれているルールを踏まえて応答してくれます。
たとえば「コメントは日本語で書く」「変数名は英語で統一する」といった指示を一度書いておけば、毎回チャットで伝え直す必要がなくなります。
書き方はマークダウン形式で、見出しと文章で構成するだけです。
複数の場所に置けるため、プロジェクト全体・自分専用・特定の作業ごとに使い分けられるのも特徴です。
Claude CodeでCLAUDE.mdの設置パターン
CLAUDE.mdは1か所だけでなく、置く場所を変えるとAIへの指示の届く範囲が変わります。
プロジェクト全体に効かせたいルールと、自分専用に隠しておきたい設定では、それぞれ別ファイルに分けるのが基本です。
チーム共有のルールと個人の好みを混ぜると、後で整理が大変になりがちです。
ここでは4つの代表的な置き方と、それぞれが適している使い方を順番に見ていきます。
プロジェクトのフォルダに置く基本設定
「コードを置いてあるフォルダの直下にCLAUDE.mdを作る」のが最も基本的なやり方です。
たとえば「webアプリ用のフォルダ」「社内ツール用のフォルダ」など、作業ごとのフォルダの中に直接ファイルを作って置きます。
このファイルはチーム全体で共有するルールを書く場所として使うのが一般的です。
コードの管理サービスにそのまま一緒に登録しておけば、メンバー全員が同じルールでAIに作業を依頼できます。
たとえば「テストは必ず書く」「ファイル名は英語で統一する」など、誰が触っても守ってほしい内容を入れておくと効果的です。
書いた内容はチームメンバーの目に触れるため、個人的なメモや一時的なルールは別ファイルに分けるとよいでしょう。
全プロジェクト共通のルールをホームフォルダに書く
「どのプロジェクトを開いても効かせたい内容」は、自分のパソコンのホームフォルダにある「~/.claude/CLAUDE.md」というファイルに書きます。
「~」（チルダ）は自分のユーザー領域を指す記号で、Windowsで言うところの「ユーザー名」フォルダにあたります。
ここに書いたルールはすべてのプロジェクトで自動的に読み込まれるため、自分の好みや作業スタイルをまとめておく場所として便利です。
たとえば「説明は丁寧な口調で答える」「コードの解説は箇条書きにする」のような個人の好みは、ここに集約しておくと毎回書き直さずに済みます。
ただし、ここに書いた内容は他人には共有されません。
チームで揃えたいルールは前項のプロジェクトフォルダ側に書きましょう。
自分だけの設定をCLAUDE.local.mdに分ける
「これは自分だけが知っていればいい内容」は、プロジェクトフォルダの中に「CLAUDE.local.md」というファイルを別に作って入れます。
ファイル名に「.local」が入っているため、コードの管理サービスでは自動的に共有から除外されるのが一般的な使い方です。
たとえば「自分の開発環境ではこのフォルダの場所が違う」「個人で試している実験的なルールがある」といった内容を入れると、チームに見られずに済みます。
このやり方なら、共有用のCLAUDE.mdをきれいに保ったまま個人だけの調整を上乗せできるのが利点です。
チームの開発スタイルに合わない部分を自分用に上書きしたいときにも、この「.local」付きファイルが役立つでしょう。
ルールをファイルごとに分けて整理する
ルールが増えてくると、1つのCLAUDE.mdに全部書くと長くなりすぎて読みにくくなります。
そんなときは別ファイルに分けて、CLAUDE.mdから「あのファイルも読んでね」と呼び出す書き方が便利です。
たとえば「ファイル名のルール」「フォルダ構成の説明」「テストの書き方」をそれぞれ別ファイルに保存しておき、CLAUDE.mdには「@docs/naming.md を参照」のように1行書くだけにします。
「@」を頭につけてファイルの場所を書くと、AIがそのファイルを開いて中身を読んでくれる仕組みです。
整理しておくと、ルールを修正するときに該当ファイルだけ書き換えれば済むため、メンテナンスも楽になります。
Claude CodeのCLAUDE.mdに書くべき内容
CLAUDE.mdの効果は、書く内容の選び方で大きく変わります。
「何でも書けばいい」というわけではなく、AIが繰り返し迷いがちなポイントや、毎回伝えるのが面倒な前提を選んで入れていくのがコツです。
中身が薄いと指示として機能せず、逆に詰め込みすぎるとAIが読み飛ばす原因にもなります。
ここでは、書いておくと作業効率がぐっと上がる5つの代表的な内容を紹介します。
よく使うコマンドやツールの設定を記載する
毎回AIに「このプロジェクトではテストはこのツールで動かす」「画面を立ち上げるときはこのコマンドを使う」と伝えるのは面倒です。
CLAUDE.mdに最初から書いておけば、AIが状況に合わせて自動的に正しい操作を選んでくれます。
たとえば「テストはJestで実行する」「データベースの確認はこのコマンドで行う」など、よく使う作業の手順を1行ずつ書いておく形が一般的です。
ツール名は省略せず、フルネームで書くと取り違えが起きにくくなります。
さらに、各ツールに渡す引数や注意点まで書いておくと、AIがそのまま使えるコマンドを提案してくれるようになります。
ただし、社内のローカルな環境変数やパスワードは書かないように注意しましょう。
コードの書き方ルールを定義する
「コードはどんなスタイルで書くか」を明示しておくと、AIが提案するコードの形がそろってきます。
CLAUDE.mdには、コードの体裁や命名のルールをまとめて書いておきましょう。
たとえば「コメントは日本語で書く」「1行に書くのは120文字までにする」のように、形が決まっている部分をそのまま伝える形が効果的です。
文字数の制限・インデントの幅・並び順なども、ここに書くと毎回統一されたコードが返ってきます。
このルールを書いておかないと、AIは標準的なスタイルで書こうとするため、プロジェクトの既存コードとちぐはぐになる場合があります。
チーム独自の決まりほど、明文化しておく効果が大きいです。
プロジェクトの構造と設計方針を書く
CLAUDE.mdに、プロジェクト全体の作りや設計の考え方を1ページにまとめておくと便利です。
「画面の部分はこのフォルダ」「裏側の処理はこっち」のような分担を1行ずつ書くだけでも、AIの提案が安定します。
特に新しい機能を追加するときは、AIが「どこに置けばいいか」を判断する材料になります。
設計の考え方も簡単にメモしておくとよいでしょう。
「データの保存は1か所にまとめる」「外部のサービスとつなぐコードはここに集める」など、方針レベルの一文だけで十分です。
詳細な仕様まで書く必要はなく、「全体像をつかむ地図」のような役割を意識すると、ファイルが長くなりすぎずに済みます。
開発の進め方の手順を記述する
「コードを書き始める前に何をして、どこで動作確認するか」といった手順を書いておくと、AIが作業の流れに沿って動いてくれます。
たとえば「変更前にまずテストを実行する」「ファイルを書き換えたら毎回画面で確認する」のような決まった流れを並べておくのが基本です。
手順を箇条書きで番号付きにすると、AIが順番を間違えずに進めやすくなります。
開発の進め方が独特なプロジェクトでは、特にこの記述が効きます。
「決められたコマンドを使って自動化したテストを行う」「リリース前にこの確認を必ず通す」など、外しがちなチェックを言語化しておくと安心です。
口頭で伝えづらいローカルルールほど、文章にしておく価値が高くなります。
よく参照するファイルの場所を指定する
CLAUDE.mdに「このプロジェクトでよく見るファイル」へのパス（場所）を書いておくと、AIが必要なファイルを自分で開いて読み込んでくれます。
たとえば「画面ごとの仕様書はdocsフォルダにある」「データの形は schema.json にまとまっている」など、AIに見てほしいファイルを指定する書き方になります。
「@」を頭につけてファイル名を書くと、AIがそのファイルを優先的に確認してくれる仕組みです。
毎回チャットで「あのファイルも見て」と添付する手間が減るのは大きなメリットです。
ただし、ファイルが多くなりすぎるとAIの読み込み量を超えてしまうため、最重要のファイルだけに絞っておきましょう。
Claude CodeのCLAUDE.mdに書くべきでない内容3つ
CLAUDE.mdに何を書くかと同じくらい、「書かないこと」を決めるのも重要です。
書きすぎるとAIが情報を取りこぼし、肝心の指示まで読み飛ばす原因になります。
「とりあえず入れておけば安心」と判断すると、ファイル全体の質を下げかねません。
ここでは、避けたほうがいい3つの内容を順番に紹介します。
コードを読めば分かることは書かない
「ファイルがこのフォルダにあります」「クラス名はこの通りです」のような、コードを開けばすぐ確認できる情報は書かなくて大丈夫です。
AIはコードを直接読み取れるため、二重に書くと記述が冗長になり、肝心のルールがうもれてしまいます。
書くべきは「コードからは読み取れない決まりごと」だけです。
たとえば「このフォルダは触らないでほしい理由」「この古い書き方は使わない方針」など、コードを見るだけでは伝わらない背景や禁止事項を中心にまとめましょう。
情報源はコード本体に任せ、CLAUDE.mdは「コードに書かれていない情報」専用にしておくのが基本です。
自動チェックツールに任せるルールは省く
コードの体裁を整える専用ツール（フォーマッターと呼ばれる種類のソフト）にすでに任せている内容は、CLAUDE.mdに書く必要はありません。
たとえば「タブとスペースの統一」「セミコロンの有無」などは自動チェックツールが処理してくれるため、AIに改めて指示しなくても大丈夫です。
二重で書くとAIがツールと矛盾する判断をする可能性が出てきます。
さらに、本当に伝えたい設計方針や独自ルールが、形だけのルールに埋もれてしまう原因にもなります。
「ツールが見てくれる範囲」と「AIに伝えるべき範囲」をはっきり分けて、後者だけをCLAUDE.mdに集約しましょう。
特定の作業専用の指示を全体設定に混ぜない
「テストを書くときだけ守ってほしいルール」「画面の見た目を整えるときだけ気をつけてほしい点」などは、CLAUDE.md本体ではなく別ファイルに分けるのが基本です。
全体設定に混ぜると、関係ない作業のときにもAIがその指示を意識し、回答が冗長になります。
たとえば「テスト用の細かい命名ルール」は別ファイルにまとめておき、必要なときだけCLAUDE.mdから呼び出す形が便利です。
「@docs/testing.md を参照」のように1行書いておけば、テスト関連の作業のときだけAIが読みに行ってくれます。
全体設定はあくまで「いつでも効いていてほしい大枠」だけにとどめ、シーン別のルールは分離して整理しましょう。
Claude Codeの性能を最大化するCLAUDE.mdの書き方
CLAUDE.mdは書く量や構成のしかた次第で、AIの読み取り精度が変わるものです。
短すぎると指示が足りませんし、長すぎても情報の優先順位がぼやけてしまいがちです。
AIに効率よく内容を読み取ってもらうため、書く長さと整理の仕方には共通のコツがあります。
ここでは、AIの理解度を高める3つの書き方ポイントを紹介します。
60〜300行を目安に書く
CLAUDE.mdには行数の目安があり、短すぎるとAIに伝わる情報が不足し、ルールとして十分機能しません。
長すぎるとAIが全部読み切れず、後半の重要なルールが無視されることもあるため、目安は60行〜300行です。
100行前後を基本にして、必要に応じて少し増減させる程度にとどめると、書きすぎも不足も避けられます。
これ以上書きたくなったら、別ファイルに分けて呼び出す形にしましょう。
メインのCLAUDE.mdは要点だけにして、詳細は別ファイル側に置くほうが結果的に伝わりやすくなります。
セクションを見出しで区切って読みやすくする
CLAUDE.mdは「ベタ書き」より「見出しで区切ったほうがAIが理解しやすくなります。
マークダウンの「##」や「###」を使い、内容ごとにセクションを分けて構造化しておきましょう。
たとえば「## コードの書き方ルール」「## プロジェクトの構成」「## 作業の進め方」のように、目的別の見出しで区切るのが基本です。
それぞれの中に短い文章でルールを書き並べると、AIが必要な部分を素早く取り出せるようになります。
見出しを設けるとファイルの目次が頭の中で見えるため、自分自身も後から内容を追加しやすくなります。
詳細な情報は別ファイルに分けて読み込む
CLAUDE.mdが長くなりそうなときは、内容ごとに別ファイルに切り分けると整理しやすくなります。
「@」をつけて呼び出す書き方を使うと、メインのCLAUDE.mdから他のファイルを参照できる仕組みです。
たとえば命名ルールは「@docs/naming.md」、テストの手順は「@docs/testing.md」のように分けておき、CLAUDE.md本体には1行ずつ参照を書くだけにしておきます。
修正するときも、該当ファイルだけ書き換えれば済むため、メンテナンスの負担も減るのが利点です。
ただし、ファイルの数を増やしすぎるとどこに何が書いてあるか分からなくなるため、3〜5個程度にとどめるのがおすすめです。
CLAUDE.mdの指示が効かないときに確認する3つのポイント
CLAUDE.mdに書いた内容が反映されない場合、ファイル自体に問題がない限り、AIの読み込み量や記述の長さに原因があることが多いです。
設定したつもりでも実は読み込まれていないケースは珍しくないため、まずは見直しのポイントを押さえておきましょう。
ここでは、確認すべき3つの代表的なポイントを紹介します。
AIの読み込み上限を超えていないか確認する
AIには一度に処理できる文字数の上限があります。
CLAUDE.mdの量がほかの読み込みファイルと合わせて上限を超えると、後半のルールが切り捨てられて反映されない原因になります。
特に「@」で大量のファイルを参照している場合は、CLAUDE.md本体は短くても、合計の読み込み量はふくらみがちです。
読み込み対象のファイルを一覧で書き出してみると、想定より多いことに気づくこともあります。
対策としては、外部ファイルへの参照を最小限に絞り、本当に毎回必要なものだけ残す方法が有効です。
「指示が一部だけ効いていない」と感じたときは、まず読み込み総量を疑ってみるとよいでしょう。
ファイルが大きすぎて読み飛ばされていないか確認する
CLAUDE.md自体が長すぎる場合も、後半の内容がAIに読み飛ばされる原因です。
500行を超えるあたりからは、特に末尾のルールが反映されにくくなります。
書いた直後に「最後のほうの指示が効いていない気がする」と感じたら、ファイル全体の行数を数えてみましょう。
300行を大きく超えているなら、内容を整理して別ファイルに切り出すのが手早い対処法です。
優先度の高いルールほど、ファイルの前半にまとめると効きやすくなります。
「絶対守ってほしいこと」を冒頭にまとめ、「あれば守ってほしい程度のもの」は後半に置く順序立てが安心です。
会話のリセット後に指示が消えていないか見直す
Claude Codeで新しい会話を始めると、それまでに渡していた指示が一度リセットされる場合があります。
長時間の作業中にAIの反応が変わったと感じたら、まず会話がリセットされていないか確認しましょう。
新しい会話でCLAUDE.mdが読み込まれているかは、AIに「いま読み込んでいるルールを教えて」と聞くと確認できます。
返答に書いた内容が含まれていれば、適用されている状態です。
もし読み込まれていない場合は、CLAUDE.mdの保存場所が正しいかを見直しましょう。
プロジェクトのフォルダ直下に置いてあるかどうかが最初のチェックポイントです。
会話のリセット直後は、自分で簡単な動作確認をしておくと安心して作業を進められます。
Claude CodeでよくあるCLAUDE.mdの失敗パターン
CLAUDE.mdは便利な反面、書き方を誤るとかえって作業効率を下げる落とし穴もあるツールです。
よくある失敗例を先に知っておくと、自分のファイル運用でも同じ失敗を避けやすくなります。
ここでは、現場でよく見られる5つのパターンと、それぞれの回避策を紹介します。
詰め込みすぎてClaudeに無視される
CLAUDE.mdに「念のため」で大量のルールを書き連ねると、AIが情報量に押されて重要な指示まで無視してしまうことがあります。
500行・1,000行と書き続けるほど、肝心のルールが埋もれていく現象が起こりやすくなります。
回避するには、書く前に「本当にここに書く必要があるか」を一度問い直すと効果的です。
コードを見れば分かること、自動チェックツールに任せられることは外していきましょう。
書きたい欲求が出てきたときほど、「他に書く場所がないか」「省ける情報はないか」を考えるとファイルが肥大化しにくくなります。
CLAUDE.mdは「あれもこれも」ではなく、「ここだけは必ず」と思える内容に絞ることが重要です。
「〜するな」だけの否定形ルールを書いてしまう
「〇〇は使わないで」「〇〇しないで」だけを並べたCLAUDE.mdは、AIにとって判断材料が不足する書き方です。
AIは禁止されていないやり方を選んでいくため、結果的に意図しない方向に進む可能性があります。
「使わないで」と書くなら、合わせて「代わりに〇〇を使う」と肯定形のルールを並べておくのがコツです。
否定形だけだと、AIは「じゃあ何ならいいの？」を自分で推測するしかありません。
推測の幅が広いほど、提案にばらつきが出やすくなります。
「やってほしいこと」と「やらないでほしいこと」をセットで書くと、AIの提案がぶれにくくなります。
自動チェックツールの代わりに使い続ける
「コードの体裁を整える専用ツールを入れていないから、CLAUDE.mdに全部書いている」というケースがあります。
短期的にはAIが指示を守ってくれるため一見うまくいきますが、長期的には問題が増えがちです。
AIは毎回のチャットでルールをチェックするため、ファイルが長くなるほど読み込み負荷が上がります。
専用ツールなら一瞬で処理できる作業を、AIに毎回判断させるのは効率的ではありません。
体裁チェック・誤字検出・テスト実行といった「機械が自動で見られる範囲」は、それ専用のツールに任せましょう。
CLAUDE.mdは「ツールが見られない領域のルール」に絞っておく方が、両者の長所を引き出しやすくなります。
自動生成された内容をそのまま本番に使う
Claude Codeには、CLAUDE.mdを自動で作る補助機能がついている場合があります。
便利ですが、生成されたものをそのまま使うとプロジェクトの実情に合わない記述が紛れ込みがちです。
たとえば、実際には使っていないツールの設定が書かれていたり、独自のルールが反映されていなかったりします。
気づかないまま運用すると、AIが間違った前提で動いてしまいます。
自動生成は「下書きの叩き台」として使うのが基本です。
生成後に必ず内容を読み直し、不要な部分を削り、自分のプロジェクト固有のルールを書き足してから本番に使いましょう。
最初から自分の手で書く必要はありませんが、内容を確認・調整するひと手間は必ず加えるのが安心です。
全体設定に特定の作業専用の指示を入れる
「テスト用のルール」「フロントエンドのスタイル指示」のような特定作業の決まりをCLAUDE.md本体に書き込んでしまうと、関係ない作業のときにもAIがその指示を読み続けることになります。
結果として、毎回必要のない判断材料がAIに渡されて、回答が冗長になりがちです。
特定の作業専用のルールは、その作業に関連するフォルダ内に別ファイルとして置くのが基本です。
たとえばテスト用なら「tests/CLAUDE.md」のように、関連フォルダの中にCLAUDE.mdを別途用意する方法があります。
CLAUDE.mdは「いつでも効いていてほしい大枠のルール」だけにとどめ、シーン別のものは分離して整理しておくと、ファイルが肥大化せずに済みます。
CLAUDE.mdについてよくある質問
最後にCLAUDE.mdによくある質問をまとめました。
- CLAUDE.mdは無料で使えますか
-
CLAUDE.mdは普通のテキストファイルなので、作成自体は完全に無料です。
Claude Code本体の利用料金は別途必要になりますが、ファイルの設置・編集に追加費用はかかりません。
- CLAUDE.mdを書いたのにルールが守られない原因は何ですか
-
最も多い原因はファイルが長すぎてAIに読み飛ばされているケースです。
300行を超えていないか、優先度の高いルールが冒頭にあるかをまず確認しましょう。
- CLAUDE.mdとCLAUDE.local.mdではどちらが優先されますか
-
一般的にはより具体的なファイル側が優先される設計です。
両方に同じテーマのルールを書くと混乱の原因になるため、内容を重複させない運用が安全です。
- 1人で使うときもCLAUDE.local.mdは必要ですか
-
1人での運用ならCLAUDE.md1つで十分な場合がほとんどです。
後からチームに共有する可能性があるなら、最初から個人専用ルールを分けておくと切り出しが楽になります。
- CLAUDE.mdは他のAIコーディングツールでも使えますか
-
CLAUDE.mdはClaude Code向けの仕組みのため、他社のAIコーディングツールは原則として参照しません。
別ツールごとに専用の設定ファイルが用意されていることが多いです。
まとめ： CLAUDE.mdの書き方を押さえればAIへの指示が安定する
CLAUDE.mdはClaude Codeに作業ルールを伝えるための設定ファイルで、配置する場所や書く内容によってAIへの伝わり方が大きく変わります。
プロジェクト全体に効かせたい内容はチーム共有のフォルダに、個人専用のルールはCLAUDE.local.mdにと、用途で書き分けるのが基本です。
書く内容は「コードを読めば分かること」「自動チェックツールに任せられること」を外し、コードからは読み取れない方針・手順・参照先に絞ると効果が出やすくなります。
長さは60〜300行を目安にして、詰め込みすぎず、否定形ルールには対になる肯定形を添えるのがコツです。
うまく機能しないときは、ファイルの長さや会話のリセットを疑うところから見直しましょう。
CLAUDE.mdを使いこなせるようになると、毎回の指示が減り、AIとの作業がぐっと楽になります。
コメント