Claude Codeのメモリ管理入門 — CLAUDE.mdとMEMORY.mdの仕組みと使い方

「さっき伝えたはずなのに」を、なくすところから

新しいセッションを開くたびに、同じ前提をもう一度打ち込んでいる。そんな瞬間はないでしょうか。「このプロジェクトはTypeScriptです」「テストはVitestで」「コミットメッセージは日本語で」——私自身、Claude Codeを使い始めた頃は、毎回このやり取りから作業を始めていました。指示そのものは一分で済むのに、それを毎回繰り返すと、集中が細切れになります。

いまは違います。個人開発で複数のサイトをClaude Codeで自動運用している関係で、どのセッションも冒頭でCLAUDE.mdとMEMORY.mdが自動的に読み込まれるようにしてあります。前提を伝え直す時間がほぼゼロになり、そのぶんすぐ本題に入れる。ここで整理するのは、その土台になっているメモリシステムの仕組みと、最初の一歩の踏み出し方です。

CLAUDE.mdとは — プロジェクトの取扱説明書

CLAUDE.mdは、プロジェクトのルートディレクトリに置く設定ファイルです。Claude Codeはセッション開始時にこのファイルを自動的に読み込み、記載された指示に従って動作します。

CLAUDE.mdに書くべき内容

CLAUDE.mdは「このプロジェクトでClaude Codeがどう振る舞うべきか」を定義するファイルです。以下のような情報を記載するのが効果的です。

# プロジェクト概要
Next.js 16 + TypeScript + Tailwind CSSのWebアプリケーション。
Cloudflare Workersにデプロイしている。
 
# 開発ルール
- テストフレームワークはVitest を使用
- コミットメッセージは日本語で書く
- CSS-in-JSは使わず、Tailwind CSSのユーティリティクラスを使う
 
# ディレクトリ構造
- src/app/ — App Routerのページ
- src/components/ — 共通コンポーネント
- src/lib/ — ユーティリティ関数

私の経験では、最初から欲張らないことが長続きのコツです。技術スタックとディレクトリ構造の二つだけでも、Claudeの初手の精度は目に見えて変わります。運用しながら「毎回言い直していること」を見つけるたびに、一行ずつ足していく。その積み重ねが、結局いちばん実態に合ったファイルになります。

CLAUDE.mdの配置場所と優先順位

Claude Codeは複数のCLAUDE.mdを階層的に読み込みます。

~/.claude/CLAUDE.md          ← グローバル設定（全プロジェクト共通）
./CLAUDE.md                  ← プロジェクトルート（最も一般的）
./src/CLAUDE.md              ← サブディレクトリ固有の設定

下位のファイルほど優先度が高く、特定のディレクトリ内での作業時にはそのディレクトリのCLAUDE.mdが追加で適用されます。たとえば、フロントエンドとバックエンドでコーディング規約が異なるモノレポでは、それぞれのディレクトリに別々のCLAUDE.mdを置くことで、文脈に応じた指示を自動的に切り替えられます。

MEMORY.md — 会話から学んだ知識の蓄積

CLAUDE.mdがプロジェクトの静的なルールを定義するのに対し、MEMORY.mdはClaude Codeとのやりとりの中で蓄積される動的な知識ベースです。

メモリの種類

Claude Codeのメモリは、主に以下の4つのタイプに分類されます。

メモリが保存される仕組み

Claude Codeは会話の中で重要な情報を検知すると、自動的にメモリファイルを作成します。たとえば、「テストではデータベースをモックしないでほしい」と指示すると、以下のようなファイルが作成されます。

---
name: feedback_no_mock_db
description: テストではDBモックを使わず実DBを使用する
type: feedback
---
 
テストでは実データベースを使用し、モックは使わない。
 
**Why:** 過去にモック/本番の乖離でマイグレーションの破損が検出できなかった。
**How to apply:** integration テスト作成時、DB接続は実環境を使う。

この情報はMEMORY.mdのインデックスに登録され、次回以降のセッションで自動的に参照されます。ひとつのファイルにはひとつの事実だけを書き、本文の**Why:**で背景を残しておくと、後から読み返したときに「なぜこの指示だったのか」を取り違えずに済みます。

実際にメモリを活用してみよう

ステップ1: CLAUDE.mdを作成する

