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

先に結論

Claude Codeへ長期的な指示を残す場合、すべてをCLAUDE.mdへ詰め込むより、常に必要な短い規約、作業中のメモ、検索して参照する詳細文書を分けた方が安定します。まず `/memory` などで実際に読み込まれるファイルを確認し、CLAUDE.mdには優先順位の高い命令だけを置きます。詳細設計や履歴はMarkdownへ分離し、更新責任と検索語を明示してください。

30秒要約

**確認日:** 2026年8月6日

• CLAUDE.mdは常時必要な短い指示、詳細文書は必要時検索という分担が基本です。
• 個人用のCLAUDE.local.mdと共有ルールを混ぜず、リポジトリへ含める範囲を決めます。
• 自動メモリやMEMORY.mdは便利ですが、事実の正本として無条件に扱いません。
• 月次またはリリース単位で重複、矛盾、古いパス、廃止コマンドを点検します。

何が起きたか

Claude Codeはプロジェクトやユーザー単位のメモリファイルを読み込み、セッションをまたいで開発規約や作業上の知識を利用できます。現行ページは、CLAUDE.md、CLAUDE.local.md、`.claude/rules/`、自動メモリ、検索対象のMarkdownを役割別に配置する設計を扱っています。課題は、記憶量を増やすほど賢くなるわけではなく、矛盾や古い指示が優先されると開発を誤らせる点です。

今回の判断で重要なのは、出来事が報じられた日、対象となった製品・制度・運用、そして2026年8月6日時点の状態を一つの文に混ぜないことです。発表時点で正しかった条件が、現在も同じとは限りません。この記事では原典で示された出来事を起点にしながら、変更されやすい仕様、料金、募集状況、提供範囲は公式ページで再確認する前提にしています。

確定情報と観測を分ける

原典記事の体験談や担当者コメントは、導入判断に役立つ観測です。一方で、すべての環境へ再現する保証、将来の継続提供、独立した性能評価を意味しません。公式文書に書かれた仕様も、対象版や適用条件を外すと誤読につながります。

この対象で押さえる3つのポイント

正本とAI向け要約を分ける

API仕様、DBスキーマ、法的ルールなどは既存の正式文書を正本にし、CLAUDE.mdには参照先と守るべき要点だけを書きます。AI向け要約が正本を上書きしない構造にします。

優先順位を文章構造で示す

禁止事項、必須コマンド、テスト条件、コードスタイルを同じ密度で並べると重要度が見えません。「絶対に守る」「通常の既定」「必要時参照」に分け、矛盾時の優先先を明記します。

検索できる名前と更新日を持たせる

長いMarkdownを分割する場合、曖昧な `notes2.md` ではなく、対象、判断、更新日が分かる名前にします。索引から参照でき、古い文書には廃止理由と代替先を残します。

影響と読者の判断

長期記憶設計が整うと、毎回同じ説明を繰り返す量が減り、新しいセッションでもテストや命名規約を再現しやすくなります。ただし、記憶が増えるほどレビュー対象も増えます。導入判断は、チーム共有が必要か、正本がどこにあるか、誰が更新するか、誤った記憶を削除できるかで行います。

AI関連の更新を横断して確認する場合は、[AIニュース話題度レーダー](/ainews/)へ戻ると、単発の出来事を他の製品更新や導入事例と並べて確認できます。個別記事は結論を固定するものではなく、公式情報を再確認するための入口として利用してください。

Claude APIの長い固定文を繰り返す場合は、[prompt cacheが効かないときの確認順](/ainews/article/claude-prompt-cache-not-working/)で、API側のキャッシュ判定も確認できます。

確認手順1: 現在読み込まれる記憶を棚卸しする

1. `/memory` など現行版の確認手段で、読み込み対象を列挙します。 2. 各ファイルを必須規約、個人設定、詳細資料、一時メモに分類します。 3. 重複する命令と矛盾する命令を表にします。 4. 廃止されたコマンド、パス、モデル名、担当者を検索します。 5. CLAUDE.mdを最優先の短い規約へ整理します。 6. 同じ代表タスクを新規セッションで実行し、守られるか確認します。

この確認では、一度に複数の条件を変えないことが重要です。変更前の状態を保存し、1項目だけ変えて同じ入力を再実行します。結果が改善しても、変更した条件との因果関係が確認できない場合は「解決」と断定せず、「再現待ち」として扱います。

確認手順2: 検索型の詳細文書へ分離する

1. 詳細設計をテーマ別Markdownへ分割します。 2. 各文書の先頭に目的、対象、更新日、正本へのリンクを書きます。 3. CLAUDE.mdには「どの状況で何を読むか」を短く記載します。 4. 検索に使う固有語、ファイル名、コンポーネント名を揃えます。 5. 古い文書を削除せず廃止フォルダへ移す場合、代替先を明記します。 6. 月次レビューで参照されない文書と誤った自動記憶を整理します。

本番環境へ反映する前に、テスト用のデータ、リポジトリ、アカウント、テナントで同じ手順を再現してください。外部サービスへ送信される情報、保存されるログ、利用規約、料金発生条件を確認できない場合は、機密性の低い最小データに限定します。

復旧・導入で詰まったときの切り分け

古い記憶が誤動作を引き起こした場合、会話で訂正するだけでなく、読み込まれているファイルを特定して修正します。変更前の内容をGitで残し、新規セッションで再検証します。自動メモリの内容を正本へコピーする際は、人間が事実と期限を確認してください。

切り分けの基本は、対象そのものの問題、ローカル環境の問題、アカウント・権限の問題、外部サービス側の一時的な問題を分離することです。公式ステータス、リリースノート、既知の問題を確認した後、最小構成で再現し、最後に既存環境へ戻します。削除や再インストールを最初に行うと証拠と設定を失うため、ログと設定の退避を先に行ってください。

検証結果を残すときの最小記録

再現できない成功例や、条件が分からない失敗例は、後から判断材料になりません。少なくとも次の項目を残してください。

スクリーンショットだけでなく、可能ならテキストのログも保存します。ただしAPIキー、トークン、個人情報、顧客データ、非公開コードは記録へ貼り付けず、伏字または安全な識別子へ置き換えてください。

更新履歴

• 2026-08-06: 現行公開ページの主題を保持し、原典・公式情報の確認経路、判断表、確認手順、復旧時の注意点を追加しました。

参考リンク

• [Claude Code Documentation](https://docs.anthropic.com/en/docs/claude-code) — Claude Codeの公式文書
• [Claude Code Memory](https://docs.anthropic.com/en/docs/claude-code/memory) — メモリ機能を確認する公式文書