Claude Codeの長期記憶設計：CLAUDE.md・Markdown・検索で破綻を防ぐ

先に結論

Claude Codeを長期プロジェクトで使うときは、すべての情報をCLAUDE.mdへ集約しないことが重要です。

役割は、次のように分けます。

CLAUDE.mdは、Claude Codeへ永続的な指示を与える公式の仕組みです。ただし、プロジェクト内のすべての仕様、会議記録、過去の判断を無制限に保存する万能な記憶装置ではありません。

Anthropic公式ドキュメントでも、CLAUDE.mdはコンテキストとして扱われ、強制設定ではないと説明されています。内容が長すぎる、矛盾している、古いまま残っている場合は、作業を誤誘導する可能性があります。

長期運用では、次の原則を守ります。

1. CLAUDE.mdには、毎回参照してほしい短い規約だけを書く 2. 詳細情報は用途別のMarkdownへ分離する 3. 現行情報と廃止情報を明確に分ける 4. 関連文書をリンクでつなぐ 5. Gitや検索で、変更理由まで追える状態を保つ

Claude Codeに「覚えさせる」のではなく、人とClaude Codeが同じ記録を確認できる状態を作ることが目的です。

基本情報

Anthropic公式ドキュメントでは、Claude Codeの記憶に関する仕組みとして、主にCLAUDE.mdファイルと自動メモリが案内されています。

CLAUDE.mdは、利用者が記述する継続的な指示です。自動メモリは、Claude Codeが作業中に得た学習内容を記録する仕組みです。

ただし、自動メモリを含めても、プロジェクトの全情報が完全かつ恒久的に保持されるとは限りません。仕様、契約、セキュリティ要件、重要な意思決定は、人が管理する正式な文書へ残す必要があります。

CLAUDE.mdに置く情報

CLAUDE.mdには、Claude Codeが日常的な作業で繰り返し参照する、短く安定した情報を置きます。

公式ドキュメントでは、次のような内容が例として示されています。

• プロジェクトのアーキテクチャ
• コーディング規約
• よく使う開発手順
• ビルド、テスト、Lintのコマンド
• 命名規則
• プロジェクト固有の重要なパターン

CLAUDE.mdに置く情報：具体的に書く

Anthropicは、曖昧な指示より具体的な指示を推奨しています。

CLAUDE.mdに置く情報：インポートを使って分離する

公式ドキュメントでは、CLAUDE.mdから@path/to/import形式で別ファイルを参照できます。

例:

/memoryコマンドを使うと、読み込まれているメモリファイルを確認できます。導入後は、想定したファイルが実際に対象になっているか確認してください。

- プロジェクト概要は @README.md を参照
- Git運用は @docs/development/git-workflow.md を参照
- API規約は @docs/development/api-rules.md を参照

Markdownに残す情報

詳細な情報は、用途別のMarkdownへ分離します。

おすすめの最小構成は次のとおりです。

.
├── CLAUDE.md
├── README.md
└── docs/
    ├── specs/
    ├── decisions/
    ├── runbooks/
    ├── development/
    └── archive/

Markdownに残す情報：仕様書

docs/specs/には、現在の実装が満たすべき仕様を置きます。

Markdownに残す情報：意思決定記録

docs/decisions/には、設計上の重要な判断を残します。

Architecture Decision Recordのように、1件の判断を1ファイルへ分けると検索しやすくなります。

docs/decisions/
├── 0001-use-postgresql.md
├── 0002-use-jwt-for-api-auth.md
└── 0003-separate-admin-frontend.md

Markdownに残す情報：作業手順

docs/runbooks/には、人が繰り返し実行する運用手順を置きます。

例:

• 本番リリース
• ロールバック
• データ移行
• 障害調査
• 秘密情報のローテーション
• バックアップ復元

Markdownに残す情報：開発手順

docs/development/には、開発環境の構築、ブランチ運用、レビュー基準、テスト方針などを置きます。

CLAUDE.mdには要点とリンクだけを置き、詳細な手順はこちらへ集約します。

検索できる状態を保つ方法

Markdownを増やすだけでは、必要な情報を発見できません。

検索できる状態を保つ方法：ファイル名を具体的にする

次のような名前は避けます。

内容が分かる名前にします。

memo.md
new-spec.md
final.md
final-v2.md
discussion.md

billing-refund-policy.md
api-authentication.md
production-release.md
0004-replace-redis-with-valkey.md

検索できる状態を保つ方法：更新日と状態を書く

文書の冒頭に、状態と更新日を記載します。

状態には、例えば次の値を使えます。

- Status: active
- Last updated: 2026-07-14
- Owner: Platform team
- Replaces: `docs/archive/legacy-deployment.md`

• draft
• active
• deprecated
• superseded
• archived

