🤖

【Claude Code】CLAUDE.md運用のベストプラクティス：失敗しないための7つの原則

に公開
AI
Productivity
llm
Claude
bestpractices
tech

Claude Code のパフォーマンスを最大化する鍵は、実は CLAUDE.md の設計にあります。
しかし、「なんとなく情報を詰め込んでいるだけ」になってしまってはいないでしょうか？

良かれと思ってルールを増やしすぎた結果、かえって AI の混乱を招き、指示が無視される――。
これは多くの開発者が直面する「コンテキスト汚染」の典型例です。

この記事では、そんな「悪い CLAUDE.md」と「良い CLAUDE.md」の違いを整理しながら、LLMの研究やコンテキストエンジニアリングの観点に基づいた、現場で使える書き方・設計のポイントをまとめます。

🚨 なぜ多くの CLAUDE.md は失敗するのか

よくある失敗パターンは次のようなものです。

  • 情報量が多すぎて、LLM が処理しきれない 🤯
  • 実務に関係ない「好みのコードスタイル」まで全部詰め込んでいる
  • /init などで自動生成した、誰もメンテしない長文ドキュメントになっている

LLM は一度に安定して扱える「ルールの数」に限界があります。指示が増えれば増えるほど、守られない指示が出てきてしまいます。
「なんか最近 Claude の精度が悪いな...」と思ったら、まず CLAUDE.md を疑ってみる価値がありますよ！

📏 原則1: CLAUDE.md は「小さく・絞って」書く

📉 行数と情報量の目安

推奨されるのは、 できるだけ小さい CLAUDE.md です。

  • 目安は 300 行以下
  • 指示としては 150〜200 個程度 に収める

これ以上増やしても、人間にとっても LLM にとっても扱いにくく、重要な情報が埋もれがちです。

LLM のコンテキストウィンドウは、人間の 「作業メモリ（ワーキングメモリ）」 に似ています。不要な情報でメモリを埋め尽くしてしまうと、本当に重要なタスクに割けるリソースが減り、推論能力の低下を招きます。これを「コンテキストエンジニアリング」の視点で最適化することが重要です。

🤖 /init や自動生成に頼りすぎない

Claude に「このリポジトリから CLAUDE.md を作って」と指示して自動生成させると、冗長でノイズの多いドキュメントになりやすいです。
結果として「全部書いてあるけど、どれも守られない」という状態になりがちなので、 /init ベースの生成は基本的に避けたほうがよい、とされています。

🎨 原則2: コードスタイルはツールに任せる

CLAUDE.md に次のような内容を書いていないでしょうか？

  • インデントは 2 スペースにして
  • シングルクオートを使って
  • import 順序はこうしてほしい

こうした「フォーマット・スタイル」の指示は、Lint や Formatter、Git hooks（pre-commit / post_tool_use など）で機械的に強制する方が確実です。
CLAUDE.md に載せるべきなのは、「スタイル」ではなく 「プロジェクト固有の知識・罠・運用ルール」 です。

💎 原則3: すべてのプロジェクトに共通で入れるべき3要素

どんなプロジェクトでも、有効に機能しやすいのは次の 3 つです。

1. プロジェクトを一行で説明する

Claude がリポジトリ全体を読む前に、 一発で全体像が掴める一文 があると、タスク理解がぐっと安定します。

2. 日常的によく使うコマンド

ここに書くのは「頻繁に使うもの」に絞ります。

  • アプリの起動・ビルド・テスト・Lint
  • よく使うスクリプト（DB マイグレーションなど）

記述例:

## Commands

- 開発サーバー: `pnpm dev`
- テスト: `pnpm test`
- Lint: `pnpm lint`
- Prisma マイグレーション: `pnpm prisma migrate dev`

これだけでも、Claude が「どうやってローカルで動かすか」「CI が何をしているか」を正しく推測しやすくなります。

