Claude Code の Auto Memory を有効にして3ヶ月。3〜5人のチームで複数の Web アプリケーションを開発する環境で、「勝手に賢くなってくれる」と期待した結果、CI が不安定になり、古い情報に引きずられ、チームメンバーと設定が衝突した。この記事では、Auto Memory を運用して初めて見えた5つの罠と、それを踏まえた設計原則を共有する。

Auto Memory の責務を正しく理解する

まず前提を揃えよう。Auto Memory と CLAUDE.md はまったく別の目的を持つ仕組みだ。

項目	CLAUDE.md	Auto Memory
誰が書くか	人間（開発者）	Claude（AI）
内容	プロジェクトのルール・指示	作業中の発見・パターン
ライフサイクル	意図的に更新	セッションごとに自動蓄積
共有範囲	git 管理でチーム共有可	マシンローカル（共有不可）
ロード方法	毎セッション全文ロード	MEMORY.md の先頭200行のみ
典型的な内容	「テストは pytest を使え」	「このプロジェクトでは pnpm を使っている」

よくある誤解は「Auto Memory を有効にしておけば CLAUDE.md は不要」というもの。逆だ。CLAUDE.md で明示的に指示すべきことを Auto Memory に頼ると、記録されるかどうかが Claude の判断に委ねられる。「pnpm を使え」というルールは CLAUDE.md に書くべきで、Auto Memory に書かれるのは「このプロジェクトでは pnpm が使われていることを発見した」というメモに過ぎない。

何が記録されて、何が記録されないか

Auto Memory が「価値がある」と判断した情報だけが記録される。具体的には以下のようなパターンだ。

記録されやすいもの:

ビルドコマンドの発見（pnpm run buildを実行して成功）- デバッグで解決したエラーパターン
ユーザーから明示的に「覚えておいて」と言われた内容
プロジェクト構造の特徴（モノレポの構成など）

記録されにくいもの:

一度しか出なかった一時的なエラー
会話の中で流れた雑談的なやり取り
Claude が「一般的すぎる」と判断した情報

問題は、何が記録されたかを開発者が能動的に確認しない限り分からない点だ。「覚えてくれているはず」という暗黙の期待が、後述する罠の温床になる。

運用で踏んだ5つの罠

責務の違いを理解した上で、実際に運用すると何が起きるのか。3ヶ月の運用で遭遇した5つの罠を具体的に示す。

罠1：200行制限に気づかず重要な情報が消えた

Auto Memory の MEMORY.md はセッション開始時に先頭200行だけがシステムプロンプトに注入される。201行目以降は存在していても読み込まれない。

数ヶ月運用していると、Claude は新しい発見を MEMORY.md の末尾に追記し続ける。やがて200行を超え、初期に記録した重要な情報（ビルド手順、主要なアーキテクチャの特徴）が200行目以降に押し出される。

# MEMORY.md（200行超過した状態）
## プロジェクト概要
...（初期に記録した重要情報）...
...

対処法: Claude は本来、MEMORY.md を「索引」として使い、詳細をトピックファイルに分割するよう設計されている。しかし実際には分割せず追記し続けるケースが多い。定期的に ~/.claude/projects/<project>/memory/を確認し、手動でトピックファイルに整理する必要がある。

# 理想的なディレクトリ構造
~/.claude/projects/<project>/memory/
├── MEMORY.md # 索引のみ（50行以内に収める）
...

罠2：CI/CD でデフォルト有効のまま不安定な挙動

ローカル環境の問題を見たところで、次は CI/CD 環境での問題だ。Auto Memory はデフォルトで有効である。ローカル開発では便利だが、CI/CD 環境ではこれが問題を引き起こす。

CI ランナーで Claude Code を使う場合、ランナーのホームディレクトリに Auto Memory が蓄積される。永続的なランナー（self-hosted runner など）では、以前のビルドで記録された情報が次のビルドに影響を与え、再現性のないビルド結果を生む。

# GitHub Actions の例: CI 環境では必ず無効化する
env:
CLAUDE_CODE_DISABLE_AUTO_MEMORY: "1"

