📝

CLAUDE.md書き方 — 順序最適化とベストプラクティス

Claude Code

変わらない内容は上に、よく変わる内容は下に — プロンプトキャッシング最適化

CLAUDE.mdはClaude Codeがプロジェクトを理解するための最も重要なファイルだ。毎セッション開始時に自動ロードされ、ここに書かれたルールをClaudeが従う。

最も重要な原則：配置順序

変わらない内容を上に、よく変わる内容を下に置くべき。理由はプロンプトキャッシングにある。

Claude Codeはシステムプロンプトをキャッシュするが、キャッシングは先頭から一致する部分までのみ有効。ファイル前半が変わるとキャッシュが全て無効化される。だから絶対に変わらない内容（プロジェクト説明、コーディングルール）を最上部に置くとキャッシュヒット率が上がり、毎回変わる内容（現在の作業コンテキスト）は最下部に置けばキャッシュに影響しない。

推奨配置順序

プロジェクト説明 — 名前、技術スタック、目的（ほぼ変わらない → キャッシュヒット）
コーディングルール — 規約、禁止事項、スタイル（追加はあるが既存内容は変わらない → キャッシュヒット）
アーキテクチャ決定 — DB、認証、ルーティング等の設計パターン（時々変更 → 時々キャッシュミス）
現在の作業コンテキスト — 進行中のタスク、一時メモ（頻繁に変更 → キャッシュミス、ただし最下部なので上のキャッシュに影響なし）

ルールファイル分離

.claude/rules/ディレクトリにトピック別.mdファイルを分離すると、メインCLAUDE.mdをスッキリ維持できる。ルールファイルはCLAUDE.mdと一緒に自動ロードされる。

3つのレベルのCLAUDE.md

~/.claude/CLAUDE.md — 個人グローバルルール（全プロジェクト共通）
プロジェクトルート/CLAUDE.md — プロジェクトルール（Gitにコミット、チーム共有）
.claude/rules/*.md — トピック別分離ルール（Gitにコミット）

プロンプトキャッシングと配置順序

Claude CodeはCLAUDE.mdをシステムプロンプトに含め、先頭からキャッシュします。前半が前回のセッションと同じなら → キャッシュヒット → 高速かつ低コスト。

キャッシュヒット ✓ プロジェクト説明（ほぼ変わらない）

キャッシュヒット ✓ コーディングルール（追加のみ）

時々ミスアーキテクチャ決定（設計変更時）

キャッシュミス ✗ 現在の作業コンテキスト（毎回変更、ただし最下部なので上に影響なし）

核心：キャッシングは先頭から一致する部分までのみ有効。変わる内容を上に置くとキャッシュ全体が無効化される。

CLAUDE.mdの3つのレベル

レベル	場所	範囲	Git
個人グローバル	`~/.claude/CLAUDE.md`	全プロジェクトに適用	非追跡
プロジェクト	`プロジェクトルート/CLAUDE.md`	プロジェクト全体（チーム共有）	コミット
トピック別分離	`.claude/rules/*.md`	プロジェクト（トピック分離）	コミット

書き方のコツ

✓

具体的に書く — 「きれいなコードを書け」より「enumはRails 8文法（attribute + enum :status）で書く」の方が効果的

✓

禁止事項は理由付き — 「jsonb禁止」より「jsonb禁止（SQLite非対応）」の方がClaudeがよく従う

✓

コード例を含める — 指示と一緒にコードブロックを入れると精度が大幅向上

✗

コードから読めることは書かない — ファイル構造、git履歴、変数名等はClaude自身が読める

使い方

1

プロジェクトルートにCLAUDE.md作成 → 安定順に記述（プロジェクト説明 → コーディングルール → アーキテクチャ → 現在の作業）

2

ルールが増えたら.claude/rules/にトピック別.mdファイルに分離

3

個人グローバルルールは~/.claude/CLAUDE.mdに設定（全プロジェクト共通適用）

4

よく変わる内容（現在の作業、一時メモ）は常にファイルの最下部に配置

Source

Anthropic Docs