【Claude Code】CLAUDE.mdの書き方と注意点

はじめに

今回はClaude Codeを使用するうえで知っておきたい、CLAUDE.mdの書き方と注意すべきことについて解説していきたいと思います。

まずは公式ドキュメントを一読することをおすすめします。

CLAUDE.mdとは

CLAUDE.mdとは、Claude Codeが起動時（セッション開始時）に自動で読み込む設定ファイルのことです。
内容はすべてコンテキストウィンドウ（記憶領域）に読み込まれ、リクエストの度に、必要な情報が自動的にコンテキストとしてプロンプトに渡されます。
そのため、常に一貫したルールを遵守させたい場合や、毎回同じようなプロンプトを作成するのが面倒な場合に役立ちます。

リクエスト時に動的に読み込まれるケースもある

CLAUDE.mdは、「配置された場所」「Claude Codeのセッションを開始した場所」「gitリポジトリの有無」 によって読み込まれるタイミングが異なるため、表にまとめてみました。
※Claude Codeのセッションを開始した場所をカレントディレクトリとします。

CLAUDE.mdの配置場所	適用タイミング
ホームフォルダ （~/.claude/CLAUDE.md）	(すべての)セッション開始時
プロジェクトルート （project/CLAUDE.md）	セッション開始時
(※1)親ディレクトリ （parent/CLAUDE.md）	セッション開始時
カレントディレクトリ （./CLAUDE.md）	セッション開始時
(※2)サブ(子)ディレクトリ （sub/CLAUDE.md）	リクエスト時

※1
カレントディレクトリを起点とし、cd ..コマンドで
(gitリポジトリ内にいる場合は)プロジェクトルートにたどり着くまで
(gitリポジトリ内にいない場合は)ホームフォルダにたどり着くまで
に通過したディレクトリ

※2
リクエスト内容によって参照されたファイルの存在するディレクトリを起点とし、cd ..コマンドでカレントディレクトリにたどり着くまでに通過したディレクトリ

現在どのCLAUDE.mdが読み込まれているかは、/memoryコマンドで確認できます。

1. 200行以下を目標にする

公式ドキュメントに以下のような記述があります。

サイズ: CLAUDE.md ファイルあたり 200 行以下を目標にします。より長いファイルはより多くのコンテキストを消費し、遵守を減らします。指示が大きくなっている場合は、インポートまたは .claude/rules/ ファイルを使用して分割します。

しかし、Claude Codeは内部のシステムプロンプトにとってデフォルトで約50ほどの命令が含まれているそうです。
そのため、より精度を高めたいのであれば、100行（1500単語）程度に収めるのが良さそうです。
より細かくルールを設定したい場合には、後述する3. 段階的開示を使用します。

2. 普遍的内容のみを記述する

「重要でないことは無視される」

Claude Codeを使用していると、たまにCLAUDE.mdに書かれていることが無視されてしまうことがありますが、これは内部的な仕様によるものです。
Claude Codeは内部で

CLAUDE.mdを参照する際に、重要ではないことは無視してください

という命令がデフォルトで与えられています。
例えば、バックエンドの実装に関するルールを書いたとしても、リクエストの内容がフロントエンドの実装だった場合、Claude CodeはCLAUDE.mdのバックエンドの実装に関するルールを無視したコンテキストをよしなに生成します。これはコンテキストの肥大化を抑えてくれるのに役立っています。
一方で、Claude Codeに重要でないと思われた記述は無視されてしまうため、CLAUDE.mdにはリクエスト内容に左右されず、常に参照されるような普遍的内容のみを記述することが推奨されます。

バックエンドの実装に関するルールなどは、後述する3. 段階的開示を使用します。

3. 段階的開示

CLAUDE.mdに書かなかったその他の細かいルールや設定などは、以下の方法で 「必要なときに」「必要な情報だけ」をわたすことが推奨されます。

インポートを使用する

以下のように@path/to/import 構文を使用して追加ファイルをインポートすることで、指示を拡張することが可能です。（公式ドキュメントより）

CLAUDE.md

See @README.md for project overview and @package.json for available npm commands.

# Additional Instructions
- Git workflow: @docs/git-instructions.md
- Personal overrides: @~/.claude/my-project-instructions.md

