はじめに
前回の記事からClaude Codeを使い始めました。使っているうちに、前のセッションで伝えたはずのルールを守ってくれないことが何度かありました。
これは、Claude Codeが毎回まっさらな状態でセッションを始めることが原因です。
今回は、Claude Codeがセッションをまたいで情報を記憶する仕組みである「CLAUDE.md」と「自動メモリ」についてまとめました。
Claude Codeの記憶の仕組み
まずは、Claude Codeがどのように情報を覚えているのか、全体像を見ていきます。
セッションは毎回リセットされる
Claude Codeでは、セッションごとに新しいコンテキストウィンドウが用意されます。
コンテキストウィンドウとは、モデルが一度に参照できる情報の入れ物のようなものです。会話の履歴、読み込んだファイル、コマンドの実行結果などはすべてここに入ります。
コンテキストウィンドウには上限があるため、会話が長くなると、それまでのやり取りが要約に置き換えられます（コンパクト）。また、新しいセッションを始めると、前のセッションの会話は引き継がれません。
そこで、セッションをまたいで情報を引き継ぐために、以下の2つの仕組みが用意されています。
- CLAUDE.md：自分で書く指示ファイル
- 自動メモリ：Claudeが自分で書くメモ
どちらもセッション開始時にコンテキストへ読み込まれます。つまり、最終的にはコンテキストウィンドウに載ることで初めて効果を発揮します。
CLAUDE.mdと自動メモリの違い
2つの仕組みの違いは以下の通りです。
| CLAUDE.md | 自動メモリ | |
|---|---|---|
| 書く人 | 自分 | Claude |
| 内容 | 指示やルール | 学習した内容やパターン |
| スコープ | 組織・ユーザー・プロジェクト | リポジトリごと |
| 読み込み | 全セッション | 全セッション（MEMORY.mdの先頭200行または25KBまで） |
| 用途 | コーディング規約、ワークフロー、アーキテクチャ | 自分の好み、Claudeへの修正指示、コードからは分からない背景 |
注意点として、どちらも「設定」ではなく「コンテキスト」として扱われます。そのため、Claudeが必ず従うとは限りません。指示は具体的かつ簡潔に書くほど守られやすくなります。
CLAUDE.md
CLAUDE.mdは、Claudeに永続的な指示を与えるためのマークダウンファイルです。
GitHub Copilotでいうcustom instructionsに近いものです。
配置場所とスコープ
CLAUDE.mdは配置する場所によってスコープが異なります。
| スコープ | 配置場所 | 用途 |
|---|---|---|
| 組織（管理ポリシー） | macOS：
/Library/Application Support/ClaudeCode/CLAUDE.md
Linux / WSL： /etc/claude-code/CLAUDE.md
| 会社のコーディング標準やセキュリティポリシー |
| ユーザー |
~/.claude/CLAUDE.md
| 全プロジェクト共通の個人設定 |
| プロジェクト |
./CLAUDE.md
または
./.claude/CLAUDE.md
| チームで共有するルール（Gitで管理） |
| ローカル |
./CLAUDE.local.md
| 自分だけのプロジェクト設定（
.gitignore
に追加する） |
組織向けのCLAUDE.mdは、個人の設定で除外することはできません。
読み込まれるタイミング
作業ディレクトリと、その上位にあるディレクトリのCLAUDE.mdは、起動時にすべて読み込まれます。
読み込まれたファイルは上書きされるのではなく、連結されます。並び順はルートに近いものが先で、作業ディレクトリに近いものほど後になります。
一方、作業ディレクトリより下のサブディレクトリにあるCLAUDE.mdは、起動時には読み込まれません。Claudeがそのディレクトリ内のファイルを読み書きしたタイミングで、必要に応じて読み込まれます。
また、CLAUDE.md内のHTMLコメントはコンテキストに渡される前に削除されます。人間向けのメモを残したい場合に、トークンを消費せずに書けるので便利です。
/initで雛形を作成する
CLAUDE.mdを一から書くのは大変なので、まずは
/init
コマンドで雛形を作成するのがおすすめです。
Claudeがコードベースを分析し、ビルドコマンドやテスト方法、プロジェクトの規約などを含むCLAUDE.mdを生成してくれます。すでにCLAUDE.mdがある場合は、上書きではなく改善案を提案してくれます。
ちなみに、
.cursorrules
や
.github/copilot-instructions.md
があれば、その内容も取り込んでくれるので、Copilotからの移行時にも便利です。
効果的な指示の書き方
CLAUDE.mdは書き方次第で守られやすさが変わります。ポイントは以下の通りです。
- 検証できるくらい具体的に書く
- 1ファイルあたり200行以内を目安にする
- 見出しや箇条書きで整理する
- 矛盾する指示を残さない
具体的な書き方の例は以下の通りです。
| NG | OK |
|---|---|
| コードを適切にフォーマットする | インデントは2スペースにする |
| 変更をテストする | コミット前に
npm test
を実行する |
| ファイルを整理する | APIハンドラは
src/api/handlers/
に置く |
指示同士が矛盾していると、Claudeはどちらか一方を任意に選んでしまいます。定期的に見直して、古い指示は削除しておきましょう。
他のファイルをインポートする
CLAUDE.mdでは、
@パス
と書くことで他のファイルを取り込むことができます。
| 1 2 3 4 5 | プロジェクトの概要は @README.md を参照 npmコマンドは @package.json を参照 # 追加の指示 - Gitのワークフロー @docs/git-instructions.md |
相対パスは、作業ディレクトリではなくインポート元のファイルを基準に解決されます。また、インポートは最大4階層までネストできます。
ただし、インポートしたファイルも起動時に読み込まれるため、コンテキストの節約にはなりません。あくまでファイルを整理するための機能です。
.claude/rulesでルールを分割する
プロジェクトが大きくなってきたら、
.claude/rules/
ディレクトリにトピックごとのルールファイルを置くことができます。
| 1 2 3 4 5 6 7 | your-project/ ├── .claude/ │ ├── CLAUDE.md │ └── rules/ │ ├── code-style.md │ ├── testing.md │ └── security.md |
さらに、ファイルの先頭に
paths
を書くことで、特定のファイルを扱うときだけ読み込まれるルールにすることができます。
| 1 2 3 4 5 6 7 8 | --- paths: - "src/api/**/*.ts" --- # APIのルール - すべてのエンドポイントで入力値のバリデーションを行う - エラーレスポンスは共通フォーマットを使用する |
この例では、Claudeが
src/api/
配下のTypeScriptファイルを扱うときだけルールが読み込まれます。常に読み込む必要がない指示はこちらに移すことで、コンテキストを節約できます。
なお、全プロジェクト共通の個人ルールは
~/.claude/rules/
に置くこともできます。
AGENTS.mdとの関係
Claude Codeは、他のコーディングエージェント向けの
AGENTS.md
も読み込むことができます。
デフォルトでは、CLAUDE.mdがない場合にのみAGENTS.mdが読み込まれます。両方を読み込みたい場合は、
/config
の「Project instructions」で設定を変更するか、CLAUDE.mdの中で
@AGENTS.md
とインポートします。
自動メモリ
自動メモリは、Claudeが作業中に自分自身でメモを取ってくれる機能です。ローカルのセッションではデフォルトで有効になっています。
保存される内容
自動メモリでは、以下の4種類の情報が保存されます。
| 種類 | 内容 |
|---|---|
| user | ユーザーの役割や専門知識、作業の好み |
| feedback | Claudeに対して行った修正や、良いと伝えたアプローチ |
| project | 進行中の作業や期限など、コードやGit履歴からは分からない情報 |
| reference | 課題管理ツールやダッシュボードなど、外部情報の場所 |
逆に、ファイル構成やアーキテクチャなどコードを読めば分かること、CLAUDE.mdにすでに書かれていることは保存されません。
また、毎回のセッションで必ず保存されるわけではなく、将来役に立つかどうかをClaudeが判断して保存します。
保存場所
自動メモリは、プロジェクトごとに以下の場所に保存されます。
| 1 2 3 4 5 | ~/.claude/projects/<project>/memory/ ├── MEMORY.md # インデックス（毎セッション読み込まれる） ├── user_role.md # 個別のメモ ├── feedback_testing.md # 個別のメモ └── ... |
<project>
はGitリポジトリから決まるため、同じリポジトリであればworktreeやサブディレクトリでも同じメモリが共有されます。
ただし、自動メモリはマシンローカルなので、別のマシンやクラウド環境とは共有されません。
読み込みの仕組み
セッション開始時に読み込まれるのは、インデックスである
MEMORY.md
の先頭200行、または25KBまでです。それを超えた部分は読み込まれません。
個別のメモファイルは起動時には読み込まれず、必要になったタイミングでClaudeが読みに行きます。
作業中に「Saved 2 memories」や「Recalled 2 memories」と表示された場合は、Claudeがメモリを保存、または参照しています。
有効・無効を切り替える
自動メモリのオン・オフは、
/memory
コマンドから切り替えることができます。
特定のプロジェクトだけ無効にしたい場合は、そのプロジェクトの設定ファイルに以下を記述します。
| 1 2 3 | { "autoMemoryEnabled": false } |
環境変数
CLAUDE_CODE_DISABLE_AUTO_MEMORY=1
を設定して無効にすることもできます。
メモリをうまく使うために
最後に、メモリ周りでよく使うコマンドと、困ったときの対処法を紹介します。
よく使うコマンド
| コマンド | 説明 |
|---|---|
| /init | CLAUDE.mdの雛形を生成する |
| /memory | CLAUDE.mdや自動メモリのファイルを開いて編集する、自動メモリのオン・オフ |
| /context | 読み込まれているメモリファイルやコンテキストの使用状況を確認する |
| /compact | 会話を要約してコンテキストを空ける |
| /doctor prompt-audit | 指示ファイルの古い内容や矛盾をチェックする |
チャットで「〇〇を覚えておいて」と伝えると、Claudeは自動メモリに保存します。CLAUDE.mdに追記してほしい場合は「これをCLAUDE.mdに追加して」と明示しましょう。
CLAUDE.mdが守られないとき
まずは
/context
を実行し、「Memory files」に対象のファイルが表示されているか確認します。表示されていなければ、Claudeはそのファイルを見ていません。
読み込まれているのに守られない場合は、指示が曖昧になっていないか、他のファイルと矛盾していないかを確認します。
コミット前に必ずLintを実行するなど、確実に実行させたい処理は、CLAUDE.mdではなくHooksで設定するのが確実です。
/compact後に指示が消えたとき
プロジェクトルートのCLAUDE.mdは、コンパクト後にディスクから再度読み込まれるため消えることはありません。
消えてしまうのは、チャットの中だけで伝えた指示です。何度も伝えている指示は、CLAUDE.mdに書いておきましょう。
さいごに
Claude Codeがセッションをまたいで情報を記憶する仕組みとして、CLAUDE.mdと自動メモリについてまとめました。
どちらも最終的にはコンテキストに読み込まれるものなので、簡潔に保つことが大切です。同じ指示を2回したらCLAUDE.mdに書く、くらいの感覚で育てていくのが良さそうです。
おすすめ書籍
