Claude Code CLAUDE.mdの書き方｜動作カスタマイズを自在にする実践ガイド-Next Hello

Claude Code CLAUDE.mdの書き方がよくわからず、試行錯誤しながら「これで合っているのかな？」と不安になった経験はありませんか。

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

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

CLAUDE.mdとは何か、どんな役割を持つのか
基本的な書き方のステップ（配置場所・コマンド定義・行動ルール）
実際に使ってわかった効果とハマりポイント
応用テクニック（階層配置・メモリとの組み合わせ）

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

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

ここに「CLAUDE.md」というファイルを置くと、状況が一変します。

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

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

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

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

プロジェクトの概要・目的（何を作っているのか）
開発環境・使用技術スタック（言語・フレームワーク）
よく使うコマンド一覧（ビルド・テスト・デプロイ等）
行動ルール（先にテストを書く、コメントを日本語で書く等）
禁止事項（git push --force禁止、本番環境への直接操作禁止等）

これは、新しいメンバーへの「オンボーディングドキュメント」に近い発想です。人間が読むドキュメントではなく、Claude Codeが読む「仕様書」として位置づけると、何を書くべきかがぐっとわかりやすくなります。

受け取る側がAIであっても、伝えるべき情報の質は変わりません。むしろ曖昧な表現を排除して具体的に書くほど、指示の通りが良くなります。

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

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

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

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

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

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

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

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

~/.claude/CLAUDE.md（グローバル設定：すべてのプロジェクトに適用）
プロジェクトのルートディレクトリ直下（例：/your-project/CLAUDE.md）
サブディレクトリ配下（例：/your-project/src/CLAUDE.md）

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

ファイルを作るだけで自動的に読み込まれるため、特別な設定は不要です。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の挙動が劇的に安定します。

行動ルールの例：

変更前に必ずファイルを読み込んでから編集する
テストは変更前に実行し、通過を確認してから次に進む
コミットメッセージは日本語で書く
長いコードは必ずリファクタリング案も一緒に提示する

禁止事項の例：

git push --forceの実行禁止
本番環境の設定ファイル（.env.production）への直接書き込み禁止
既存のAPIエンドポイントのURL変更禁止（破壊的変更となるため）

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

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

CLAUDE.mdを書くこと自体は難しくありませんが、書き始めると「これでいいのかな？」という疑問が浮かびやすいです。ここでは実際に使ってわかった変化と、よくある失敗パターンを整理しました。

指示が通りやすくなった具体的な変化

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

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

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

具体的に変化を感じた点をまとめると：

毎回伝えていたプロジェクト背景の説明が不要になった
エラー対処時に使用技術スタックを踏まえた的確な提案が増えた
「確認なしで進んでいい」という信頼感が生まれ、作業テンポが上がった

「書いたのに動かない」よくある失敗パターン

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

ファイルの場所が間違っている

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

書き方が曖昧すぎる

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

情報量が多すぎる

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

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

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

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

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

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

ルートのCLAUDE.mdには「プロジェクト共通のルール」を書き、各ディレクトリのCLAUDE.mdにはその領域固有の技術スタックや注意事項を書きます。

こうすることで「フロントエンドの作業をしているときに、バックエンドの設定が目に入って混乱する」という状況を避けられます。コンテキストを絞ることで、Claude Codeの判断精度も上がる感覚があります。

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

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

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

ざっくりした使い分けのイメージはこうです。

CLAUDE.md：プロジェクトの「静的な仕様書」。変わりにくいルール・コマンド・禁止事項を書く
メモリ（memory/）：進行中の作業状況や、ユーザーの好み・学習した新しいパターンを動的に記録する

この使い分けを意識するだけで、Claude Codeが「長期記憶を持ったペアプログラマー」のように機能し始めます。プロジェクト固有のパターンを覚えてくれるので、似たタスクを繰り返すたびに提案の精度が上がっていきます。

CLAUDE.mdはあくまで「最初から決まっているルール」、メモリは「使いながら育てる記録」と覚えておくと、迷わず使い分けられます。

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

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

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

最初は100〜300行程度を目安にするといいでしょう。長すぎると重要な指示が埋もれ、短すぎると効果が薄くなります。「このプロジェクトに初めて参加した人間が読んで、3分で概要がつかめる分量」を目安にすると書きやすいです。書いているうちに「これは不要かな」と気づく部分が出てくるので、定期的に見直して削ることも大切です。

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

~/.claude/CLAUDE.md（ホームディレクトリのグローバル設定）に書くといいでしょう。たとえば「Gitのコミットメッセージは必ず日本語で書く」「rm -rfの実行前に必ず確認を求める」などのルールはグローバルに設定しておくと便利です。プロジェクトごとのCLAUDE.mdと組み合わせて使えるため、共通ルール＋個別ルールの二重管理が実現できます。

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

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

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

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

プロジェクト概要・コマンドを書いて「毎回言わなくていい状態」を作る
行動ルール・禁止事項を具体的に書いて「誤操作を防ぐ仕組み」を作る
階層配置とメモリを組み合わせて、長期的な精度向上を狙う

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

書くたびに「あ、これも書いておけばよかった」という気づきが生まれ、自然と精度が上がっていきます。育てていくものだと思えば、最初のクオリティへの気負いも軽くなります。

あなたのプロジェクトに、最初に書き込むルールは何でしょうか。

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