CLAUDE.mdの書き方｜Claude Codeの精度を上げるメモリ設定

公開: 2026年8月2日

Claude Codeの精度を上げる一番手っ取り早い方法は、CLAUDE.md にプロジェクトの前提知識を書いておくことです。ビルドコマンドや規約を毎回説明する必要がなくなり、Claudeが一貫した挙動でコードを書いてくれるようになります。この記事では、CLAUDE.mdの配置場所と優先順位、/init による自動生成、書くべき内容と実例、書かない方がいい内容を整理します。

CLAUDE.mdとは何か

CLAUDE.mdは、Claude Codeがセッション開始時に読み込む、プレーンテキストのMarkdownファイルです。毎回チャットで説明し直すのが面倒な情報を書いておく場所だと考えるとわかりやすいです。

Claude Codeにはこのほかに、Claude自身が学習内容を書き込む「自動メモリ(Auto memory)」もあります。CLAUDE.mdは人間が書く指示、自動メモリはClaudeが自分で書く学習内容という役割分担です。この記事ではCLAUDE.mdの書き方に絞って解説します。

CLAUDE.mdはあくまでClaude Codeの数ある設定のひとつです。権限やhook、環境変数など動作そのものを制御する設定はsettings.jsonが担当します。詳しくは「Claude Code settings.json解説」を、設定ファイル全体を体系的に押さえたい方は「Claude Code設定完全ガイド」をあわせてご覧ください。

CLAUDE.mdは複数の場所に置くことができ、それぞれスコープ(適用範囲)が異なります。公式ドキュメントによると、読み込み順は範囲が広いものから狭いものへと次のようになっています。

スコープ	配置場所	用途
組織全体	各OSの管理者用ディレクトリ(Windowsは `C:\Program Files\ClaudeCode\CLAUDE.md`)	会社全体の規約・ポリシー
ユーザー	`~/.claude/CLAUDE.md`	全プロジェクト共通の個人的な好み
プロジェクト	`./CLAUDE.md` または `./.claude/CLAUDE.md`	チームで共有するプロジェクトの規約
ローカル	`./CLAUDE.local.md`	個人用の固有設定(`.gitignore`推奨)

作業ディレクトリより上の階層のCLAUDE.mdは起動時にすべて読み込まれ、サブディレクトリのCLAUDE.mdはClaudeがそのディレクトリのファイルを読んだタイミングで追加読み込みされます。複数ファイルは上書きではなく連結され、階層の浅い指示が先、作業ディレクトリに近い指示が後に配置されます。

CLAUDE.md内では @path/to/file という記法で他ファイルを読み込めます(import構文)。相対パスはimport元からの相対位置で解決され、再帰的なimportは最大4階層まで可能です。既存の AGENTS.md を流用したい場合は、先頭で @AGENTS.md と書くだけで取り込めます。仕様は変わる可能性があるため、正確な挙動は公式ドキュメントのMemoryページで確認してください。

/init での自動生成

CLAUDE.mdは手書きしなくても、セッション内でスラッシュコマンドの /init を実行すれば自動生成できます。

/init

/init を実行すると、Claudeがコードベースを解析し、ビルドコマンドやテスト方法、発見したプロジェクトの慣習をまとめたCLAUDE.mdを作成してくれます。すでに存在する場合は上書きではなく改善案を提案します。既存のCursorルールなど他ツールの指示ファイルがあれば取り込んでくれます。

ただし生成内容はコードベースから読み取れる範囲にとどまります。チーム独自の暗黙のルールはカバーしきれないため、生成後に手を入れる前提で使うのがおすすめです。

作成済みのCLAUDE.mdを一覧・編集したいときは /memory コマンドを使います。ファイルを選択すると自動でエディタが開き、存在しないファイルを選ぶとその場で新規作成されます。会話中に「これをCLAUDE.mdに追加して」と頼む方法や、# から始めるメッセージで手早くメモリに追記できる場合もありますが、挙動はバージョンや設定によって変わるため、最新の仕様は公式ドキュメントで確認してください。

書くべき内容と実例

