【Claude Code 連載 第5回】CLAUDE.md と自動メモリ——セッションをまたいで覚えさせる

背景

この連載では、Claude Codeの公式ドキュメントを1ページずつ読み解いていきます。公式ドキュメントは情報が網羅されている分、「結局どの機能を、どんな場面で使えばいいのか」は自分で考える必要があり、読むのに意外と時間がかかります。そこで、私が実務で使うために読み込んだ内容を「使う場面→実例コード」の順に整理して残していくことにしました。専門家の解説というより、一次情報を読んだ記録です。推測や動作を確認していない部分には、その都度そう書きます。

1. これは一言でいうと何か

Claude Code のセッションは、毎回新しいコンテキストウィンドウで始まります。それをまたいで知識を保持する仕組みが 2 つあります。CLAUDE.md ファイル（あなたが書く永続的な指示）と、自動メモリ（あなたの修正や好みに基づいて Claude が自分で書くメモ）です。どちらも各会話の開始時に読み込まれます。

重要な前提が 1 つあります。Claude はこれらをコンテキストとして扱い、強制的な設定としては扱いません。 アクションをブロックしたいなら、Claude の判断に関わらず発火する PreToolUse hook（ツール実行前に発火するフック）を使う必要があります。

2. どういう場面で役立つか

CLAUDE.md は「そうでなければもう一度説明することになる場所」だと考えてください。ページが挙げるトリガーは明快です。

• 同じ指摘が繰り返されるとき：Claude が 2 回目に同じ間違いを犯した、あるいはコードレビューで「Claude がこのコードベースについて知っておくべきだった」ことを指摘された——これが追加のサインです。
• 新メンバーのオンボーディングと同じ情報が要るとき：ビルドコマンド、規約、プロジェクトレイアウト、「常に X を実行する」ルール。人間の新人に渡す情報とほぼ重なります。
• モノレポなど、指示が肥大化してきたとき：.claude/rules/ に分割し、paths でファイルパスにスコープできます。一致するファイルを読むときだけ読み込まれるので、ノイズとコンテキストを節約できます。
• 他エージェント用の AGENTS.md が既にあるリポジトリ：Claude Code は AGENTS.md ではなく CLAUDE.md を読みます。CLAUDE.md からインポートすれば、重複なく両ツールで同じ指示を使えます。

向かないケース・不要なケース。 複数ステップの手順や、コードベースの 1 か所にしか関係しない内容は CLAUDE.md に置くべきではありません。前者は Skill、後者はパススコープルールに移します。さらに重要なのは、「必ず守らせたいこと」を CLAUDE.md に書いても保証にはならない点です。特定のタイミングで必ず走らせたい処理（コミット前、ファイル編集後など）は hook に、ツールやコマンド、ファイルパスのブロックは管理設定の permissions.deny に置きます。CLAUDE.md は行動ガイダンス、設定は技術的な強制です。

3. コード・コマンドの実例と解説

前提条件

• 自動メモリには Claude Code v2.1.59 以降が必要です。claude --version で確認できます（自動メモリはデフォルトで有効）。
• CLAUDE.md の主な置き場所は 4 つです。管理ポリシー（組織全体）、ユーザー指示 ~/.claude/CLAUDE.md、プロジェクト指示 ./CLAUDE.md または ./.claude/CLAUDE.md、ローカル指示 ./CLAUDE.local.md（.gitignore 対象）。読み込みはこの順（広い→具体的）です。
• ゼロから書く必要はありません。/init を実行すると Claude がコードベースを分析し、ビルドコマンド・テスト指示・規約を含む CLAUDE.md を生成します。既存ファイルは上書きせず改善を提案します。

他ファイルをインポートする

プロジェクト概要については @README を参照し、このプロジェクトで利用可能な npm コマンドについては @package.json を参照してください。

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

CLAUDE.md 内で @path/to/import と書くと、そのファイルが展開されて起動時に一緒に読み込まれます。相対パスは「インポートを含むファイル」に相対で解決され、再帰インポートは最大 4 ホップです。注意点として、インポートしてもコンテキスト削減にはなりません（起動時に読み込まれるため）。整理目的と割り切ってください。

