Claude Code CLAUDE.mdの書き方｜動作カスタマイズを自在にするコツ

「Claude Code CLAUDE.mdの書き方がよくわからず、自己流のまま使っていませんか?」
「CLAUDE.mdを正しく設定して、毎回同じ指示を出す手間を減らしたい!」

実は、CLAUDE.mdは正しいフォーマットと最新の機能を知ってしまえば、プロジェクトごとの指示を「仕様書」として残せる強力なツールになります。

この記事では、以下の内容を解説します。

CLAUDE.mdとは何か——Claude Codeが読む「仕様書」の正体

Claude CodeはAIによるコーディング支援ツールですが、デフォルトのままだと「どんなプロジェクトでも同じ振る舞いをする汎用AIアシスタント」でしかありません。

ここでは、以下の内容について詳しく解説します。

プロジェクトごとにClaude Codeの動作を変えるしくみ

ここに「CLAUDE.md」というファイルを置くと、状況が一変します。CLAUDE.mdは、Claude Codeが起動時に自動的に読み込む特別なMarkdownファイルです。「このプロジェクトではこう動いてほしい」という指示を事前に書いておくことで、毎回同じことを伝えなくて済む仕組みになっています。

Claude CodeはCLAUDE.mdをプロジェクトのコンテキストとして取り込み、会話のたびに参照するため、「いつも最初にやること」「使ってほしいコマンド」「禁止したい操作」などを一度書いておけば、毎回の指示が不要になります。

具体的には次のような情報を書くと効果的です。

これは、新しいメンバーへの「オンボーディングドキュメント」に近い発想です。人間が読むドキュメントではなく、Claude Codeが読む「仕様書」として位置づけると、何を書くべきかがぐっとわかりやすくなります。受け取る側がAIであっても、伝えるべき情報の質は変わりません。むしろ曖昧な表現を排除して具体的に書くほど、指示の通りが良くなります。

なぜCLAUDE.mdを書くと作業効率が上がるのか

CLAUDE.mdを書く前は、毎回「このプロジェクトのテストはこのコマンドです」「ファイルはここに保存してください」などを都度伝えていました。これが積み重なると会話のコンテキストが長くなり、重要な指示がAIに見落とされやすくなります。

CLAUDE.mdに書いた情報はセッション開始時に必ず読み込まれるため、「伝え忘れ」がなくなります。私の場合、CLAUDE.mdを書いてから「なんでまたそこを変えるんだ」という誤操作が明らかに減りました。

コストパフォーマンスという観点からも、同じ説明を毎回入力するトークンが削減されるため、長期的な効率化につながります。書く手間は最初の30分だけで、以後はずっと恩恵を受け続けられます。料理で例えるなら、毎回レシピを見ながら作るより「自分専用のレシピノート」を一冊作ってしまうほうが、長期的には圧倒的に楽——そういった感覚に近いです。

Claude Code CLAUDE.mdの基本的な書き方4つのステップ

実際に手を動かして書いてみましょう。難しく考える必要はありません。まずは4つのステップを押さえれば十分機能します。

ここでは、以下の内容について詳しく解説します。

ステップ1：ファイルを置く場所と読み込まれる順序

CLAUDE.mdはMarkdownファイルなので、テキストエディタで作成できます。置く場所には優先順位があり、Claude Codeは以下の順番で読み込みます。

最初はプロジェクトルートにひとつ置くだけで十分です。グローバル設定は「どのプロジェクトでも共通のルール」（例：コミットメッセージの書き方、絶対にやってはいけない操作等）に使うと重宝します。

ファイルを作るだけで自動的に読み込まれるため、特別な設定は不要です。Claude Codeを起動したとき、すでに有効化されている状態になります。一点だけ注意したいのが「Claude Codeをどのディレクトリで起動したか」という点です。ルートに置いたつもりが、サブディレクトリで起動していると読み込まれないことがあります。迷ったら、起動したディレクトリと同じ階層にファイルがあるかを確認してみましょう。

ステップ2：プロジェクト概要・使用コマンドを書く

CLAUDE.mdの核となる情報は「プロジェクト概要」と「よく使うコマンド」です。以下のような構成で書き始めると迷いにくいでしょう。

## プロジェクト概要



ECサイトのバックエンドAPI（Laravel + MySQL）。
注文管理・在庫管理・ユーザー認証機能を担う。