検索できる状態を保つ方法：廃止情報を削除せず明示する

古い文書を残す場合は、冒頭で廃止済みと分かるようにします。

古い内容をGit履歴だけに残せる場合は、リポジトリから削除する方法もあります。

重要なのは、通常の検索結果に、現行文書と同じ見え方で古い文書が出続けないことです。

> This document is deprecated.
> Use `docs/runbooks/production-release.md` instead.
> Deprecated on: 2026-06-30

検索できる状態を保つ方法：相互リンクを付ける

仕様書、意思決定記録、実装、Issueをつなぎます。

Claude Codeへ調査を依頼するときも、関連情報をたどりやすくなります。

## 関連文書

- Decision: `docs/decisions/0002-use-jwt-for-api-auth.md`
- Runbook: `docs/runbooks/rotate-signing-key.md`
- Source: `apps/api/src/auth/`
- Issue: `#184`

検索できる状態を保つ方法：検索方法を決める

小規模なリポジトリでは、通常のファイル検索とGit検索で十分です。

例:

検索機能を導入しても、古い情報の状態管理がなければ、誤った文書を見つけやすくなるだけです。検索精度より先に、現行、廃止、下書きを区別します。

rg "Status: active" docs/
rg "Superseded by" docs/decisions/
git log -S "JWT" -- docs/
git blame docs/specs/authentication.md

古い文脈で破綻する典型例：CLAUDE.mdに旧コマンドが残る

パッケージマネージャーを変更したのに、CLAUDE.mdへ以前のコマンドが残っている例です。

実際にはpnpm install --frozen-lockfileへ移行済みでも、Claude Codeが古い指示を参照する可能性があります。

- Install dependencies with `npm install`

古い文脈で破綻する典型例：新旧の仕様書が並んでいる

payment-spec.mdとpayment-spec-new.mdが両方残り、どちらが現行か分からない状態です。

Claude Codeに「決済仕様を確認して」と依頼しても、古い文書を根拠にする可能性があります。

古い文脈で破綻する典型例：決定だけが残り、理由がない

「Redisを使わない」とだけ記録され、理由が残っていない例です。

意思決定記録には、背景、採用理由、代替案、影響を残します。

古い文脈で破綻する典型例：会話だけで仕様が決まる

Claude Codeとの会話で設計を決めても、正式な文書へ反映しなければ、次のセッションや別の担当者が判断を再現できません。

古い文脈で破綻する典型例：自動メモリを正式記録として扱う

Claude Codeの自動メモリは便利ですが、人が管理する正式な仕様書の代わりにはなりません。

自動メモリの内容が、現在の仕様と一致していることを保証する運用は別途必要です。重要な指示はCLAUDE.mdまたは正式なMarkdownへ明示し、Gitでレビューできる状態にします。

古い文脈で破綻する典型例：秘密情報を記録する

CLAUDE.mdやMarkdownへ、APIキー、パスワード、個人情報、本番環境の認証情報を書かないでください。

代わりに、秘密情報の参照方法だけを記載します。

- Local secrets are loaded from `.env.local`.
- Do not commit `.env.local`.
- Production secrets are managed in the deployment platform.

導入時の最小構成

最初から複雑な検索基盤を作る必要はありません。

次の構成から始められます。

.
├── CLAUDE.md
├── README.md
└── docs/
    ├── specs/
    │   └── overview.md
    ├── decisions/
    │   └── 0001-initial-architecture.md
    ├── runbooks/
    │   └── release.md
    └── development/
        └── local-setup.md

導入時の最小構成：CLAUDE.md

次の項目だけを入れます。

• リポジトリの目的
• 主要ディレクトリ
• ビルド、テスト、Lintコマンド
• 重要な禁止事項
• 文書の保存場所
• 参照すべき主要Markdownへのリンク

導入時の最小構成：仕様書

まずはdocs/specs/overview.mdへ、システム全体の目的、主要機能、対象外を記載します。

導入時の最小構成：意思決定記録

重要な技術選定を行うたびに、1ファイル追加します。

導入時の最小構成：作業手順

リリースやデータ移行など、失敗時の影響が大きい作業から文書化します。

導入時の最小構成：定期確認

月1回、リリース前、主要な設計変更時など、文書を確認するタイミングを決めます。

確認項目は次のとおりです。

長期記憶設計の目的は、AIに大量の情報を保持させることではありません。

現在の規約、正式な仕様、過去の判断、作業手順を分離し、人とClaude Codeが必要なときに確認できる状態を維持することです。

• CLAUDE.mdのコマンドが現在も有効か
• 廃止済みの規約が残っていないか
• 仕様書の状態と更新日が正しいか
• 新しい意思決定が記録されているか
• 旧文書に廃止表示があるか
• リンク切れがないか
• 秘密情報が含まれていないか