CLAUDE.md が反映されない・無視される問題を完全解決するトラブルシューティングガイド

CLAUDE.md が効かない！よくある症状と原因

Claude Code を使い始めると、多くの人が「CLAUDE.md に書いたはずの指示が無視される」「コーディング規約を設定したのに守ってくれない」という経験をします。CLAUDE.md はプロジェクトの指示書として強力なツールですが、いくつかのよくある落とし穴があります。

主な症状としては次のようなものがあります。

設定したコーディング規約が守られない
プロジェクト固有の指示（ライブラリ名・命名規則など）を Claude Code が無視する
セッションをまたいでも記憶が引き継がれない
グローバル設定とプロジェクト設定が混在して予期しない動作をする

これらの症状は原因ごとに対処法が異なります。順番に確認していきます。

原因1：CLAUDE.md のファイル配置場所が違う

最も多い原因がこれです。CLAUDE.md は Claude Code を起動したディレクトリのルート に置く必要があります。よくある間違いをまとめます。

# ❌ よくある間違い例
~/Projects/my-app/src/CLAUDE.md        # src/ 配下に置いている
~/Projects/my-app/docs/CLAUDE.md       # docs/ 配下に置いている
~/Projects/my-app/.claude/CLAUDE.md    # .claude/ フォルダ内に置いている
 
# ✅ 正しい配置
~/Projects/my-app/CLAUDE.md            # プロジェクトルートに置く

確認コマンドはシンプルです。

# Claude Code を起動するディレクトリで確認
ls -la | grep CLAUDE
# → CLAUDE.md が表示されれば OK

Claude Code を cd ~/Projects/my-app && claude のように起動している場合、CLAUDE.md は ~/Projects/my-app/CLAUDE.md でなければなりません。サブディレクトリから起動している場合は、そのサブディレクトリに CLAUDE.md を置くか、起動ディレクトリを変更してください。

原因2：CLAUDE.md の書式・フォーマットに問題がある

CLAUDE.md はマークダウン形式で記述します。しかし「書いてあるのに効かない」という場合、指示の書き方が原因のことがあります。

効果が出やすい書き方のポイントを紹介します。

# ✅ 明確で効果的な書き方
 
## コーディング規約
- TypeScript を使う（JavaScript は禁止）
- 関数名はキャメルケース（例: getUserData）
- コメントは日本語で書く
- エラーハンドリングは必ず try-catch で行う
 
## 禁止事項
- console.log をコミットしない
- any 型の使用禁止
- テストなしでの実装禁止
 
## このプロジェクトについて
Next.js 15 + TypeScript + Supabase の SaaS アプリ。
src/lib/ にユーティリティ関数を集約する設計。

# ❌ 効果が出にくい書き方（あいまいな表現）
 
コードはきれいに書いてください。TypeScript を使ってください。
エラー処理もちゃんとやってください。テストも書いてください。

ポイントは 箇条書き・見出し・具体的な例 を使うことです。曖昧な表現よりも、「〜する」「〜しない」という断定的な指示のほうが Claude Code に正しく伝わります。

また、ファイルが大きすぎると読み込みが不完全になることがあります。目安として 500行以内 に収めることを推奨します。500行を超える場合は、重要な指示を上部に集約し、補足情報は別ファイルに分けるか、記述を簡潔にまとめましょう。

原因3：グローバル設定とプロジェクト設定の混乱

CLAUDE.md には3つの階層があります。

グローバル設定（~/.claude/CLAUDE.md）: すべてのプロジェクトに適用
プロジェクト設定（{プロジェクトルート}/CLAUDE.md）: そのプロジェクトのみに適用
サブディレクトリ設定（{サブディレクトリ}/CLAUDE.md）: そのサブディレクトリでの作業時に追加適用

問題が起きやすいのは、グローバル設定とプロジェクト設定が矛盾しているケースです。

# グローバル設定の場所を確認
cat ~/.claude/CLAUDE.md
 
# プロジェクト設定の場所を確認
cat ./CLAUDE.md

たとえばグローバル設定に「コメントは英語で書く」と書いてあり、プロジェクト設定に「コメントは日本語で書く」と書いてあると、どちらが優先されるか混乱します。基本的にプロジェクト設定がより具体的な指示として優先されますが、競合を避けるためにグローバル設定は最小限にとどめ、プロジェクト固有の設定はプロジェクト CLAUDE.md に集約することを推奨します。

原因4：Claude Code を起動したままでの CLAUDE.md 変更

Claude Code のセッションが起動中に CLAUDE.md を編集しても、変更がそのセッションには反映されないことがあります。CLAUDE.md はセッション開始時に一度読み込まれます。

対処法は簡単です。

# CLAUDE.md を編集したら、Claude Code を再起動する
# 現在のセッションを終了（Ctrl+C または exit）
exit
 
# 再度起動する
claude

あるいは、Claude Code 内で /clear コマンドを実行すると、コンテキストがリセットされ、CLAUDE.md が再読み込みされる場合があります（バージョンによって動作が異なります）。確実に反映させたい場合は再起動が確実です。

原因5：コンテキスト圧縮で指示が薄れる

長時間の作業でコンテキストウィンドウが満杯に近づくと、Claude Code は自動的に古いコンテキストを圧縮（compaction）します。このとき CLAUDE.md の内容は通常保持されますが、セッションが長くなるにつれて指示の優先度が低下することがあります。

この場合の対処法は以下の通りです。

# 長いセッション中に設定を再確認させる
# Claude Code へのメッセージ例:
# "CLAUDE.md の指示を再度確認して、以降の作業に反映してください。"
 
# または /compact コマンドで手動でコンテキストを整理する
/compact
 
# 新しいセッションを開始する（最も確実）
/new

重要な指示は CLAUDE.md の冒頭に置くことで、コンテキスト圧縮後も優先的に保持されやすくなります。

チェックリストで原因を素早く特定する

CLAUDE.md が効かないと感じたら、次の順番で確認してください。

Step 1: ファイルの存在確認

ls -la $(pwd)/CLAUDE.md
# → ファイルが存在しなければ作成または移動する

Step 2: 内容の確認

cat CLAUDE.md | head -50
# → 重要な指示が上部にあるか確認

Step 3: グローバル設定との競合確認

cat ~/.claude/CLAUDE.md 2>/dev/null || echo "グローバル設定なし"
# → プロジェクト設定と矛盾がないか確認

Step 4: Claude Code の再起動

# 変更後は必ず再起動
exit && claude

これらを順番に確認することで、ほとんどのケースで原因を特定できます。

全体を振り返って

CLAUDE.md が反映されない問題の原因は大きく5つです。ファイルの配置場所、書き方の明確さ、グローバル設定との競合、セッション再起動の忘れ、そしてコンテキスト圧縮による指示の希薄化です。

チェックリストに沿って順番に確認することで、多くの場合すぐに原因を特定できます。CLAUDE.md を正しく機能させることで、Claude Code がプロジェクトのルールをきちんと理解した状態で作業してくれるようになり、開発効率が大きく向上します。

CLAUDE.md のさらに詳しい書き方や活用方法については、CLAUDE.md と AGENTS.md 完全ガイドもあわせてご覧ください。