プロジェクトのルートディレクトリで、以下のコマンドを実行します。

# CLAUDE.mdを作成
cat << 'MEMO' > CLAUDE.md
# プロジェクト設定
 
## 技術スタック
- Next.js 16 (App Router) + TypeScript
- パッケージマネージャ: pnpm
- テスト: Vitest + Testing Library
 
## コーディング規約
- 関数コンポーネントのみ使用（クラスコンポーネント禁止）
- named exportを推奨（default exportは避ける）
- コミットメッセージはConventional Commitsに従う
MEMO
 
echo "✅ CLAUDE.mdを作成しました"
# 出力: ✅ CLAUDE.mdを作成しました

ステップ2: メモリの蓄積を確認する

Claude Codeとの会話中に、Claudeに対して好みや指示を伝えてみましょう。

あなた: テストを書くときは、describeブロックは日本語で書いてください。
Claude: 承知しました。今後テストのdescribeブロックは日本語で記述します。
        （→ メモリに自動保存）

保存されたメモリは.auto-memory/ディレクトリで確認できます。

# メモリの一覧を確認
ls .auto-memory/
# 出力例:
# MEMORY.md
# feedback_test_describe_japanese.md
# user_profile.md

ステップ3: メモリインデックスを確認する

MEMORY.mdには、保存されたメモリファイルへのリンクが記録されています。

cat .auto-memory/MEMORY.md
# 出力例:
# # Memory Index
# ## Feedback
# - [feedback_test_describe_japanese.md] — テストのdescribeブロックは日本語で書く

運用してわかった、メモリを腐らせないコツ

仕組みを知ることと、長く使い続けられる形に保つことは、別の技術です。私が複数プロジェクトでメモリを回すうちに、いくつか手痛い遠回りをして身についた運用の型を、正直に共有します。公式ドキュメントには載っていない、実地の勘所です。

ひとつ目は、1ファイルに1つの事実だけを書くこと。ひとつのファイルに複数の話題を詰めると、片方が古くなったときに全体を消すか残すかで迷います。粒を小さく保つと、間違ったメモリだけを外科的に消せます。

ふたつ目は、MEMORY.mdは索引に徹すること。ここに事実そのものを書き込みたくなりますが、太らせると読み込みが重くなります。「1メモリ＝1行のリンクと一言」に留め、中身は各ファイルへ逃がす。索引が薄いほど、必要な記憶を素早くたぐり寄せられます。

三つ目は、重要な事実ほど先頭に置くこと。自動読み込みは常に全文が丸ごと届くとは限らず、長くなると先頭が優先される場面があります。頻繁に効かせたい規約は上に、めったに参照しない補足は下に。この並べ替えだけで、効き目が安定します。

四つ目は、古いメモリは指し示す前に確認すること。「このファイルではAを使う」というメモリが残っていても、リファクタでAが消えていることは珍しくありません。メモリはあくまで「書かれた当時の事実」です。ファイル名・関数・フラグを指す記憶は、いま実在するかを一度確かめてから頼る。これを習慣にすると、古い前提に引きずられた提案が減ります。

最後に、関連するメモリは本文中で[[ファイル名]]のようにゆるくつないでおくと、後から関連情報をたどりやすくなります。まだ存在しないメモリへのリンクを先に書いておいても構いません。「いずれ書くべきこと」の付箋として機能します。

まとめ — メモリ管理はClaude Codeの生産性を左右する

Claude Codeのメモリシステムは、AIとの協業を継続的に改善していくための基盤です。CLAUDE.mdでプロジェクトのルールを明文化し、MEMORY.mdで会話から学んだ知識を蓄積することで、セッションを重ねるほどClaudeの応答精度が上がっていきます。仕組みそのものより、腐らせずに育て続ける運用のほうが、効果を大きく左右すると感じています。

まずは今日、使っているプロジェクトにCLAUDE.mdを1つ作成するところから始めてみてください。技術スタックとディレクトリ構造を書くだけでも、体感できる効果は大きいはずです。一週間ほど使ってみて、「毎回言い直していること」に気づいたら、それをそのまま一行足す。その繰り返しが、あなたの手に一番なじむメモリへと育ててくれます。

私自身もまだ運用の型を磨いている途中です。あなたのプロジェクトでも、メモリが少しずつ賢く育っていくことを願っています。