## 開発コマンド



- ローカルサーバー起動：php artisan serve
- テスト実行：php artisan test
- マイグレーション：php artisan migrate
- コード整形：vendor/bin/pint

ポイントは「Claude Codeが迷わないよう、曖昧さをなくすこと」です。「テストを実行して」と伝えたときに何を実行すべきか、CLAUDE.mdを見れば一目でわかる状態にしておきます。

使用技術スタック（言語バージョン・主要ライブラリ）も書いておくと、ライブラリ選定や記述スタイルの提案が的外れにならなくなり、バージョンが古いライブラリの書き方で提案されて「これ動かないんだけど……」となる場面も減らせます。

ステップ3：行動ルールを定義する

コマンド定義の次は「どう動いてほしいか」のルールです。ここが書けると、Claude Codeの挙動が劇的に安定します。

行動ルールは「何をしてほしいか」ではなく「どのように動いてほしいか」を書くイメージを持つと、書きやすくなります。抽象的な期待ではなく、判断基準として機能する具体的な行動として書くのがコツです。

たとえば「品質を意識してください」と書いても、何を指すのかClaude Codeには伝わりません。「関数を追加したら必ずユニットテストも追加する」「エラーハンドリングは例外を握りつぶさず、必ずログに出力する」のように、具体的な振る舞いとして書き下すことで、初めて判断基準として機能します。行動ルールは一度にすべて揃える必要はなく、Claude Codeとやり取りする中で「これも書いておけばよかった」と感じた場面から少しずつ追記していけば十分です。

ステップ4：禁止事項を定義する

行動ルールとセットで、必ず書いておきたいのが禁止事項です。ここを明示するだけで、Claude Codeが判断に迷う場面で自ら止まってくれるようになります。

「禁止」を明示することで、判断に迷う状況でClaude Codeが自ら止まってくれるようになります。私の感覚では、禁止事項の記載が一番費用対効果の高いセクションです。「まずここだけ書いてみて」と勧めるとしたら、禁止事項一覧を真っ先に挙げます。

/initコマンドでCLAUDE.mdを自動生成する方法

ここまでは手書きでCLAUDE.mdを作る方法を紹介しましたが、Claude Codeには/initというコマンドが用意されており、ゼロから書かなくてもたたき台を自動生成できます。

ここでは、以下の内容について詳しく解説します。

/initコマンドの使い方と生成される内容

Claude Codeのプロジェクトディレクトリで対話モードを起動し、/initと入力するだけで実行できます。

$ claude
> /init

実行すると、Claude Codeが現在のプロジェクトを解析し、README・package.json・pyproject.tomlなどの設定ファイルを読み込んでビルド・テスト・実行コマンドを推定し、あわせてディレクトリ構成を要約したうえでプロジェクト概要・コマンド一覧を含んだCLAUDE.mdの雛形を自動生成します。

手作業でゼロから書く場合と比べて、プロジェクトの棚卸しにかかる時間が大幅に短縮できるのが魅力です。特に、他人が作ったプロジェクトを引き継いだときや、しばらく触っていなかった過去のプロジェクトに戻ってきたときほど、恩恵を感じやすいでしょう。

ゼロから書き始めるのが面倒なとき、まず/initを実行してからステップ3・4で紹介した行動ルールや禁止事項を手で追記する、という流れが最も効率的です。手書きと自動生成を組み合わせることで、書く手間を最小限にできます。

既存のCLAUDE.mdがある場合は上書きされず改善提案になる

すでにCLAUDE.mdを書いた状態で/initを実行すると、既存のファイルをいきなり上書きすることはありません。代わりに、現在の内容を踏まえたうえで「ここを補強すると良さそうです」という改善提案を提示するモードに切り替わります。

この挙動のおかげで、育ててきたCLAUDE.mdを壊す心配なく定期的に/initを実行して内容を見直せるため、プロジェクトが成長してコマンドや構成が変わったタイミングでも書き漏れに気づきやすくなります。

特に効果を感じるのは、フレームワークのバージョンアップやディレクトリ構成の変更があったタイミングです。手作業でCLAUDE.mdを直すのは忘れがちですが、/initを実行すればコマンドや構成の変化をClaude Code自身が拾い直してくれるため、「CLAUDE.mdだけが古いまま」という状態を防ぎやすくなります。四半期に一度など、決まったタイミングで実行する習慣にしておくと安心です。