これは環境変数による無効化で、settings.json

の autoMemoryEnabled

や /memory

コマンドのトグルより優先度が高い。CI 環境ではこの環境変数を必ず設定すること。

罠3：CLAUDE.md と Auto Memory の責務混同

最も厄介な罠がこれだ。CLAUDE.md に「テストは必ず書くこと」と指示しつつ、Auto Memory にも「このプロジェクトではテストファーストで開発する」と記録されている状態。表面上は整合しているように見えるが、両者の内容が微妙に矛盾し始めたときに Claude はどちらを優先するか予測できない。

実際に遭遇したケースを示す。

CLAUDE.md（人間が書いた指示）

テストフレームワークは Jest を使用すること。

MEMORY.md（Claude が自動記録した内容）

...

プロジェクトが途中で Jest から Vitest に移行した場合、CLAUDE.md の更新を忘れるとこうなる。Claude はどちらを信じるか？答えは不定だ。セッションによって Jest でテストを書いたり Vitest で書いたりする。

設計原則: CLAUDE.md に書くべきことと Auto Memory に任せることの境界を明確にする（後述の設計原則セクションで詳しく扱う）。

罠 4：リファクタリング後に古い情報が残留する

罠 3 は「設定の矛盾」だったが、罠 4 は「情報の陳腐化」だ。大規模なリファクタリングを行った後、Auto Memory にはリファクタリング前の情報が残り続ける。ディレクトリ構成の変更、API エンドポイントの改名、パッケージマネージャの移行——こうした変更は CLAUDE.md を手動で更新すれば反映されるが、Auto Memory は自動更新されない。

# MEMORY.md に残った古い情報の例
- src/utils/helpers.ts に共通ユーティリティが集約されている
- API のベース URL は /api/v1/ を使用
...

リファクタリング後、helpers.ts は分割され、API は v2 に移行し、ORM は Prisma に変わっている。しかし Auto Memory はそれを知らない。Claude は古い情報に基づいてコードを書き、存在しないファイルを参照したり、廃止された API を呼んだりする。

対処法: 大規模なリファクタリングの後は、MEMORY.md を手動でレビューし、陳腐化した情報を削除または更新する。これは月次メンテナンスとは別に、リファクタリング直後に行うべき作業だ。

# リファクタリング後の MEMORY.md クリーンアップ
# <project> は実際のディレクトリ名に置き換える
# （ls ~/.claude/projects/ で確認可能。パスがエンコードされた文字列になる）
...

罠 5：チーム開発でのメモリ汚染

ここまでの罠は個人開発でも発生するが、罠 5 はチーム開発で特有の問題だ。Auto Memory はマシンローカルに保存される。つまりチームメンバーごとに異なる MEMORY.md が蓄積される。これ自体は設計通りだが、問題はメンバーごとに Claude の振る舞いが異なることだ。

開発者 A の Auto Memory には「このプロジェクトではシングルクォートを使う」と記録され、開発者 B には「ダブルクォートで統一されている」と記録されている場合、同じプロジェクトで Claude が生成するコードのスタイルがメンバーによって異なる。

これはコードレビューで初めて発覚し、「なぜ Claude がスタイルを変えたのか」の原因特定に時間がかかる。

対処法: チーム全体で統一すべきルールは Auto Memory に頼らず、CLAUDE.md に明示的に書いて git 管理する。Auto Memory はあくまで個人の作業メモとして割り切る。また、CLAUDE.md の更新責任を明確にしておくことも重要だ。テックリードや機能オーナーが四半期ごとにレビューする運用を推奨する。新メンバーのオンボーディングチェックリストにも「Auto Memory の運用方針を確認」を含めておくとよい。

# CLAUDE.md に書くべき内容（チーム共通ルール）
## コードスタイル
- クォートはシングルクォートを使用（Prettier で強制）
...

設計原則：CLAUDE.md と Auto Memory の責務分離

5 つの罠を踏まえて、CLAUDE.md と Auto Memory の責務を分離する判断フローを示す。

