目次
概要
Claude Codeを使っていて「毎回同じ説明を繰り返している」と感じたことはないでしょうか。プロジェクトの技術スタックやコーディング規約を、セッションのたびに一から伝えるのは非効率です。そこで活用したいのが「CLAUDE.md」というファイルです。プロジェクトのルートやディレクトリに置いておくと、セッション開始時に自動で読み込まれ、いわば「AIへの取扱説明書」として機能してくれます。
WHAT・WHY・HOWの3視点で構成する
効果的なCLAUDE.mdの型として広く紹介されているのが、WHAT(何をするプロジェクトか)、WHY(なぜそのルールがあるのか)、HOW(具体的にどう実装するか)という3つの視点で構成するという考え方です。単にルールを羅列するのではなく、「なぜそのルールが必要なのか」という背景まで書いておくことで、AIがルールの意図を理解した上で応用の効いた判断をしやすくなるようです。
1ファイルは約200行以内を目安に
もうひとつの重要な指針が、行数の目安です。CLAUDE.mdは1ファイルあたり約200行以内に収めることが推奨されています。それを超えるボリュームになる場合は、内容をSkillsや「.claude/rules/」というディレクトリに分割するのが望ましいとされます。ファイルが肥大化すると、AIが本当に重要なルールを見落としやすくなるため、簡潔さを保つことが結果的に精度の向上につながりそうです。
書き方の実践的なコツ
CLAUDE.mdを書く際によく指摘されるのが、「いい感じに」といった主観的な表現は避けるべきだという点です。Claudeは「いい感じ」という曖昧な言葉を解釈できません。代わりに「変数名はキャメルケースで統一する」のように、客観的で検証可能な具体的な指示に落とし込む必要があります。
また、興味深い指摘として、「〜してはいけない」という禁止形の指示のほうが、「〜してください」という肯定形の指示よりも遵守されやすい傾向があるです。避けてほしい行動を明示的に書いておくことが、実は効果的な制御方法になるということのようです。
すぐ使えるテンプレートの構成
ゼロから書き始めるのが大変だという場合は、次のような5つのセクションを埋めていく形でテンプレート化すると取り組みやすくなります。
- プロジェクト概要
- 技術スタック
- コーディング規約
- 禁止事項
- よく使うコマンド
この5セクションを起点にすれば、初めてCLAUDE.mdを書く人でも迷わず作成に着手できそうです。
複数のプロジェクトを扱う場合は階層化する
個人開発を超えて、複数のパッケージやサービスを一つのリポジトリにまとめる「モノレポ」構成でClaude Codeを使う場合は、CLAUDE.mdを階層的に配置する方法も知っておくと役立ちます。具体的には、リポジトリのルート直下に共通のルール(全体に共通するコーディング規約やCI/CDの方針など)を書いたCLAUDE.mdを置き、フロントエンド用パッケージやAPI用パッケージそれぞれのディレクトリの中に、その領域固有のルールを書いた個別のCLAUDE.mdを置く、という構成です。
Claude Codeは作業しているディレクトリから親ディレクトリに向かって再帰的にCLAUDE.mdを探し、見つかったファイルをすべて読み込んだ上で、より具体的な(階層が深い)指示を優先するという仕組みになっているようです。ここで注意しておきたいのが、ルート直下のCLAUDE.mdは会話の途中で「/compact」によるコンテキスト整理が行われた後も再度読み込まれる一方、ネストされた(サブディレクトリの)CLAUDE.mdは再注入されない、という細かな違いがある点です。長時間の作業でサブディレクトリ固有のルールが効かなくなってきたと感じたら、この仕様が影響している可能性がありそうです。
完璧を目指さず「育てていく」
CLAUDE.mdの運用でもうひとつ大切な考え方が、最初から完璧なものを作ろうとしないことです。失敗するたびに「次から気をつけてほしいこと」を1行ずつ追記していく、という漸進的な運用スタイルが推奨されています。数週間、数ヶ月かけて、自分のプロジェクトに自然と最適化されたCLAUDE.mdへと育っていくというイメージを持っておくと、最初のハードルがぐっと下がるかもしれません。
MEMORY.mdとの兼ね合い
クロードコードにはMEMORY.mdというのもあり、こちらはクロードコードのエージェントがプロジェクトの情報などをちょこちょこ書き換えたりしています。ところが、ここに古い情報が残ってしまったり、間違った情報をエージェントが書いてしまったりと言った事が時折起こります。
厳密な優先順位のルールは明示されていませんが、扱われ方に違いがあります。
- CLAUDE.md：「これらの指示は既定の動作より優先し、必ずそのまま従うこと」という強い言葉で渡されます。現在有効な、意図的にキュレーションされた指示という位置づけです- MEMORY.md（メモリ）：「ある時点でのスナップショットであり、常に最新とは限らない。使う前に現状と照らし合わせて確認すること」という前提つきです。参考情報であり、絶対的な指示ではありません
MEMORY.mdの中身も時折チェックしながら作業すると、より間違いが起こりにくいと思います。（大体間違ってから原因を探るとMEMORY.mdの情報が間違ってたり古かったりするのですが、、）
まとめ
CLAUDE.mdを書く際に押さえておきたいポイントは次の通りです。
- WHAT・WHY・HOWの3視点で構成する
- 1ファイルは約200行以内を目安にし、超える場合は.claude/rules/へ分割する
- 「いい感じに」のような曖昧な表現を避け、具体的な動詞と禁止形の指示を活用する
- 最初から完璧を目指さず、失敗のたびに1行ずつ育てていく
CLAUDE.mdは一度書いたら終わりのファイルではなく、プロジェクトと一緒に成長していく生きたドキュメントだと捉えると、無理なく続けられそうです。