自動生成後に必ず手直しすべき3つのポイント

/initで生成された内容は、そのまま使うにはやや粗い状態です。公開前に必ず次の3点を手直ししましょう。

/initはあくまで「たたき台」を作る機能です。プロジェクト固有の判断基準や禁止事項までは推測できないため、この記事のステップ3・4で紹介した内容を必ず自分の手で追記してください。

実際に書いてわかったCLAUDE.mdの効果とハマりポイント

CLAUDE.mdを書くこと自体は難しくありませんが、書き始めると「これでいいのかな？」という疑問が浮かびやすいです。

ここでは、以下の内容について詳しく解説します。

指示が通りやすくなったと実感した変化

CLAUDE.mdを書いてから最も効果を感じたのは、「毎回言わなくていいことが増えた」という点です。

たとえば「テストを書いてから実装する」という行動ルールをCLAUDE.mdに書いておくと、実装を頼んだときにClaude Code側から「先にテストケースを確認していいですか？」と提案してくれるようになりました。こちらから指示しなくても、CLAUDE.mdを読んで先回りして動いてくれる感覚があります。

コマンドを書いておいたことで「このプロジェクトのビルドコマンドは何ですか？」という確認も一切なくなりました。聞かれるたびに答える手間はわずかでも、積み重なるとセッション全体のリズムが崩れます。

「書いたのに動かない」ときによくある3つの原因

CLAUDE.mdを書いたのに指示が反映されないと感じるときは、たいてい以下のどれかが原因です。

プロジェクトルートに置いたつもりが、サブディレクトリに置いてしまっているケースが多いです。Claude Codeを起動したディレクトリと、CLAUDE.mdを置いたディレクトリが一致しているかを確認しましょう。

「丁寧に対応してください」「効率よく作業してください」のような抽象的な指示はほぼ機能しません。「コメントを日本語で書く」「変更前にReadツールで必ずファイルを読む」のように、具体的な動作として書くことが重要です。

CLAUDE.mdに書けば書くほどいい、というわけではありません。優先度の低い情報まで詰め込むと、重要なルールが埋もれてしまいます。まずは「これがなかったら困る」情報だけに絞って書くのがコツです。後から追加は簡単にできるので、最初は薄くて大丈夫です。

CLAUDE.mdの遵守率を上げる書き方のコツ

ここまでの内容を実践しても「なぜかルールを無視される」と感じることがあります。公式ドキュメントや実践者の知見をもとに、CLAUDE.mdの遵守率を上げる書き方のコツを紹介しましょう。

ここでは、以下の内容について詳しく解説します。

説明形ではなく命令・禁止形で書く

同じルールでも、書き方によってClaude Codeの遵守率は変わります。「〜すること」という説明形よりも、「〜は禁止」「〜せよ」という命令・禁止の形で書くほうが、ルールとして強く認識される傾向があります。

たとえば「データベースへの直接アクセスは避けましょう」という説明形より、「データベースへの直接呼び出しは禁止。必ずリポジトリ層を経由すること」という命令・禁止形のほうが、実際の遵守率が高くなります。この記事のステップ4で紹介した禁止事項も、この形式を意識して書いています。

テストコマンドについても同様で、「テストを書いてください」だけでなく「コミット前に必ずnpm testを実行する」のように、実行するタイミングまで添えて書くのが公式でも推奨されている書き方です。「何を」だけでなく「いつ」までセットで書くと、行動として実行されやすくなります。

200行を超えると効果が薄れる

CLAUDE.mdは長く書けば書くほど効果的というわけではありません。Claude Code公式のベストプラクティスでも触れられているとおり、1ファイルあたり200行程度に収めることが目安とされています。

200行を大きく超えると、重要なルールが埋もれてコンテキストの中で見落とされやすいでしょう。「/init後に手直しすべきポイント」でも触れたとおり、情報を詰め込むより、優先度の高いルールだけを残して定期的に整理するほうが、結果的に遵守率が高い状態を保てます。

行数だけでなく、セッション全体でコンテキストがどれだけ埋まっているかも合わせて見ておくと、削る判断がしやすくなります。数字で把握する方法はClaude Codeのコンテキスト枯渇対策｜劣化を防ぐ削り方で解説しています。

