はじめに
Claude Codeを初めて使ったとき、こんな経験はありませんか。
- 「うちのプロジェクトはTypeScriptなんだけど」と毎回伝えている
- 「テストはVitest使って」と何度も指示している
- 昨日決めた設計方針を今日また最初から説明している
Claude Codeは、CLAUDE.mdなしだと「毎回初対面の優秀なエンジニア」です。技術力は高いのに、プロジェクトのことを何も知らない。そのギャップを埋めるのがCLAUDE.mdであり、さらにセッションを跨いで「学習」させるのがメモリの仕組みです。
この記事では、CLAUDE.mdの書き方を基礎から解説した後、セッション横断で知識を蓄積する「メモリ3階層設計」まで踏み込みます。筆者が半年ほどClaude Codeを日常の開発で使い込んで得た運用知見と、公式ドキュメント、コミュニティで話題になった実装例を組み合わせた内容です。
この記事で扱う「メモリ」の位置づけ
「メモリ」という言葉はAIツールごとに意味が違います。先に整理しておきます。
| ツール | メモリの性質 |
|---|---|
| ChatGPT Memory | サービス側がユーザー発言から勝手に覚える。ユーザーはオンオフと閲覧のみ |
| Cursor Rules | リポジトリ内の .mdc ファイル。パスやファイルタイプでスコープ可能 |
| GitHub Copilot Custom Instructions | リポジトリ or ユーザー単位のプレーンテキスト |
| Claude Code CLAUDE.md + Auto Memory | ローカルのMarkdownをユーザーが書く「CLAUDE.md」と、Claude自身が書き足す「Auto Memory」の二系統 |
Claude Codeの特徴は、ユーザーが書く層とAIが書く層が分離されていて、さらにどちらもプレーンMarkdownのためGitや手動編集で自由に触れる点です。この二系統をどう設計するかで、Claude Codeの出力品質は大きく変わります。
前半：CLAUDE.mdで出力品質を変える
CLAUDE.mdとは何か
CLAUDE.mdは、Claude Codeがセッション開始時に自動で読み込む指示書です。プロジェクトのルートディレクトリに置くだけで、毎回の口頭説明が不要になります。
公式ドキュメント（How Claude remembers your project）では、CLAUDE.mdを次のように位置づけています。
Treat CLAUDE.md as the place you write down what you'd otherwise re-explain.
（毎回説明し直すことになる内容を書き留める場所として扱う）
つまりCLAUDE.mdは「面倒で毎回言っていること」を書くファイルです。逆に言えば、書くべき内容の判断基準は「もう一度説明したいかどうか」の一点に絞れます。
配置場所によって読み込みスコープが異なります。公式仕様では優先順位が明確に決まっており、より狭いスコープが広いスコープを上書きします。
| 配置場所 | スコープ | 用途 | Git管理 |
|---|---|---|---|
管理ポリシー（/Library/Application Support/ClaudeCode/CLAUDE.md 等） |
組織全体 | セキュリティポリシー、コンプライアンス要件 | IT/DevOps管理 |
~/.claude/CLAUDE.md |
全プロジェクト共通 | 個人の文体、常用ツール、行動原則 | 個人 |
プロジェクトルート ./CLAUDE.md or ./.claude/CLAUDE.md
|
特定プロジェクト | 技術スタック、規約、禁止事項 | チーム共有 |
./CLAUDE.local.md |
特定プロジェクト・個人 | ローカル環境設定、個人的な好み |
.gitignore 対象 |
.claude/rules/*.md |
トピック別 | ファイルパスで絞れる詳細ルール | チーム共有 |
興味深いのは、Claude Codeはカレントディレクトリから親を辿って見つけた全てのCLAUDE.mdを連結して読み込む点です。foo/bar/ で起動すれば foo/bar/CLAUDE.md と foo/CLAUDE.md が両方読み込まれ、階層的な指示書として機能します。モノレポで共通ルールと個別ルールを自然に共存させられます。
なぜCLAUDE.mdが必要になったのか
Claude Codeの設計思想を理解すると、CLAUDE.mdの存在意義がより腑に落ちます。
LLMを組み込んだコーディングエージェントは、「システムプロンプトで全ての前提を渡す」方式では限界があります。プロジェクトごとに違う技術スタックや規約を全てシステムプロンプトに詰め込むと、汎用性が失われ、トークンも無駄になります。
そこでClaude Codeは、セッション開始時にユーザーメッセージとしてCLAUDE.mdを注入するというアーキテクチャを採用しました。公式ドキュメントにも次の記述があります。
CLAUDE.md content is delivered as a user message after the system prompt, not as part of the system prompt itself.
これは重要なポイントです。CLAUDE.mdは「システムプロンプトと同等の強制力」ではなく「ユーザーが毎回冒頭で投げる指示」です。だからこそ、曖昧な表現は効きません。人間に対する指示と同じで、具体的で検証可能な文言でなければ守られないのです。
最小限のCLAUDE.mdを書く
まずは4セクションだけで十分です。以下はコピーしてそのまま使えるテンプレートです。
# プロジェクト設定
## プロジェクト概要
ECサイトのバックエンドAPI。注文管理・在庫管理・ユーザー認証を担当する。
## 技術スタック
- 言語: TypeScript 5.x
- ランタイム: Node.js 22
- フレームワーク: Fastify 5
- ORM: Prisma 6
- テスト: Vitest
- DB: PostgreSQL 16
## コーディング規約
- 関数は1つの責務のみ持つ。50行を超えたら分割を検討する
- エラーハンドリングはResult型パターンを使う。throw禁止
- 変更したファイルに対応するテストファイルが存在する場合、テストも更新する
- APIエンドポイント追加時はOpenAPIスキーマも同時に更新する
## 禁止事項
- any型の使用禁止。unknown + 型ガードで対応する
- console.logによるデバッグ禁止。loggerモジュールを使う
- node_modules内のファイルを直接編集しない
この程度であれば3分で書けます。しかし、この3分の投資で「TypeScript使って」「テストも書いて」「anyは使わないで」といった反復指示がすべて消えます。
公式ドキュメントは 200行以内 を推奨しています。長すぎるとトークンを消費するだけでなく、Claudeの遵守率が下がるためです。大きくなってきたら @path/to/file.md のインポート構文で分割するか、.claude/rules/ に移動するのが定石です。
効果的なルールの書き方
CLAUDE.mdのルールは「具体的で検証可能」であることが重要です。以下に良い例と悪い例を5組示します。
判断基準はシンプルです。そのルールを読んだ別のエンジニアが「守れたかどうか」を客観的に判定できるなら、良いルールです。
| # | 悪い例 | 良い例 |
|---|---|---|
| 1 | きれいなコードを書く | 関数は50行以内。超える場合は分割してヘルパー関数を作る |
| 2 | テストを書いて | 変更したファイルに対応する *.test.ts が存在する場合、テストも更新する |
| 3 | セキュリティに気をつけて | ユーザー入力は必ずzodスキーマでバリデーションする。SQLは必ずパラメータ化クエリを使う |
| 4 | コミットメッセージをちゃんと書く | コミットメッセージはConventional Commits形式（feat:, fix:, docs:）で書く |
| 5 | パフォーマンスを意識して | N+1クエリを避ける。関連データはincludeで一括取得する。ループ内でDBアクセスしない |
悪い例に共通するのは「解釈の幅が広すぎる」ことです。「きれいなコード」の定義は人によって違いますが、「50行以内」は誰が見ても同じ判定になります。公式ドキュメントの表現を借りれば、 "Use 2-space indentation" instead of "Format code properly" というレベルの具体性が必要です。
よくある失敗パターン10個と対処法
CLAUDE.mdを書き始めると陥りやすい落とし穴を10個まとめます。前半は筆者自身が踏んだもの、後半はコミュニティで見かける相談事例です。
| # | 失敗 | 症状 | 対処法 |
|---|---|---|---|
| 1 | 制約の詰め込みすぎ | 500行超のCLAUDE.md。どれも守られない | 200行以内に削減、詳細は .claude/rules/ へ分割 |
| 2 | 曖昧な表現 | 「きれいに」「適切に」「ちゃんと」が並ぶ | 数値・ファイル名・コマンド名で具体化する |
| 3 | メンテナンスの放置 | 古い技術スタックが残り誤った前提で動作 | 技術選定が変わったらCLAUDE.mdも同コミットで更新 |
| 4 | 矛盾するルールの共存 | グローバルとプロジェクトで方針がぶつかる |
/memory で読み込みファイルを確認し整理 |
| 5 | 機密情報の混入 | クライアント名・APIキーがGitに残る |
CLAUDE.local.md + .gitignore に分離 |
| 6 | コピペテンプレの放置 | 他プロジェクトのルールが残りノイズに | プロジェクト初期化時に必ず読み返す |
| 7 | 個人の好みがチーム用に混入 | チームCLAUDE.mdに個人の文体指示 | 個人用は ~/.claude/CLAUDE.md に書く |
| 8 | Do だけで Don't がない | 禁止事項が明示されず事故が起きる | 「何をしないか」を必ず1セクション設ける |
| 9 | プロジェクト概要の欠落 | Claudeが目的を誤解した提案をする | 1〜2行で「何を作っているか」を冒頭に書く |
| 10 | 更新履歴なし | いつのルールか分からず棚卸しできない | 節目のコミットにタグを打つ、日付コメントを添える |
特に5番と7番は見落とされがちです。CLAUDE.mdはGitで管理されるため、うっかりクライアント名や契約金額を書くと公開リポジトリでそのまま漏洩します。個人用は ~/.claude/CLAUDE.md または CLAUDE.local.md に分離する癖をつけてください。
ルールがなかった時に起きた具体的失敗
抽象論だけでは実感が湧かないので、筆者自身がCLAUDE.md導入前に踏んだ失敗を5つ紹介します。これらはそのまま「なぜそのルールが必要か」の動機になっています。
1つ目。いきなりコードを書き始めて設計が破綻した ケース。あるAPIの追加を依頼したら、Claudeは既存の類似エンドポイントを読まずに独自のパターンで実装しました。後から既存コードと統合する段階で「認証ミドルウェアが重複している」「エラー型が違う」などの手戻りが発生し、結局ゼロから書き直しました。以降「3ステップ以上のタスクはPlanモード必須」というルールを入れています。
2つ目。場当たり的なパッチを重ねてコードが腐敗した ケース。テスト失敗を「とりあえず動かす」方向で修正した結果、元の意図と違う形で通ってしまい、本番でバグが再発しました。「うまくいかなくなったら立ち止まって再計画する」というルールは、この経験から生まれました。
3つ目。読まずに書いて既存関数と重複した ケース。コンテキストが逼迫してくると、Claude Codeは既存コードを読まずに「たぶんこうなっているだろう」で書き始めます。その結果、既存のバリデーション関数と同じものが別名で再実装されたり、存在しないインポートパスを指定したりします。「コードを読まずに書かない」を明文化してから、この事故がほぼゼロになりました。
4つ目。生成ファイルがリポジトリに散乱した ケース。Claudeが出力した調査メモやスクリプトがプロジェクトルート直下に溜まり、git status がノイズだらけになりました。「ファイルは output/ に出力し、公開前にユーザー確認を取る」で解決しました。
5つ目。依頼していない変更を勝手に入れた ケース。「この設計の方が良いと判断したので変更しました」と、依頼範囲外のリファクタが混入しました。AI駆動開発における意思決定の主体は常に人間である必要があるため、「重要な判断を独断で進めない」というルールを追加しています。
いずれも「一度痛い目を見てからルール化した」パターンです。最初から完璧なCLAUDE.mdを書く必要はありません。失敗の後にその場で1行追加する のが、形骸化しない育て方です。
後半：メモリ3階層でセッション跨ぎの知識を蓄積する
CLAUDE.mdだけでもClaude Codeの出力品質は大きく改善されます。しかし、使い込んでいくと別の課題が見えてきます。
- 「先週のセッションで決めた設計方針、覚えてる？」→ 覚えていない
- 「前回のバグ修正で学んだパターン、次も活かして」→ 知らない
CLAUDE.mdは「不変のルール」を伝えるのに適していますが、セッション中に生まれる知見や意思決定を蓄積する仕組みにはなっていません。ここで登場するのがメモリの3階層設計です。
Auto Memoryという新しい仕組み
最近のClaude Codeには、公式に Auto Memory という機能が入りました。これはClaude自身が「これは次回も使えそうだ」と判断した内容を ~/.claude/projects/<プロジェクトパス>/memory/MEMORY.md に自動で書き足す仕組みです（導入バージョンは更新にともない変動するため、最新の公式ドキュメントを参照してください）。
公式ドキュメントの表現を引用します。
Auto memory lets Claude accumulate knowledge across sessions without you writing anything.
Claude doesn't save something every session. It decides what's worth remembering based on whether the information would be useful in a future conversation.
特徴を整理すると次のとおりです。
-
MEMORY.mdの 先頭200行または25KB がセッション開始時に自動で読み込まれる - それを超える内容は別トピックファイル（例:
debugging.md）に切り出され、必要になった時だけ読み込まれる - プロジェクトルートのCLAUDE.mdは
/compact後にも再注入されるが、ネストされたCLAUDE.mdは再注入されない - Auto Memoryはマシンローカルで、worktreeやサブディレクトリは同じgitリポジトリなら共有される
この仕組みは「覚えている」から「学んでいる」への重要な一歩ですが、Auto Memoryだけに任せると運用が破綻します。なぜなら、Claudeが何を覚えているかブラックボックスになり、腐敗検出が難しくなるからです。そこで、ユーザー側で階層を明示的に設計する発想が生まれました。
3階層の全体像
この設計は、Claude Codeのメモリを3階層にしたら「覚えてる」が「学んでる」に変わった（Zenn、TOKIUM PdMのまっさん氏、100いいね超）の考え方を参考にしています。この記事では、人間の脳科学における記憶の分類（短期記憶・長期記憶・手続き記憶）になぞらえて、Claude Codeのメモリを次の3層に分けています。
第1層: CLAUDE.md ─── 永続的な行動規範（変わらない原則 / 手続き記憶相当）
第2層: MEMORY.md ─── セッション横断の学習記録（蓄積される知見 / 長期記憶相当）
第3層: プロジェクトメモリ ─ 意思決定・進捗の記録（文脈の保存 / 作業記憶相当）
| 階層 | ファイル | 性質 | 更新頻度 | 書き手 |
|---|---|---|---|---|
| 第1層 | CLAUDE.md |
憲法。プロジェクトの基本法 | 月1回程度 | 人間 |
| 第2層 | MEMORY.md |
学習ノート。セッション間の観察 | セッションごと | Claude（Auto Memory） |
| 第3層 |
decisions.md, context-log.md 等 |
業務日誌。具体的な意思決定 | 随時 | 人間（+ Claudeの下書き） |
なぜ3階層なのか──2階層や4階層ではだめか
「CLAUDE.mdとMEMORY.mdの2階層でいいのでは？」という疑問は自然です。実際、筆者も最初は2階層で始めました。しかし運用していくうちに、2階層では次の問題が起きます。
問題1: MEMORY.mdが肥大化する。セッションで学んだこと・決めたこと・観察したことが全て1箇所に溜まると、200行制限をすぐに超えます。超えた部分は別ファイルに自動分離されますが、「どこに何があるか」が分からなくなります。
問題2: 不変のルールと可変の知見が混ざる。「テストはVitestを使う」というプロジェクトの憲法と、「このライブラリの初期化は非同期で待つ必要がある」という発見が同じファイルに並ぶと、棚卸しのたびに判断がぶれます。前者は削除してはいけない、後者はライブラリ更新で不要になる、という性質の違いを区別できなくなるのです。
問題3: 意思決定の理由が失われる。「なぜPrismaからDrizzleに移行したか」という意思決定の背景は、MEMORY.mdに書くには長すぎ、CLAUDE.mdに書くには変わりやすい情報です。
3階層にする理由は、情報の寿命が違うものを混在させない という一点に尽きます。
- 第1層（不変のルール）: プロジェクト存続中ずっと有効
- 第2層（学習記録）: 環境や依存が変わるまで有効
- 第3層（意思決定）: 判断の背景として永続記録
逆に4階層や5階層にすると、どこに書けばいいか迷う時間が増え、結局使われなくなります。筆者の経験上、3階層が「十分な分離」と「書く場所で迷わない」のバランスです。
各階層に何を書くか、何を書かないか
それぞれの階層に適した情報と、書くべきでない情報を整理します。理由も添えます。
第1層：CLAUDE.md
書くべきもの：
- 技術スタック（言語・フレームワーク・DB・テストツール）
- コーディング規約（命名・エラー処理・ファイル分割基準）
- ディレクトリ構造（どこに何があるか）
- 禁止事項（any型禁止、console.log禁止 等）
- 行動原則（Planモード必須条件、レビュー前の確認項目）
書くべきでないもの：
- 進行中タスク（数日で古くなる）
- 特定のバグの調査記録（一過性の情報）
- ライブラリの細かい挙動（バージョン更新で変わる）
理由は明快です。CLAUDE.mdは毎セッション読まれるため、頻繁に変わる情報を書くとメンテナンスコストが跳ね上がる からです。
第2層：MEMORY.md
書くべきもの：
- 開発環境の癖（「このプロジェクトのE2Eテストは並列だと認証トークンが競合する」）
- ライブラリの初期化手順（「Playwrightはヘッドレスで実行」）
- 頻繁に参照するコマンド（ビルド・デプロイ・seed投入）
- Claudeが何度か間違えて修正された内容（Auto Memoryが自動で書き足す）
書くべきでないもの：
- プロジェクトの憲法レベルの規約（第1層に書くべき）
- 一度きりの作業ログ（第3層に書くべき）
理由は、MEMORY.mdの先頭200行しかセッション開始時に読み込まれないという仕様です。ここには 「次回セッションで即座に役立つ、圧縮された知見」だけ を入れる必要があります。
# Memory
## 開発環境
- Playwrightはヘッドレスモードで実行する
- Docker Composeでの起動はdb→api→workerの順序が必要
## テスト
- E2Eテストは並列実行すると認証トークンが競合する。直列で実行すること
- seed dataの投入はテストごとにリセットが必要
## デプロイ
- staging環境はCloudflare Tunnel経由。ローカルからcurl確認可能
第3層：プロジェクトメモリ
書くべきもの：
- 意思決定の記録（決定・根拠・日付）
- プロジェクト進捗（マイルストーンの達成）
- 過去の判断パターン（類似の判断が求められた時の参照元）
書くべきでないもの：
- Claudeが毎回読む必要がある内容（第1層に書くべき）
- 圧縮できる恒常的な知見（第2層に書くべき）
筆者の場合、以下の4ファイルに分けて管理しています。
| ファイル | 内容 | 記録例 |
|---|---|---|
decisions.md |
意思決定の記録 | 「ORMをPrismaからDrizzleに移行する。理由: エッジランタイム対応」 |
context-log.md |
プロジェクト進捗 | 「認証基盤の実装完了。OAuth2.0 + PKCE対応」 |
preferences.md |
好み・方針 | 「エラーメッセージは日本語で統一」 |
case-judgment-framework.md |
教訓・判断基準 | 「DBマイグレーションは必ずロールバックスクリプトも用意する」 |
第3層は必要になった時だけClaudeに読ませる設計です。CLAUDE.mdからインポートすると毎セッション読まれてしまうので、スキルや明示的な参照 で呼び出します。
「覚えてる」から「学んでる」への進化メカニズム
前述のTOKIUM記事で紹介されている、興味深いメカニズムを一つ掘り下げます。それは pain_count（痛みカウンタ） という考え方です。
同じ指摘をClaudeに対して何度も繰り返すとき、そのフィードバックには「痛み」が溜まっています。1回目はうっかりミス、2回目は注意不足、3回目は仕組みの問題です。TOKIUM記事の著者は、次のルールでメモリを運用しているそうです。
- 新規フィードバックを記録する際、既存メモリと照合する
- 同じ趣旨があれば新しいファイルを作らず、既存メモの
pain_countを +1 する -
pain_count >= 3に達したフィードバックは、単なるメモから CLAUDE.mdのルール またはスキル・フックに昇格させる
これは人間の学習プロセスと同じです。最初は「意識しないとできない」段階だったものが、何度も繰り返すうちに「意識しなくてもできる」段階に移行する。その移行を明示的にメモリ階層で表現しているのです。
| 学習段階 | 状態 | Claude Codeでの対応 | 強制力 |
|---|---|---|---|
| 1 | 知らない | Auto Memoryが観察して記録 | Lv.0 |
| 2 | 意識すればできる | MEMORY.md参照 | Lv.1 |
| 3 | 繰り返し指摘が必要 | CLAUDE.mdルール化 | Lv.2 |
| 4 | 自動的にやる | スキルまたはフック | Lv.3-4 |
このメカニズムが示唆するのは、CLAUDE.mdに最初から全てを書く必要はない ということです。Lv.1とLv.2の境界線を pain_count で機械的に判定する運用にすれば、本当に必要なものだけが昇格していきます。結果としてCLAUDE.mdは肥大化せず、どのルールも「3回以上の実体験から生まれた必要なルール」になります。
筆者自身もこの考え方を取り入れてから、CLAUDE.mdの更新がぐっと楽になりました。気になった瞬間にすぐ追記するのではなく、「今の指摘は何回目か」を意識するようになったのです。
CLAUDE.mdはどのタイミングで読み込まれるか
メモリ運用を設計するには、Claude CodeがいつファイルをReadするかを正確に把握しておく必要があります。公式ドキュメントを元に整理すると次のとおりです。
| タイミング | CLAUDE.md | MEMORY.md | .claude/rules/*.md |
|---|---|---|---|
| セッション起動時 | 全文読み込み | 先頭200行/25KB読み込み |
paths 無しは全件、ありはマッチしたファイル読み込み時 |
/compact 実行後 |
プロジェクトルートは再注入、ネストは再注入されない | 再注入される | 同じ挙動 |
| サブエージェント呼び出し時 | 引き継がれる（サブエージェントも読む） | サブエージェント専用のAuto Memoryあり | 引き継がれる |
| ファイル読み込み時 | サブディレクトリのCLAUDE.mdがオンデマンド読み込み | トピック別ファイル（例: debugging.md）が必要時に読み込み |
paths 指定のルールがマッチ時に読み込み |
この仕様を知っているとメモリ設計の精度が上がります。例えば、「毎回必ず読ませたい内容」はCLAUDE.md本体に、「普段は読まなくていいが特定ディレクトリで作業する時だけ読ませたい内容」は .claude/rules/ に paths フロントマター付きで置く、という使い分けになります。
---
paths:
- "src/api/**/*.ts"
---
# API Development Rules
- 全エンドポイントは zod バリデーションを必須とする
- エラーレスポンスは標準フォーマットを使う
このルールは src/api/ 配下のTypeScriptファイルを読む時だけ読み込まれます。トークンを節約しつつ、関連ファイル作業時には確実に効く仕組みです。
トークン消費から見たメモリ設計
CLAUDE.mdもMEMORY.mdもコンテキストウィンドウのトークンを消費します。どれくらいのコストか、概算を示します。
| ファイル | 行数 | 概算トークン | 毎セッションの消費 |
|---|---|---|---|
| 短いCLAUDE.md | 50行 | 約500トークン | 毎回 |
| 推奨サイズのCLAUDE.md | 200行 | 約2,000トークン | 毎回 |
| 肥大化したCLAUDE.md | 500行 | 約5,000トークン | 毎回 |
| MEMORY.md（先頭200行） | 200行 | 約2,000トークン | 毎回 |
| トピック別ファイル | - | 0トークン | オンデマンド |
200行以内のCLAUDE.mdとMEMORY.mdを合わせて約4,000トークンというのは、現在のClaude Codeのコンテキストウィンドウから見れば十分軽い投資です。しかし、これが500行を超えると「Claudeの注意力を薄める副作用」が発生します。公式ドキュメントも明言していますが、ファイルが長いほど個々のルールの遵守率が下がる のです。
設計の指針はシンプルです。
- CLAUDE.mdは 200行以内
- MEMORY.mdは Auto Memoryに任せて先頭200行相当に自然収束させる
- それ以上の詳細は
.claude/rules/にパス指定で分散、または第3層に移動
メモリの腐敗問題と対策
メモリ運用で最も注意すべきリスクは「情報の腐敗（stale memory）」です。
古くなった情報が残り続けると、Claude Codeが誤った前提で動作します。例えば「DBはMySQL」というメモリが残ったままPostgreSQLに移行していたら、MySQL前提のSQLが生成されます。これはCLAUDE.mdがない状態より悪い結果を招きます。
対策は3つあります。
1つ目は、日付の記録 です。すべてのメモリエントリに日付を付けることで、古さが一目で分かるようになります。
### 2026-04-10: ORMの移行決定
- **決定**: PrismaからDrizzleに移行する
- **根拠**: Cloudflare Workers対応が必要になったため
2つ目は、定期的な棚卸し です。月に1回、メモリファイルを上から読み直し、現状と合わなくなった記述を削除または更新します。筆者はスプリントの振り返りのタイミングでメモリの棚卸しも行っています。/memory コマンドで現在読み込まれているファイル一覧を確認し、不要なものをその場で編集するワークフローが機能します。
3つ目は、矛盾の検出 です。CLAUDE.mdに「メモリの内容と矛盾する情報が出た場合は、ユーザーに確認してから更新」というルールを入れておくと、Claude Code自身が矛盾に気づいて報告してくれます。これは地味ですが効果的です。
メモリに古い情報が残っていると、CLAUDE.mdに正しいルールがあっても上書きされる場合があります。公式ドキュメントにも「矛盾する指示があるとClaudeは任意に選ぶ」と明記されています。メモリの棚卸しはCLAUDE.mdの更新と同じくらい重要です。
実践コーナー
今日から始める3ステップ
ここまで読んで「全部やるのは大変そう」と感じた方も多いと思います。以下の3ステップで段階的に進めれば、無理なく始められます。
ステップ1（今日）。プロジェクトのルートに最小限のCLAUDE.mdを作成します。前半で示した4セクション（プロジェクト概要・技術スタック・コーディング規約・禁止事項）だけで構いません。所要時間は3分です。もっと楽をしたければ /init コマンドを実行すれば、Claude自身がコードベースを解析してCLAUDE.mdのたたき台を生成してくれます。
ステップ2（1週間後）。1週間Claude Codeを使ったら、「毎回同じことを説明している」「毎回修正している」項目をCLAUDE.mdに追記します。実際に困った場面から書くので、形骸化しにくいルールになります。合わせて /memory コマンドで現在読み込まれているファイルを確認し、Auto Memoryが何を勝手に書き足したかも眺めてみてください。
ステップ3（2週間後）。第3層のプロジェクトメモリ（decisions.md など）を追加します。意思決定の理由を残すだけでも、数ヶ月後の自分とClaudeに大きな価値をもたらします。
1週間・1ヶ月・3ヶ月後の進化パス
CLAUDE.mdは一度書いて終わりではなく、時間をかけて育てるものです。各タイミングでの到達目標を示します。
1週間後の到達目標
- CLAUDE.mdが30〜50行程度
- プロジェクトの技術スタックと5個程度の基本ルール
-
~/.claude/CLAUDE.mdに個人の文体・常用ツールを整理
1ヶ月後の到達目標
- CLAUDE.mdが80〜120行程度
- 実際の失敗から生まれた具体的ルールが10個以上
- MEMORY.mdに開発環境の癖が蓄積されている
-
/memoryで読み込みファイルの全体像を把握できている
3ヶ月後の到達目標
- CLAUDE.mdが150〜200行程度で安定
-
.claude/rules/にトピック別ルール（testing.md、api-design.md 等） -
decisions.mdに主要な意思決定10件以上 - 月1回のメモリ棚卸しがワークフローに組み込まれている
- pain_countに近い考え方でルール昇格の判断ができている
3ヶ月を過ぎると、CLAUDE.mdの更新頻度は月1〜2回程度に落ち着きます。これは「育て終わった」のではなく「育てる対象がMEMORY.mdと第3層に移った」という状態です。
筆者のCLAUDE.mdから実際のルール5つ
最後に、筆者が実際に使っている ~/.claude/CLAUDE.md から5つのルールを引用します。それぞれ、なぜそのルールが必要になったかのストーリーも添えます。
1つ目。
- 3ステップ以上 or アーキテクチャに関わるタスクは必ずPlanモードで開始する
これは、Claude Codeがいきなりコードを書き始めて、途中で「やっぱりこの設計だと無理がある」と手戻りが発生したことがきっかけです。複雑なタスクほど、最初に計画を立てさせた方が結果的に速いと学びました。
2つ目。
- 途中でうまくいかなくなったら、無理に進めずすぐに立ち止まって再計画する
エラーが出たとき、Claude Codeが場当たり的なパッチを重ねて、最終的に元のコードより悪い状態になった経験から生まれたルールです。「3回修正しても解決しないなら、アプローチ自体を見直す」というラインを設けています。
3つ目。
- コードを読まずに書かない: ファイルを読んでいないコードを直接書くのは禁止
コンテキストウィンドウが逼迫してくると、Claude Codeは既存コードを読まずに「たぶんこうなっているだろう」で書き始めることがあります。その結果、既存の関数と重複したコードを生成したり、存在しないインポートパスを指定したりします。このルールを入れてから、そうした事故がなくなりました。
4つ目。
- ファイルは output/ に出力し、公開前にユーザー確認を取る
Claude Codeが生成したファイルがプロジェクトルート直下に散乱して、リポジトリが汚れた経験から追加しました。出力先を固定することで、生成物の管理が楽になります。
5つ目。
- 重要な判断を独断で進めない。必ずユーザーに確認を取る
Claude Codeが「この設計の方が良いと判断したので変更しました」と、依頼していない変更を勝手に行ったことがありました。AI駆動開発において、意思決定の主体は常に人間である必要があります。このルールは安全弁として機能しています。
MEMORY.mdに蓄積された学習記録の実例
参考までに、筆者の実際のMEMORY.mdから抜粋した記述を紹介します。いずれも「最初のセッションで指摘したら、次回から勝手に守ってくれるようになった」項目です。
# Memory
## ユーザー設定
- 会話は日本語で行う
- Playwrightはヘッドレスモードで実行する
- Qiita記事の公開後はスクリーンショットで表示崩れを確認する
## プロジェクト情報
- agent-chat プロジェクトの実体は /Users/xxx/dev/agent-chat/ にある
（リポジトリ内ではない。パス混同に注意）
特に「Playwrightはヘッドレスモードで実行する」は、最初に一度「ブラウザが開いて邪魔」と伝えただけで、Auto Memoryが勝手に記録してくれたものです。それ以来、このプロジェクトでPlaywrightを使うタスクでは毎回ヘッドレスで動いています。これが「覚えている」から「学んでいる」への変化の、最も分かりやすい例です。
まとめ
CLAUDE.mdは「3分で書ける投資」です。最小限の4セクションだけで、毎回の反復説明がなくなります。公式推奨の200行以内を意識しつつ、具体的で検証可能なルールを育てていくのが基本です。
メモリ3階層は「使い込むほど賢くなる仕組み」です。第1層（CLAUDE.md）で不変のルールを、第2層（MEMORY.md / Auto Memory）でセッション横断の学びを、第3層（decisions.md等）で意思決定の理由を蓄積することで、Claude Codeは「毎回初対面のエンジニア」から「プロジェクトを熟知したチームメンバー」に変わります。3階層にする理由は、情報の寿命を揃え、棚卸しのコストを下げるためです。
ただし、メモリは放置すると腐ります。日付を記録し、定期的に棚卸しし、矛盾を検出する仕組みを入れること。pain_countのような昇格メカニズムを意識し、「繰り返し発生したものだけをルール化する」姿勢を持つこと。この運用コストを払えるかどうかが、CLAUDE.mdを「書いて終わり」にするか「育てていく」かの分岐点です。
まずは今日、プロジェクトルートにCLAUDE.mdを1つ作るところから始めてみてください。あるいは /init を叩くだけでも構いません。最初の1行が、数ヶ月後の自分を助けます。