具体的な分類基準を表にまとめる。

情報の種類	置き場所	理由
コーディングスタイル	CLAUDE.md	チーム統一が必要
...
注意: CLAUDE.md に書いた内容と Auto Memory の内容が矛盾した場合、Claude がどちらを優先するかは保証されない。CLAUDE.md に書いたルールが Auto Memory の記録に上書きされるリスクがある。CLAUDE.md を更新したら、Auto Memory に矛盾する記録がないか /memory コマンドで確認することを習慣にすべきだ。

月次メンテナンスのプレイブック

Auto Memory は「設定して放置」で使える仕組みではない。月に 1 回、以下の手順でメンテナンスする。筆者の経験では、1 プロジェクトあたり 15〜30 分程度で完了する。

ステップ 1：現在の状態を確認する

# MEMORY.md の行数を確認（200 行を超えていないか）
wc -l ~/.claude/projects/*/memory/MEMORY.md
# トピックファイルの一覧（ディレクトリ名は ls ~/.claude/projects/ で確認）
...

ステップ 2：陳腐化した情報を削除する

MEMORY.md を開き、以下に該当する記録を削除する。

削除べき情報	具体例
存在しないファイルへの言及	「src/utils/helpers.ts に〜」（ファイル削除済み）
...

ステップ 3：200 行制限への対処

MEMORY.md が 100 行を超えたら、トピックファイルへの分割を検討する。

# MEMORY.md（索引として 50 行以内に収める）
## プロジェクト概要
- モノレポ構成（apps/ + packages/）
...

Claude はトピックファイルを必要に応じてオンデマンドで読み込む。MEMORY.md に「詳細は build-commands.md を参照」と書いておけば、ビルドに関する質問を受けたときに Claude が判断してそのファイルを参照する場合がある。

ステップ 4：メンテナンスログを残す

メンテナンスを行ったことを MEMORY.md 自体に記録しておくと、次回の判断材料になる。

## メンテナンスログ
- 2026-03-01: 200 行超過のため分割実施。architecture.md を新規作成
- 2026-02-01: リファクタリング後の古い情報を削除（5 件）

メンテナンス忘れ防止策

人間の記憶に頼るメンテナンスは半年で破綻する。以下のいずれかを導入しておくとよい。

カレンダーリマインダー: 毎月 1 日に「Auto Memory メンテナンス」を設定 -
CI での行数監視:wc -l

を定期ジョブで回し、200 行を超えたら Slack 通知 -
シェルエイリアス:alias mem-check='wc -l ~/.claude/projects/*/memory/MEMORY.md'

を.zshrc に追加し、目視確認を習慣化