行数が増えてきたら、次章で紹介する@import構文を使って、詳細なコーディング規約やAPI仕様を別ファイルに切り出すのも有効な対処法です。CLAUDE.md本体には「本当に外せない指示」だけを残し、参照頻度の低い詳細情報は別ファイルに逃がすという役割分担を意識すると、200行の目安を守りながら情報量も確保できます。

ESLint・Prettier等の既存設定と重複させない

CLAUDE.mdに書くべきなのは、Claude Codeがコードベースを読んでも知ることができない「プロジェクト固有のルール」です。

ESLintやPrettier、tsconfig.jsonがすでに管理しているコーディング規約（インデント幅・クォートスタイル・any禁止等）は、Claude Codeが設定ファイルを直接読めば把握できるため、CLAUDE.mdに重複して書く必要はありません。むしろ重複を避けることで、本当に伝えたい固有ルールにスペースを割けます。

上級者が使うCLAUDE.mdの応用テクニック

基本的な書き方ができたら、次のステップを試してみてください。CLAUDE.mdの可能性がもう一段広がります。

MCPとCLAUDE.mdを組み合わせてさらに拡張したい方は、「Claude CodeのMCP設定方法を詳しく解説！」もあわせてご覧ください。

ここでは、以下の内容について詳しく解説します。

階層配置——ルートと各フォルダに分けて管理する方法

大規模なプロジェクトでは、CLAUDE.mdを複数のフォルダに分けて配置すると管理しやすくなります。フォルダの役割ごとに「ここでは何を優先するか」を分けて書けるからです。

project-root/
├── CLAUDE.md          ← プロジェクト全体のルール
├── frontend/
│   └── CLAUDE.md      ← フロントエンド固有のルール
└── backend/
    └── CLAUDE.md      ← バックエンド固有のルール

ルートのCLAUDE.mdには「プロジェクト共通のルール」を書き、各ディレクトリのCLAUDE.mdにはその領域固有の技術スタックや注意事項を書きます。こうすることで「フロントエンドの作業をしているときに、バックエンドの設定が目に入って混乱する」という状況を避けられるでしょう。コンテキストを絞ることで、Claude Codeの判断精度も上がる感覚があります。

デメリットとしては、ファイルが分散するため「どこに何を書いたか」の管理コストが生まれます。プロジェクトが小規模なうちはルートひとつで十分で、規模が大きくなってから分割を検討するほうがいいでしょう。

@import構文で他のMarkdownファイルを読み込む方法

CLAUDE.mdには、@path/to/fileという構文で別のMarkdownファイルを読み込む「@import構文」が用意されています。CLAUDE.mdの本文に直接書くのではなく、詳細を別ファイルに切り出して参照する形にできる機能です。

## コーディング規約



詳細は @docs/coding-style.md を参照してください。



## APIの仕様



エンドポイント一覧は @docs/api-spec.md を参照してください。

インポートされたファイルは、参照元のCLAUDE.mdとあわせて起動時に展開され、コンテキストに読み込まれます。長くなりがちな規約やAPI仕様を別ファイルに分離しつつ、CLAUDE.md自体は前章で触れた200行のガイドラインに収めやすくなるのが利点です。

CLAUDE.local.mdで個人用の設定を分離する方法

チームでプロジェクトを共有していると、「自分だけのローカル環境の設定」までCLAUDE.mdに書きたくなる場面が出てきます。そんなときに使えるのがCLAUDE.local.mdです。

CLAUDE.local.mdはプロジェクトルートに置く個人用のファイルで、CLAUDE.mdと同様にClaude Codeが自動的に読み込みます。.gitignoreに加えておくことで、チームには共有されない個人専用の設定として運用できます。

チーム共有のCLAUDE.mdには「全員に関係するルール」だけを残し、個人的な好みや一時的な設定はCLAUDE.local.mdに逃がす、という使い分けを意識すると、CLAUDE.mdが余計な情報で膨らむのを防げます。

CLAUDE.md以外の設定もまとめてチーム全体へ配りたくなったら、Claude Codeのチーム設定共有｜属人化を資産に変えようが参考になります。

CLAUDE.md×メモリシステムの組み合わせ

Claude Codeには「メモリ」と呼ばれる機能があり、会話をまたいで情報を保持できます。CLAUDE.mdとメモリを組み合わせると、さらに強力な使い方ができます。

