Claude CodeのCLAUDE.md書き方リファレンス
Claude Codeに指示を覚えさせておける「CLAUDE.md」、なんとなくでしか使えていなかったので仕様を整理してみました。
配置場所・優先順位・書き方のコツをまとめています。
早見表
| ファイル | 配置場所 | git管理 |
|---|---|---|
| ユーザーグローバル | ~/.claude/CLAUDE.md |
対象外 |
| プロジェクト | ./CLAUDE.md |
コミットする |
| プロジェクトローカル | ./CLAUDE.local.md |
コミットしない |
| サブディレクトリ | subdir/CLAUDE.md |
コミットする |
CLAUDE.mdとは何か
セッション開始時に毎回読み込まれる、Claudeへの指示ファイルを指す。
ビルドコマンドやコード規約、ワークフローのルール、プロジェクト固有の癖などを書いておくファイルで、hooksやpermissionsのような強制設定ではなく、あくまで「指示」という位置づけになる。
配置場所と読み込み順序
CLAUDE.mdは複数の階層に置くことができ、読み込み順はファイルシステムのルート側から作業ディレクトリ側に向かう。
例えばfoo/bar/で起動した場合の順序はこうなる。
foo/CLAUDE.md
foo/CLAUDE.local.md
foo/bar/CLAUDE.md
foo/bar/CLAUDE.local.md
サブディレクトリのCLAUDE.mdは、Claudeがそのディレクトリのファイルを読むタイミングでオンデマンドに読み込まれる。
複数ファイルは結合される
複数のCLAUDE.mdが見つかった場合、上書きではなく単純に連結される。
矛盾する指示を複数ファイルに書くと、どちらが優先されるか不定になるため、競合する内容は極力避けた方がよい。
特定のCLAUDE.mdを除外したい場合は、claudeMdExcludes設定でglobパターン指定が可能。
他ファイルを読み込む: @import構文
@path/to/fileと書くと、その場所に別ファイルの内容を展開できます。
See @README.md for overview and @package.json for available commands.
相対パス・絶対パスのどちらも使え、~/から始まるホームディレクトリ指定もできる。ネストは最大4ホップまで対応している。
バッククォートで囲むと、importとして展開されずただの文字列として残る。
/init と /memory の役割
/initはコードベースを解析し、CLAUDE.mdの叩き台を自動生成してくれるコマンド。
既存のCLAUDE.mdがある場合は上書きせず、改善案として提案される。生成後の手動調整は基本的に必要になります。
/memoryはCLAUDE.mdを編集するためのコマンド。
実行すると、現在読み込まれているCLAUDE.md・CLAUDE.local.mdの一覧が表示される。ファイルを選ぶと外部エディタが開き、存在しなければ新規作成もできる。
書き方のベストプラクティス
| 項目 | 推奨 | 非推奨 |
|---|---|---|
| サイズ | 200行以下を目安にする | 長文を書き連ねる |
| 内容 | コマンド・規約・癖・決定事項 | コードから読み取れる内容 |
| 表現 | 具体的な指示("2スペースインデント") | 曖昧な表現("形式を正しく") |
| 構造 | 見出し・箇条書き | 密度の高い段落 |
| 強調 | "IMPORTANT"などのキーワード | 普通の記述のみ |
サイズが膨らんできたら、.claude/rules/にパス単位でルールを分割する方法もある。
まとめ
CLAUDE.mdは階層ごとに置け、読み込み時は上書きではなく結合される。
@importで外部ファイルを取り込め、/initと/memoryでそれぞれ生成と編集ができる。
書くときは200行以下を目安に、具体的で検証可能な指示に絞るとよさそうです。