インポートには相対パスと絶対パスの両方が使えます。
注意点として、@docs/git-instructions.mdのようにコードスパン（バッククォート）で囲んだ場合や、コードブロック内に記載した場合は、インポートとして評価されません。
また、インポートされたファイルの中からさらに別のファイルをインポートすることも可能ですが、ネストの深さは最大で5階層までが推奨されています。

相対パスと絶対パスの両方が許可されます。相対パスはワーキングディレクトリではなく、インポートを含むファイルに相対的に解決されます。インポートされたファイルは他のファイルを再帰的にインポートでき、最大深度は 5 ホップです。

ファイルを参照させたい場合はなるべく明示的に@インポートを使用しましょう。そうでないと、無視されてしまうことがあります。
@インポートを使用する際は、二重読み込みに注意してください。
rules/のファイルをインポートするなど、同じファイルを二重に読み込むことでコンテキストが逼迫してしまいます。

rulesを使用する

rulesを使用すると、ディレクトリごとに1つのCLAUDE.mdファイルでルールを管理する必要がなくなります。
また、CLAUDE.mdでの @インポート読み込みはClaude Codeの判断に依存しますが、rules/で定義したルールはより確実に適用できるというメリットがあります。
現在どのrules/が読み込まれているかは、CLAUDE.md同様に/memoryコマンドで確認できます。
.claude/rulesディレクトリを使うことで、任意のファイル名をつけながらルールファイルを分割してより細かく管理できるようになります。

your-project/
├── .claude/
│   ├── CLAUDE.md           # メインプロジェクト指示
│   └── rules/
│       ├── code-style.md   # コードスタイルガイドライン
│       ├── testing.md      # テスト規約
│       └── security.md     # セキュリティ要件

特定のパスや拡張子に一致するパターンにのみルールを適用させる、といったことも可能です。

---
paths:
  - "src/api/**/*.ts"
  - "src/**/*.{ts,tsx}"
---

# API 開発ルール

- すべての API エンドポイントは入力検証を含める必要があります
- 標準エラー応答形式を使用します
- OpenAPI ドキュメンテーションコメントを含めます

ルールは各セッションまたは一致するファイルが開かれたときにコンテキストに読み込まれます。常にコンテキストに必要ないタスク固有の指示については、skillsを使用してください。これは、呼び出すときまたは Claude がプロンプトに関連していると判断したときにのみ読み込まれます。

rulesはskillsと比較すると、コンテキスト負荷が高くなりやすいようです。
詳しくは公式ドキュメントのrulesの章を参照ください。

skillsを使用する

skillsに関しては、別途深ぼったこちらの記事をぜひご参考ください。

4. 　/initコマンドはなるべく使わない

Claude Codeには/initコマンド(CLAUDE.mdをよしなに作成してくれるコマンド)が存在しますが、最新の研究で

AIが自動生成したCLAUDE.mdは何もない状態より精度が下がる

という結果が出ているそうなので、できる限り自分で考えながら作成したほうが良さそうです。

結論

CLAUDE.mdにはできる限りなにも書くな(極端な話ですが)
理由は以下のとおりです。
・（基本的に）セッション開始時に一度のみ読み込まれその後更新されない
・会話が続く中で古い情報として真っ先に消される可能性がある
・Claude Codeも必ずリクエスト時のプロンプトに含めるわけではない
・ルールを設定するなら常時読み込まれるrules/の方が優秀
・@インポートによる二重読み込みのリスクあり

こちらの記事でも言われているように、CLAUDE.mdはただのSession Start Hook（毎回最初に似たようなプロンプトを入力する手間を省くためだけのもの）ぐらいに思って扱ったほうが良さそうです。

おまけ

CLAUDE.mdの便利な使い方の例を紹介します。

①プロンプトの補助として使う

CLAUDE.md

ユーザーの入力が曖昧な場合はAskUserQuestionツールを積極的に使ってください

②学習として使う

CLAUDE.md

##出力ガイド
ユーザーは、写経して学習しながら開発を行うことを希望しています。
**あなたはコードを教えるだけで実装しないでください。**
まず現在のファイルを一緒に確認してから、変更箇所を順番に教えていきます。各変更箇所ごとに:
- 変更後のコードを提示
- なぜこう変更するのかを説明
という流れで進めてください。