ここでのポイントは、単に禁止事項を並べるのではなく、 「トリガー（いつ）」と「アクション（何をするか）」 をセットで記述することです。

  • × 悪い例: schema.prisma の直接編集は禁止。
  • ○ 良い例: schema.prisma を変更したいときは、必ず schema/*.prisma を編集してから pnpm build:schema を実行すること。

人間の新メンバーに「最初に知っておいてほしいことリスト」を渡すイメージで、Claude にもその 地雷マップ を共有してあげましょう。具体的な行動指示（Actionable）にすることで、遵守率が劇的に向上します。

📂 原則4: 情報は「段階的に開示」する

CLAUDE.md にすべてを書ききる必要はありません。
むしろ、詳細な情報（DB スキーマ、API 一覧、ビジネスルールなど）は別ファイルに分け、Claude には「必要になったら読ませる」方がうまくいきます。

種類 ファイルパス例
DB スキーマ docs/schema.md
API ドキュメント docs/api.md
複雑なドメインルール docs/domain-rules.md

CLAUDE.md には、これらの場所と概要だけを書いておき、タスクに応じて追加のファイルを開かせる、という「 progressive disclosure（段階的開示） 」の設計が推奨されます。

🧠 原則5: Claude が指示を無視する理由を理解する

Claude Code のシステムメッセージには、「 CLAUDE.md の文脈はタスクと無関係な場合がある」という前提が含まれています。
そのため、Claude は状況によって CLAUDE.md の一部を意図的に無視することがあります。

さらに LLM は、入力の先頭と末尾をより強く重み付ける傾向があります。

  1. 先頭: システムメッセージ + CLAUDE.md の冒頭
  2. 末尾: 直近のユーザープロンプト

この特性を踏まえると、 本当に守ってほしいことは CLAUDE.md の冒頭に書く のが効果的です。
「IMPORTANT」「Read this first」などで明示的に強調するのも有効ですよ！

💾 原則6: CLAUDE.md は「長期記憶」として扱う

Claude Code を使っていると、動作が不安定になったときに /clear コマンドで会話履歴をリセットすることがあります。
このとき、チャットログ（短期記憶）は消えますが、CLAUDE.md （長期記憶）は読み直されます。

  • 短期記憶（Chat Log）: タスクごとに使い捨てられる。不安定になりやすい。
  • 長期記憶（CLAUDE.md）: 常に維持される唯一の拠り所。

「毎回同じことを説明しているな」と感じたら、それは短期記憶にしか情報がない証拠です。すぐに CLAUDE.md という 長期記憶 に書き込みましょう。これにより、セッションをリセットしても賢い状態を即座に復元できます。

🌱 原則7: CLAUDE.md は「生きたドキュメント」として育てる

CLAUDE.md は一度書いて終わりの静的なドキュメントではなく、開発とともに育てていくべきです。

例えば、次のようなタイミングでアップデートしていきます。

  • Claude が誤ったフレームワークや API を選んでしまった
  • 開発中に新しい「罠」や注意点に気づいた
  • ワークフローやコマンドが変わった

「AI が何度も同じミスをしている」と感じたら、その都度 CLAUDE.md に一行追加するぐらいの軽さで、継続的にメンテするのが理想ですね。

🏠 原則8: 置き場所とスコープ設計

Claude Code は、プロジェクトルートだけでなく、親ディレクトリ・サブディレクトリの CLAUDE.md も自動で探索します。
これを利用すると、モノレポなどで次のような構成にできます。

  • リポジトリルート: 全体共通のルール・方針
  • 各パッケージ配下: そのサービス固有のルール・罠

さらに、個人用の設定はリポジトリにはコミットせず、 claude.local.md に書いて .gitignore に入れる運用も紹介されています。
すべてのプロジェクトに共通する「自分の好み」は、ホームディレクトリの ~/.claude に書いておくことで、全セッションに適用できます。

✅ まとめ: 良い CLAUDE.md のチェックリスト

最後に、手元の CLAUDE.md を見直すときのチェックリストを置いておきます。

  • 300 行以内、指示は 150〜200 個程度に収まっているか
  • /init などの自動生成頼みになっていないか
  • コードスタイルやフォーマットの好みを書いていないか（Lint / Formatter に任せているか）
  • 冒頭に「プロジェクトの一行説明」があるか
  • よく使うコマンドだけが整理されているか
  • プロジェクト特有の「罠」「注意点」がトリガーと行動（If X, then Y）形式で書かれているか
  • 詳細情報は docs 配下などに分離し、CLAUDE.md では場所だけ案内しているか
  • 本当に重要なルールは冒頭に書かれているか
  • /clear しても失われない「長期記憶」として必要な情報が網羅されているか
  • 直近の開発で気づいたことが反映されているか

このあたりを満たしていれば、「AI にとっても人間にとっても読める CLAUDE.md」になっているはずです。

ぜひ、あなたのプロジェクトの CLAUDE.md も見直してみてくださいね！🚀

Discussion