この使い分けを意識するだけで、Claude Codeが「長期記憶を持ったペアプログラマー」のように機能し始めます。プロジェクト固有のパターンを覚えてくれるので、似たタスクを繰り返すたびに提案の精度が上がっていくでしょう。CLAUDE.mdはあくまで「最初から決まっているルール」、メモリは「使いながら育てる記録」と覚えておくと、迷わず使い分けられます。

Claude Codeの全体的な使い方に興味がある方は、Claude Codeの使い方まとめ｜初心者向けに詳しく解説も参考にしてみてください。CLAUDE.mdを含む全体のセットアップ手順から丁寧に解説しています。

Claude Code CLAUDE.mdに関するよくある質問

Q：CLAUDE.mdはどのくらいの長さが適切ですか？

A：最初は100〜300行程度を目安にするといいでしょう。長すぎると重要な指示が埋もれ、短すぎると効果が薄くなります。「このプロジェクトに初めて参加した人間が読んで、3分で概要がつかめる分量」を目安にすると書きやすいです。書いているうちに「これは不要かな」と気づく部分が出てくるので、定期的に見直して削ることも大切です。行数が膨らんできたら、詳細部分を@import構文で別ファイルに切り出すことも検討してみてください。

Q：複数プロジェクトで共通ルールを使いたい場合は？

A：~/.claude/CLAUDE.md（ホームディレクトリのグローバル設定）に書くといいでしょう。たとえば「Gitのコミットメッセージは必ず日本語で書く」「rm -rfの実行前に必ず確認を求める」などのルールはグローバルに設定しておくと便利です。プロジェクトごとのCLAUDE.mdと組み合わせて使えるため、共通ルール＋個別ルールの二重管理が実現できます。フリーランスで複数のクライアント案件をかけ持ちしている場合も、グローバル設定に自分の作業スタイルを書いておけば、案件ごとに毎回同じ説明を繰り返す必要がなくなります。

Q：CLAUDE.mdを更新したら即座に反映されますか？

A：既存のセッション（会話）が進行中の場合は、次のセッション開始時に反映されます。現在進行中のセッションへの即時反映は基本的にされないため、重要な変更を加えたあとは一度セッションを終了して再起動するのがおすすめです。「書いたのに変わらないな……」と感じたら、まずセッションの再起動を試してみてください。禁止事項を追加したのに反映されていないように見える場合は、たいていこのセッション再起動忘れが原因です。

Q：/initコマンドを使えば、自分でCLAUDE.mdを書く必要はなくなりますか？

A：完全にはなくなりません。/initはプロジェクトの構成やコマンドを解析して雛形を作ってくれますが、禁止事項や行動ルールのようなコードから読み取れない情報までは推測できません。まず/initで下地を作り、そのうえでこの記事のステップ3・4の内容を手で追記する、という流れが最も効率的です。すでにCLAUDE.mdがある場合も上書きされず改善提案モードになるので、定期的な棚卸しに使うのもおすすめです。

Q：@import構文は何階層まで読み込めますか？

A：インポートされたファイルがさらに別のファイルをインポートする、という形で最大4ホップまで再帰的に読み込めます。パスは、実行しているディレクトリではなく「@importと書いたファイル自体」からの相対で解決される点に注意してください。相対パスの解決を勘違いしたまま使うと、意図したファイルが読み込まれずに終わることがあるため、迷ったときは絶対パスで指定すると安全です。

Claude Code CLAUDE.mdの書き方まとめ

CLAUDE.mdはClaude Codeを「自分専用のAIアシスタント」に育てるための土台です。

最初から完璧を目指す必要はありません。まず「コマンド一覧だけ書いたCLAUDE.md」か、/initで生成した雛形を作ってみてください。

書くたびに「あ、これも書いておけばよかった」という気づきが生まれ、自然と精度が上がっていきます。育てていくものだと思えば、最初のクオリティへの気負いも軽くなります。あなたのプロジェクトに、最初に書き込むルールは何でしょうか。

Claude Codeを使いこなす力は、そのまま「AIを業務に組み込める人」の市場価値につながります。独学で埋めきれない部分を講座で補いたい方は、社会人におすすめの生成AI研修スクール｜スクール6校を比較が判断材料になります。