.claude/rules/ に分割する

your-project/
├── .claude/
│   ├── CLAUDE.md           # メインプロジェクト指示
│   └── rules/
│       ├── code-style.md   # コードスタイルガイドライン
│       ├── testing.md      # テスト規約
│       └── security.md     # セキュリティ要件

.claude/rules/ 配下のマークダウンファイルは再帰的に発見され、1 ファイル 1 トピックで整理します。paths frontmatter を持たないルールは、.claude/CLAUDE.md と同じ優先度で起動時に読み込まれます。

ルールをファイルパスにスコープする

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

# API 開発ルール

- すべての API エンドポイントは入力検証を含める必要があります
- 標準エラー応答形式を使用します
- OpenAPI ドキュメンテーションコメントを含めます

YAML frontmatter の paths にグロブを書くと、Claude が一致するファイルを読むときにだけこのルールが適用されます。全ツール使用時ではなく「一致ファイルを読むとき」がトリガーです。ここが CLAUDE.md との実質的な差で、モノレポでコンテキストを節約する主な手段になります。

AGENTS.md を再利用する

@AGENTS.md

## Claude Code

`src/billing/` の下の変更には Plan Mode を使用します。

既存の AGENTS.md をインポートし、その下に Claude 固有の指示を足す形です。Claude はインポートされたファイルをセッション開始時に読み込み、その後に残りを追加します。

自動メモリの保存場所

~/.claude/projects/<project>/memory/
├── MEMORY.md          # 簡潔なインデックス、すべてのセッションに読み込まれます
├── debugging.md       # デバッグパターンの詳細なメモ
├── api-conventions.md # API 設計の決定
└── ...                # Claude が作成するその他のトピックファイル

MEMORY.md は先頭 200 行または 25KB（先に来るほう）だけが毎セッション読み込まれ、debugging.md などのトピックファイルは起動時には読み込まれず、必要になった時点で Claude がオンデマンドで読みます。中身はプレーンマークダウンなので、いつでも編集・削除できます。セッション中に /memory を実行すると、読み込まれている CLAUDE.md・ルールファイルの一覧表示、自動メモリのオン/オフ切り替え、メモリフォルダを開く操作ができます。

autoMemoryEnabled / autoMemoryDirectory / claudeMdExcludes（モノレポで他チームの CLAUDE.md をスキップする設定）、管理設定の claudeMd キーなどは公式ドキュメントを参照してください。

4. まとめと次回予告

• 「あなたが書く CLAUDE.md」と「Claude が書く自動メモリ」の 2 本立て。どちらも毎セッション読み込まれます。
• どちらもコンテキストであって強制ではありません。必ず守らせたいものは hook や permissions.deny に置きます。
• 1 ファイル 200 行以下を目標に。溢れたら .claude/rules/ のパススコープに逃がすのが定石です。

トラブルシュートで最も効く事実：CLAUDE.md はシステムプロンプトそのものではなく、システムプロンプトの後にユーザーメッセージとして配信されます。だから「読んで従おうとする」が、厳密な遵守は保証されません。従っていないと感じたら、まず /memory で読み込まれているかを確認し、次に指示の具体性と矛盾を疑ってください。なお /compact 後、プロジェクトルートの CLAUDE.md は再読み込みされて再注入されますが、サブディレクトリのネストされた CLAUDE.md は自動では再注入されません。

次回予告：オンデマンドで読み込まれる「Skills」を取り上げます。

関連ページ（本記事で触れた概念の詳細）：hook →「Hooks」、Skill →「Skills」、強制設定 →「設定」「権限」、圧縮後の残存 →「コンテキストウィンドウ」、モノレポ構成 →「モノレポと大規模リポジトリ」、subagent の自動メモリ →「サブエージェント」。

---

本記事は執筆時点の公式ドキュメント（Claude があなたのプロジェクトを記憶する方法）に基づきます。最新は公式ドキュメントをご確認ください。