CLAUDE.mdに書くべきなのは、「Claudeが同じ間違いを2回目もしてしまったこと」「コードレビューで毎回指摘されること」「新しいメンバーに毎回説明していること」です。具体的にはビルド・テスト・Lintの実行コマンド、ディレクトリ構成のルール、コーディング規約、やってはいけない操作などが向いています。

以下は、Node.jsのWebアプリを想定したサンプルCLAUDE.mdの全文です。

# プロジェクト概要

社内向けタスク管理SaaSのバックエンドAPIです。Node.js + TypeScript + Expressで構築しています。

## セットアップ・ビルドコマンド

- 依存関係のインストール: `npm install`
- テスト実行: `npm test`
- 型チェック: `npm run typecheck`

## コーディング規約

- インデントは2スペース、async/awaitを使用(.then()チェーンは不可)
- APIレスポンスは必ず `{ data, error }` の形式で返す

## 禁止事項

- `src/models/schema.prisma` は直接編集しない(マイグレーションコマンド経由で変更する)
- `main` ブランチへの直接pushは禁止。必ずPR経由にする

## 参考ファイル

@docs/api-conventions.md

コマンド・規約・禁止事項をセクションごとに分けると、Claudeが構造を把握しやすくなります。詳細な資料は本文に埋め込まず、importで参照すると見通しがよくなります。

書かない方がいいこと

CLAUDE.mdはセッションのたびにコンテキストウィンドウへ読み込まれるため、長くなるほどトークンを消費し、指示への追従精度も下がる傾向があります。以下のアンチパターンは避けましょう。

長すぎる指示: 1ファイルあたり200行程度が目安です。肥大化したら .claude/rules/ へのパス限定ルールに分割しましょう。
曖昧な表現: 「コードをきれいに整形する」ではなく「インデントは2スペースにする」のように検証可能な表現で書く方が効果的です。
矛盾した指示: 複数階層のCLAUDE.mdで矛盾する指示があると、Claudeがどちらに従うか一貫しなくなります。
絶対に守らせたいルールをCLAUDE.mdだけに書く: CLAUDE.mdはあくまで「文脈」であり強制設定ではありません。確実に強制したい処理はHook機能の利用を検討してください。

つまずきポイント

CLAUDE.mdを置いたのに読み込まれない: セッション内で /context を実行し、「Memory files」の一覧に対象ファイルが表示されているか確認してください。表示されない場合は配置場所が誤っている可能性があります。
/init の生成内容が薄い: READMEや設定ファイルが少ないプロジェクトでは自動生成の内容も乏しくなります。生成後に手動で追記してください。
/compact 後に指示が消えたように見える: プロジェクトルート直下のCLAUDE.mdは /compact 後にディスクから再読み込みされますが、サブディレクトリのCLAUDE.mdは該当ディレクトリのファイルを読んだタイミングまで再読み込みされません。

よくある質問

CLAUDE.mdとCLAUDE.local.mdはどう使い分ければよいですか?

チームで共有したい規約は CLAUDE.md に、自分だけのローカル設定(サンドボックスURLやテストデータなど)は CLAUDE.local.md に書き、.gitignore に追加するのが基本です。

`/init` を実行したあと、内容は手動で編集してもよいですか?

問題ありません。むしろ推奨されています。生成内容はコードベースから読み取れる範囲にとどまるため、チーム独自のルールは自分で追記してください。編集は /memory コマンドから対象ファイルを選ぶと開けます。

CLAUDE.mdに書いた指示にClaudeが従ってくれないことがあります

CLAUDE.mdは強制設定ではなく文脈として扱われるため、曖昧な指示や矛盾した指示があると従わないことがあります。まず /context でファイルが読み込まれているか確認し、より具体的な表現に書き換えてみてください。確実に守らせたい処理はHook機能での実装を検討しましょう。

まとめ

CLAUDE.mdは、組織・ユーザー・プロジェクト・ローカルという階層構造で読み込まれ、/init コマンドで自動生成もできる、Claude Codeの精度を左右する設定ファイルです。書くべき内容は「毎回説明し直している情報」に絞り、200行程度を目安に具体的で検証可能な表現でまとめるのがコツです。Claude Code自体の概要は「Claude Codeとは?できること・料金・始め方」、/init や /memory を含むコマンド一覧は「Claude Codeのスラッシュコマンド一覧と使い方を解説」もあわせてご覧ください。