# CI での行数監視スクリプト例
LINE_COUNT=$(wc -l < ~/.claude/projects/*/memory/MEMORY.md 2>/dev/null || echo 0)
if [ "$LINE_COUNT" -gt 150 ]; then
...

無効化すべきケースと判断基準

Auto Memory はデフォルト有効だが、無効化すべきケースがある。判断を誤ると、前述の罠に直接つながる。

| ケース | 推奨 | 理由 |
|---|---|
| CI/CD パイプライン | 無効化 |
再現性を確保するため |
| 高機密プロジェクト | 無効化 |
MEMORY.md の内容がシステムプロンプトに注入される |
| 信頼できないリポジトリの調査 | 無効化 |
悪意あるコードの情報が記録されるリスク |
| CLAUDE.md を徹底整備済み | 検討 |
Auto Memory が矛盾する情報を記録するリスク |
| 短期間のスポット作業 | 検討 |
メンテナンスコストに見合わない |
| 長期プロジェクト（個人開発） | 有効化 |
コンテキストの蓄積が効率化に寄与 |
| ドキュメント未整備のレガシーコード | 有効化 |
Claude が構造を学習してくれる |

無効化の方法は 3 つある。優先度が高い順に以下の通り。

# 方法 1: 環境変数（最優先のキルスイッチ）
export CLAUDE_CODE_DISABLE_AUTO_MEMORY=1

// 方法 2: settings.json
// ユーザー全体：~/.claude/settings.json
// プロジェクト単位：.claude/settings.json（git 管理対象に注意）
...

# 方法 3: /memory コマンド（セッション内トグル）
# Claude Code 内で /memory を実行し、トグルする

トレードオフと限界

ここまで運用ノウハウを紹介してきたが、Auto Memory には構造的な限界がある。これを理解した上で使うかどうかを判断すべきだ。

「メモリは学習ではない」

Auto Memory に対する最大の誤解は、「Claude が学習して賢くなる」と思い込むことだ。実際には、Claude のモデルの重みは一切更新されていない。セッション開始時に MEMORY.md をシステムプロンプトに注入しているだけであり、ファイルを読んでいるに過ぎない。

この区別が重要な理由は、Auto Memory の信頼性に直結するからだ。

記録の正確性は保証されない: Claude が「発見した」と記録した情報が、実は一時的な回避策だったり、特定の状況下でしか成立しない事実だったりする -
記録の網羅性は保証されない: 重要だと人間が思う情報でも、Claude が「記録する価値がない」と判断すれば記録されない -
記録の鮮度は保証されない: 一度記録された情報は、プロジェクトが変化しても自動更新されない

セキュリティ上の考慮

MEMORY.md の内容はシステムプロンプトに注入され、Anthropic のサーバーに送信される。Auto Memory に機密情報（API キー、内部 URL、顧客データに関する記述）が記録された場合、それらが外部に送信される。

Claude Code が .env ファイルを自動ロードするという報告がある。この自動ロードされた情報が Auto Memory に記録されるリスクは否定できない。高機密プロジェクトでは Auto Memory を無効化するか、定期的に MEMORY.md の内容を監査すべきだ。

コンテキストウィンドウの圧迫

MEMORY.md 의 첫 200 행은 각 세션의 시스템 프롬프트에 추가됩니다. CLAUDE.md + .claude/rules/

Auto Memory 의 총합이 커지면, 실제 작업에 사용할 수 있는 컨텍스트 윈도우가 좁아집니다.

특히 대규모 프로젝트에서 CLAUDE.md 가 긴 경우, Auto Memory 의 200 행이 추가로 컨텍스트를 압박합니다. MEMORY.md 를 간결하게 유지하는 것은 단순한 정리정돈이 아니라 컨텍스트 효율의 최적화입니다.

まとめ

Auto Memory 는「설정하고 방치」하는 것이 아니라「설계하고 운영」하는 시스템입니다.

지금 바로 해야 할 일:

CI/CD 환경에. 영속 라운더를 사용하는 경우 특히 시급합니다. CLAUDE_CODE_DISABLE_AUTO_MEMORY=1

을 추가해야 합니다 - MEMORY.md 의 행 수를 확인하세요. wc -l ~/.claude/projects/*/memory/MEMORY.md

으로 200 행을 초과하지 않는지 확인하고 - CLAUDE.md 와 Auto Memory 의 내용을 일치시키세요. 모순이 없는지 확인하고, 규칙은 CLAUDE.md 에 통합합니다.

월간 유지보수를 습관화하세요:

낡은 정보의 삭제
200 행 제한에 대한 대응 (토픽 파일로의 분할)
리팩토링 후 재고
팀에서 CLAUDE.md 의 업데이트를 공유

Auto Memory 는 편리한 시스템이지만,「자동」이라는 이름에 속지 마세요. 사람이 유지보수함으로써初めて, 세션을 넘어선 생산성 향상이 실현됩니다.

참고 링크

How Claude remembers your project — Claude Code 공식 문서
Claude Code Auto Memory: How Your AI Learns Your Project — ClaudeFast
Automatic Memory Is Not Learning — Brent W. Peterson
You (probably) don't understand Claude Code memory — Jose Parreño Garcia
Claude Code's Memory Evolution: Auto Memory & PreCompact Hooks Explained — Yuanchang's Blog

Claude Code Auto Memory 運用で踏んだ5つの罠と設計原則

요약

핵심 포인트