CLAUDE.mdの書き方｜Claude Codeのメモリ設定と配置場所

CLAUDE.md とは — Claude Code が毎回読む「指示書」

CLAUDE.md は、Claude Code が各セッションの開始時に自動で読み込むマークダウンファイルです。新しく入ったチームメンバーに渡すオンボーディング資料に近い役割ですが、読み手は人ではなく Claude です。

Claude Code のセッションは毎回まっさらなコンテキストウィンドウで始まります。そのため、プロジェクトのビルドコマンドやコード規約、アーキテクチャといった「毎回前提になる情報」をプロンプトのたびに説明し直す必要があります。CLAUDE.md にこれらを書いておくと、会話の冒頭にその内容が読み込まれ、説明の反復が不要になります。

公式ブログはこの性質を「CLAUDE.md はドキュメントではなく、チームと AI のあいだの振る舞いの契約だ。すべての行が Claude の動きを変えるべきで、変えないなら消すべきだ」と表現しています(出典)。単なるメモ置き場ではなく、Claude の挙動を実際に変えるための指示だけを書く、という考え方が重要です。

CLAUDE.md と自動メモリの違い(2つのメモリ)

Claude Code には、セッションをまたいで知識を保つ仕組みが 2 つあります。どちらも会話の開始時に読み込まれますが、役割がはっきり分かれています。

• CLAUDE.md ファイル:あなたが書く指示とルール。コーディング標準、ワークフロー、プロジェクトアーキテクチャなど「Claude にこう動いてほしい」を記述します。
• 自動メモリ:Claude が自分で書くメモ。あなたの修正や好みから、ビルドコマンドやデバッグの知見、コードスタイルの傾向を学習して蓄積します。

つまり、Claude の動きを能動的にガイドしたいときは CLAUDE.md、手作業なしに修正履歴から学ばせたいときは自動メモリ、という使い分けです。なお両者とも「強制設定」ではなくコンテキスト(参考情報)として扱われます。確実にブロックしたい操作は CLAUDE.md ではなく PreToolUse hook を使う、という点は押さえておきましょう。

CLAUDE.md の配置場所と読み込み順(4つのスコープ)

CLAUDE.md は置く場所によってスコープ(適用範囲)が変わります。公式ドキュメントは、広いスコープから狭いスコープへの読み込み順で次の 4 種類を挙げています。

1. 管理ポリシー(組織全体):IT/DevOps が配布する全社共通の指示。macOS は /Library/Application Support/ClaudeCode/CLAUDE.md、Linux/WSL は /etc/claude-code/CLAUDE.md、Windows は C:\Program Files\ClaudeCode\CLAUDE.md。
2. ユーザー指示(全プロジェクト):~/.claude/CLAUDE.md。あなた個人の好み(コードスタイル、ツールのショートカット等)を、どのプロジェクトでも適用します。
3. プロジェクト指示(チーム共有):./CLAUDE.md または ./.claude/CLAUDE.md。バージョン管理にコミットしてチームで共有する、プロジェクト標準の指示です。
4. ローカル指示(自分専用):./CLAUDE.local.md。そのプロジェクト固有だが共有したくない好み。.gitignore に追加して使います。

読み込み順は「広い → 狭い」で、後に読まれた指示ほど Claude に近い文脈として効きます。さらに Claude Code はカレントディレクトリから親方向へツリーを遡り、途中の各階層の CLAUDE.md を連結して読み込みます。たとえば foo/bar/ で起動すると、foo/CLAUDE.md → foo/bar/CLAUDE.md の順で文脈に並びます。サブディレクトリ内の CLAUDE.md は起動時ではなく、Claude がそのフォルダのファイルを読むときにオンデマンドで読み込まれます。

CLAUDE.md の書き方 — 効果的な指示の3原則

CLAUDE.md は毎回コンテキストウィンドウに読み込まれ、会話と一緒にトークンを消費します。長く曖昧なファイルは遵守率を下げるため、公式は次の 3 原則を挙げています。

1. サイズ:1 ファイル 200 行以下を目標に。長くなるほどコンテキストを食い、指示の遵守が下がります。膨らんできたら後述の .claude/rules/ や @import で分割します。
2. 構造:マークダウンの見出しと箇条書きで関連する指示をグループ化します。Claude も人と同じように構造をスキャンするため、整理されたセクションのほうが従いやすくなります。
3. 具体性:検証できるレベルまで具体的に書きます。

3 つ目の「具体性」は特に効きます。公式が挙げる対比が分かりやすいので引用します。

• 「コードを適切にフォーマットする」ではなく「2 スペースのインデントを使用する」
• 「変更をテストする」ではなく「コミット前に npm test を実行する」
• 「ファイルを整理しておく」ではなく「API ハンドラーは src/api/handlers/ に置く」

また、矛盾する指示があると Claude はどちらか一方を任意に選んでしまいます。古くなったルールは定期的に見直して削除しましょう。

/init コマンドで自動生成する

ゼロから書くのが面倒なら、/init を実行するのが近道です。Claude がコードベースを解析し、見つけたビルドコマンド・テスト手順・プロジェクト規約を含む CLAUDE.md を自動生成します。既に CLAUDE.md がある場合は、上書きではなく改善の提案をしてくれます。

生成された雛形をベースに、Claude が自力では気づけないチーム固有のルール(命名規則、レビュー方針、避けるべき落とし穴など)を手で書き足していくのが効率的です。

@import と .claude/rules でルールを整理する

CLAUDE.md が大きくなってきたら、内容を外部ファイルに分けて整理できます。手段は 2 つです。

ひとつは @import(インポート)。@path/to/file の構文で別ファイルを取り込めます。相対パスはインポート元ファイル基準で解決され、再帰インポートは最大 4 階層まで対応します。たとえば次のように書けます。

プロジェクト概要は @README を、npm コマンドは @package.json を参照してください。

# 追加の指示
- git ワークフローは @docs/git-instructions.md を参照

ただしインポート先も起動時に読み込まれるため、トークン削減にはなりません(整理が目的)。

もうひとつは .claude/rules/ ディレクトリです。testing.md security.md のようにトピック別のマークダウンに分け、paths フィールドの YAML フロントマターを付ければ、特定のファイルを編集するときだけそのルールを読み込ませられます。

---
paths:
  - "src/api/**/*.ts"
---

# API 開発ルール
- すべての API エンドポイントは入力検証を含める
- 標準エラー応答フォーマットを使う

この「パス固有ルール」を使うと、関係ないときにはコンテキストを消費せず、ノイズを減らしつつコンテキスト容量を節約できます。常にではなく特定タスクのときだけ必要な手順は、ルールではなく Skills に分けるのも有効です。

AGENTS.md との関係(他ツールとの共存)

「他のコーディングツール用に AGENTS.md を既に持っている」というケースもあります。Claude Code が読むのは CLAUDE.md であって AGENTS.md ではありません。重複を避けるには、CLAUDE.md から AGENTS.md をインポートします。

@AGENTS.md

## Claude Code
`src/billing/` 配下の変更には Plan Mode を使う

Claude 固有の追記が不要なら、シンボリックリンク(ln -s AGENTS.md CLAUDE.md)でも構いません。Windows ではシンボリックリンクに管理者権限が必要なため、@AGENTS.md インポートを使います。

なお、Claude Code を Anthropic 経由で使っても、Google Cloud の Vertex AI 経由で使っても、CLAUDE.md の仕様はまったく同じです。認証や課金の経路が変わるだけで、メモリの読み込みは共通仕様で動きます(Vertex 経由の設定は「Google で Claude Code を使う方法」を参照)。

CLAUDE.md がうまく効かないときのトラブルシュート

「書いたのに従ってくれない」ときは、次の順で切り分けます。

1. 読み込まれているか確認:/memory を実行すると、現在のセッションに読み込まれた CLAUDE.md・CLAUDE.local.md・ルールが一覧表示されます。ここに無ければ Claude はそのファイルを見ていません。
2. 配置場所を見直す:対象の CLAUDE.md が、セッションに読み込まれる階層(プロジェクトルートや親ディレクトリ)に置かれているかを確認します。
3. 指示を具体化する:前述のとおり「適切に」より「2 スペース」のように、検証可能な表現に書き換えます。
4. 矛盾を探す:複数の CLAUDE.md やルールで相反する指示がないかを点検します。

そもそも CLAUDE.md は「システムプロンプトそのもの」ではなく、その後のユーザーメッセージとして渡されるコンテキストです。厳密な遵守は保証されません。コミット前やファイル編集後など特定タイミングで必ず実行させたい処理は、hook として書くのが確実です。hook はシステムコマンドとして固定のライフサイクルで動くため、Claude の判断に左右されません。

ちなみに /compact で会話を圧縮しても、プロジェクトルートの CLAUDE.md はディスクから再読み込みされるため失われません。圧縮後に指示が消えたように見える場合、それは会話中にだけ伝えた指示か、まだ再読み込みされていないサブディレクトリの CLAUDE.md です。永続化したい指示は会話任せにせず CLAUDE.md に書きましょう。

まとめ

CLAUDE.md は、Claude Code に毎回同じ説明を繰り返す手間をなくし、プロジェクトのルールを一度書けば全セッションに効かせられる「指示書」です。要点を振り返ります。

• 正体:毎セッション読まれる指示ファイル。あなたが書く CLAUDE.md と、Claude が書く自動メモリの 2 系統がある。
• 配置:管理ポリシー / ユーザー(~/.claude/CLAUDE.md)/ プロジェクト(./CLAUDE.md)/ ローカル(CLAUDE.local.md)の 4 スコープ。広い順に読み込まれる。
• 書き方:200 行以下・構造化・検証できる具体性の 3 原則。/init で雛形生成、@import と .claude/rules/ で整理。
• 限界:強制ではなくコンテキスト。確実な制御は hook で。

まずは /init で雛形を作り、よく繰り返す説明を 1 つずつ追記していくところから始めるのがおすすめです。

出典:

• Claude Code 公式ドキュメント「Claude があなたのプロジェクトを記憶する方法」 https://code.claude.com/docs/ja/memory
• Anthropic 公式ブログ「Using CLAUDE.md files」 https://claude.com/blog/using-claude-md-files