claude-migrate-memory-to-doc

Claude Code のメモリをツール非依存のドキュメントに移行する

このスキルが必要な理由

Claude Code の個人用メモリは ~/.claude/projects/<project-slug>/memory/ に保存されます。Claude Code 専用であり、リポジトリと一緒にバージョン管理されず、ほかのツールからは見えません。同じディレクトリで Codex、Cursor、その他の AI CLI を使い始めても、それらのツールは「ユーザーがどんな人か／どのように協働するか」を読み取れません。ユーザープロフィールや協働時の設定は、本来どの AI アシスタントも最初に読むべき情報なのに、です。

このスキルでは、複数ツールで共有できる情報をメモリからツール非依存の場所に移し、メモリは最小限の引き継ぎキャッシュとして残します。解決するのは「メモリが散らかっている」という問題ではなく、ツールへのロックインです。

このスキルはインラインで実行します（context: fork は使いません）。並列レビューのサブエージェントを起動し、Bash 経由で codex を実行するためです。フォークされたサブエージェントでは、どちらも実行できません。

最初に確認：どちらが目的ですか？

目的	ユーザーの希望	手順
A — ツールへのロックインを解消する	ほかの AI ツールでも同じプロフィールと設定を読み込めるようにし、メモリは最小限の引き継ぎキャッシュとして残す	以下のワークフローの全フェーズ
B — 自動メモリを廃止する	あるプロジェクトで自動メモリの利用をやめ、そこに保存されていた情報をすべてドキュメントで管理する	references/retire_auto_memory.md。以下のワークフローからは、フェーズ 1 のスコープ表とフェーズ 6 のアーカイブ規則を使い、Codex にも結果を読み込ませたい場合に限り、フェーズ 2 と 5 も実施します

目的 B には「メモリに残す」分類はありません。引き継ぎ状態、外部への参照、保留中の判断にはドキュメント上の保存先が必要です。メモリディレクトリは最終的に空になり、プロジェクトの切り替え設定をオフにして、制御プローブで無効化を確認します。依頼から目的が分からない場合は、質問してください。

核心となる考え方 — 何かに手を加える前に読んでください

難しいのはファイルの移動ではありません。次の点です。

プレーンテキストのポインターだけで参照できるファイルは、必要に応じて読み込まれるものであり、必ず読み込まれるとは限りません。これはどちらのツールでも同じです。

• Claude Code が参照ファイルを自動で事前読み込みするのは、@import 構文を使った場合だけです。プレーンテキストのポインター（「~/.claude/references/user/foo.md を参照」など）の場合は必要に応じた読み込みとなり、エージェントが自分で開く必要があります。
• Codex はさらに厳格です。CLAUDE.md 内に記載されたテキスト形式のパスを解析も追跡もしません。自動で挿入されるのは、~/.codex → git-root → cwd の階層に沿ったドキュメントファイル（AGENTS.md または設定済みのフォールバック）のみです。~/.claude/references/ にある、ほかの名前の参照ファイルが Codex に自動で読み込まれることはありません。

そのため、アーキテクチャは2 層に分ける必要があります。

層	配置場所	保証
確実に読み込まれる層 — 毎回のターンで必ず必要な少数の情報	CLAUDE.md 本文に直接記載する（どちらのツールも挿入する）	常に利用可能
必要に応じて読む詳細 — プロフィール全体、実体験から得た知見、例外的なケース	ポインターから参照する references/ ファイル	関連する場合に読み込まれる

最も重要な情報だけを参照ファイルに置き、ポインターを頼りにするのが、この移行を気づかれないまま失敗させる最大の原因です。重要な情報は本文に記載してください。

ツール非依存のアーキテクチャ

~/.claude/CLAUDE.md            global instructions — BOTH tools inject this.
                               Inline the hardest user facts here (a short "User context" section).
~/.claude/references/user/     SSOT for profile / preferences / methodology / personal affairs.
~/.claude/references/user-profile.md   hub: condensed core + index into the user/ files
~/.codex/AGENTS.md  ──symlink──▶  ~/.claude/CLAUDE.md
                               so Codex's GLOBAL layer injects the same file Claude Code reads.
~/.codex/config.toml           raise project_doc_max_bytes — Codex truncates docs at 32 KiB by default,
                               which silently drops the back half of a long CLAUDE.md.

スコープに関する注記：配線（~/.codex/ のシンボリックリンク、設定の編集、フェーズ 5 の検証）はCodex 固有で、Codex のみで検証済みです（2026-06）。~/.claude/references/user/ のコンテンツ層は、プロジェクトのドキュメントを自動で読み込むツールなら利用できますが、Cursor などでは独自の配線が必要です（Cursor が読み込むのは .cursor/rules またはプロジェクトルートの AGENTS.md であり、~/.codex/ ではありません）。ここでは実装も検証も行っていません。

ワークフロー

このチェックリストを作業メモにコピーし、項目を完了するたびにチェックしてください。

Memory → Tool-Agnostic Doc Migration:
- [ ] Phase 1: Diagnose & scope — classify every memory file by SCOPE
- [ ] Phase 2: Tool-agnostic migration — references/ + inline hardcore + symlink + config
- [ ] Phase 3: Multi-agent review — 4 parallel reviewers
- [ ] Phase 4: Fix everything review surfaced
- [ ] Phase 5: VERIFY BY RUNNING CODEX (not by reasoning)
- [ ] Phase 6: Memory cleanup — clean / thin / keep + soft-delete to backup

Phase 1 — 診断と範囲の特定

事前確認 — メモリディレクトリを見つけます。 Claude Code のメモリは ~/.claude/projects/<project-slug>/memory/ にあります。<project-slug> は作業ディレクトリのパスで、/ を - に置き換えたものです。ユーザーは複数のプロジェクトにまたがるメモリを持っている場合があります。ls ~/.claude/projects/*/memory/ で一覧表示し、ツール横断のユーザー情報を含むプロジェクトを選択（または統合）してください。

そのメモリディレクトリ内の全ファイルを一覧表示します。「整理されていないかどうか」ではなく、範囲で分類してください。詳細な判断表と、エージェントが非公開のコンテキストを判断できない場合についての注意事項は、references/diagnosis_and_scoping.md を参照してください。

要点は次のとおりです。

• チームのルール／標準／SOP → プロジェクトの CLAUDE.md または docs/（バージョン管理され、チームに共有されます）。
• ツール横断のユーザープロフィール／協業上の好み／方法論／個人的な事柄 → ~/.claude/references/user/（ツールに依存しません）。これが移行対象です。
• 一時的な引き継ぎスナップショット／外部システムへのポインター → メモリに残します。これはメモリ本来の用途です。移行しないでください。（目標 B では代わりに文書へ移します。references/retire_auto_memory.md §4 を参照してください。）

エントリを「どこにも記載されていない」と判断する前に、その情報を保持している可能性のある場所をすべて検索してください。グローバルおよびプロジェクトの指示ファイル、~/.claude/references/、すべてのスキルのソースリポジトリ（公開・非公開を問わず）、プロジェクトのドキュメントと引き継ぎ資料、フックやスクリプトのヘッダーが対象です。サブエージェントへのプロンプトには、これらのルートをすべて記載してください。エージェントは指示されたルートしか検索しません。検索コマンドが結果ゼロでも信頼する前に、存在がわかっている文字列で各検索コマンドを確認してください。

すべてを移行してはいけません。引き継ぎ状態を長期間保持する文書へ移しすぎるのも誤りです。ただし、ディレクトリ全体を確認してください。feedback_*.md だけでなく、プロジェクトの SOP や運用上の経験談が project_*.md や architecture_*.md ファイルに置かれていることもあり、リポジトリのドキュメントに含めるべきです。

この段階で、プライベートなコンテキスト／PII も確認してください。システムのユーザー名と実名、個人的な連絡先、その他の個人を特定できる情報を対応づけるメモリファイルは、プロジェクトに関係する場合でもプライベートなメモリに残してください。プロジェクトのドキュメントはバージョン管理され、共有される可能性があります。本人の特定につながる情報の対応づけは、薄い引き継ぎレイヤーに置くべきです。

Phase 2 — ツールに依存しない移行

まず CLAUDE.md のスナップショットを保存します（cp ~/.claude/CLAUDE.md ~/.claude/CLAUDE.md.bak）。これから編集するためです。~/.claude/CLAUDE.md が存在しない場合は作成してください（プロジェクトレベルのものしかないユーザーもいます）。

command -v codex の結果が空の場合（Codex がインストールされていない場合）、以下の手順 1 と 4（references/ と CLAUDE.md へのインライン記載）のみを行い、シンボリックリンク（2）、設定（3）、Phase 5 全体はスキップしてください。コンテンツの移行はそのまま行います。後で Codex を接続するにはシンボリックリンクと project_doc_max_bytes が必要であることをメモに残してください。

「移行対象」の各項目について、内容を ~/.claude/references/user/ に移します（テーマごとに少数のファイルへまとめ、ハブとして user-profile.md を作成します）。その後、次の 2 層アーキテクチャを設定します。

1. 最重要事項をインラインで記載します。~/.claude/CLAUDE.md の上部近く（Codex が読み込めるよう、先頭から約 32 KiB 以内）に # User context セクションを設け、必ず毎ターン適用される 3～6 個の事実を記載します（例：ユーザーへの呼びかけ方、譲れない好み、最も重要な本人情報）。それ以外はすべてポインターのままにします。
2. シンボリックリンク ~/.codex/AGENTS.md → ~/.claude/CLAUDE.md を作成します（~/.codex/AGENTS.md が存在しないか、空のプレースホルダーである場合のみ。実際の内容があるファイルは決して上書きしないでください）。
3. CLAUDE.md が 32 KiB を超える場合は、~/.codex/config.toml の project_doc_max_bytes を引き上げます。
4. プロジェクトにナレッジ保存ルールがある場合は更新し、「ユーザーの好み → memory」という記述が、新しい「ユーザープロフィール → ~/.claude/references/user/」という運用と矛盾しないようにします。

正確なディレクトリ構成、ハブ・アンド・スポークのパターン、ガバナンスルールの修正については、references/tool_agnostic_migration.md を参照してください。

フェーズ 3 — マルチエージェントレビュー

4 つのレビュー用サブエージェントを並行して起動します（1 つのメッセージで複数の Task 呼び出し）。それぞれが 1 つの観点を監査します。内容の完全性（事実が抜け落ちたり、変更されたりしていないか）、相互参照の破損（メモリを削除すると、どの [[links]] がリンク切れになるか）、ツールに依存しないリンクの整合性（シンボリックリンク／ポインターの連鎖は実際に解決できるか。Codex は本当にそれを読み取るか）、重複／乖離（リファレンスに CLAUDE.md のルールが重複していないか）。正確なプロンプトは references/review_and_verification.md にあります。

エージェントの指摘は判定ではなく仮説です。対応する前に（確率 × コスト × 実際に起こるか）に基づいて精査してください。

フェーズ 4 — 修正

レビューで明らかになった点に対処します。よくある実際の指摘（すべて実運用での事例）として、子ファイルの 1 つをインデックスに登録し忘れたハブファイル、リファレンスにしか残っていない重要な事実（本文に移動する）、削除予定のメモリを参照する存続ファイル内の [[links]]（新しいリファレンスに付け替える）、ガバナンステーブルの行は更新したものの、同じセクションの判断文が矛盾したまま、といったものがあります。

フェーズ 5 — CODEX を実行して検証（省略しない。ユーザーに委任しない）

「問題なさそう」や「後で自分で確認してください」に置き換えたくなるステップです。そうしないでください。**任意のディレクトリから --skip-git-repo-check を付けて codex を実行し、mtime ではなくセッション ID でセッションログを照合して、本文にインライン化した重要なセクションとファイル後半の文字列を grep してください。**インライン化したセクションのタイトルは # User context、# 用户上下文、またはユーザーが使用している任意のローカライズ表記の場合があります。ハードコードされた英語の見出しではなく、実際の見出し文字列を grep してください。検証に合格する実行では、その見出しとファイル後半の文字列の grep 件数がそれぞれ 1 になります（CLAUDE.md が 32 KiB を超える場合）。--skip-git-repo-check、セッション ID の抽出（ヘッダーにあり、末尾にはありません）、32 KiB の確認に加え、< 32 KiB と codex-not-installed のショートカット、および期待されるコンソール出力を含む、正確で実証済みのコマンドブロックは references/review_and_verification.md にあります。そのまま使用してください。ここで独自の派生版を作らないでください（それが 2 つのコピーに食い違いが生じる原因です）。

フェーズ 6 — メモリの整理

移行しなかったメモリファイルについて、次の3つのいずれかを実施します（判断の詳細は references/diagnosis_and_scoping.md を参照してください）。

• 整理する — 期限切れ（過去の日付の引き継ぎ）または古くなっている（保存せずに算出すべき派生カウント）もの → アーカイブします。
• 内容を絞る — 別の場所にあるSSOTを繰り返している引き継ぎ → 重複部分を削除し、参照先と変動する状態だけを残します（例：「インスタンスXはまだ課金中なので、停止する」）。
• 残す — 正当な引き継ぎ、またはすでに簡潔な参照情報 → そのままにします。（ゴールBでは対象外です。すべてアーカイブします。）

メモリインデックス（例：MEMORY.md）を更新し、移行した項目を削除して、移行先への参照を1つ追加します。

ファイルを移動する前に、メモリディレクトリ全体とプロジェクトのドキュメント／CLAUDE.mdをgrepし、アーカイブするファイルへの参照がないか確認してください。 存続するファイルや有効なドキュメントからアーカイブ済みファイルへのリンクが残っていると、参照切れになります。リンク先を新しいドキュメントの場所、またはプレーンテキストの参照情報に変更してください。メモリ内の相互参照だけがリスクではありません。プロジェクトのCLAUDE.mdや引き継ぎドキュメントに、メモリファイル名が記載されていることもよくあります。

完全削除ではなく、ソフト削除してください。 移行または整理したファイルは、日付付きのバックアップディレクトリに移動します。移動先はmemory/の外（例：~/.claude/projects/<slug>/.memory-archive-2026-07-06/のような隣接ディレクトリ）にし、プレースホルダーではなく実際の現在の日付を使用してください。アーカイブをmemory/内に置くと、現役のメモリとして読み込まれ、整理の目的が損なわれます。インデックスの参照先を、memory/外の新しいパスに更新してください。両方のツールが正常に動作することを数週間確認した後、バックアップをrmで削除できることをユーザーに伝えてください。

新しい知見が得られた移行の後は、このスキルを更新してください。 references/failure_cases.mdに記載されていない失敗パターンがあれば追記します。手順が不明確だった場合は、SKILL.mdのチェックリストを明確にしてください。そこで得た教訓を反映しないスキルは、同じ間違いを繰り返します。

やってはいけないこと（実際の実行中に失敗して学んだこと）

• 最初に「削除」に手を伸ばさないでください。 整理されていないメモリを削除したくなるものですが、順序が違います。まず移行／簡素化／維持に分類してください。「整理されていない」メモリの多くは、移行できる価値があるか、正当な引き継ぎ情報です。削除すると、その価値が失われます。
• reference + pointer ならツールに依存しないと思い込まないでください。 ポインターは、どちらのツールでも必要に応じて参照するものです。重要な事実は CLAUDE.md 本文に直接記載する必要があります。そうしないと、読み込まれないままになってしまいます。
• Codex がテキストのポインターをたどると思わないでください。 Codex が読むのは AGENTS.md／CLAUDE.md ファイルそのものであり、ファイル内に記されたパスではありません。公式ドキュメントと実際のセッションログで確認済みです。
• Codex のドキュメントが 32 KiB で切り詰められることを忘れないでください。 project_doc_max_bytes を引き上げない限り、長い CLAUDE.md は後半が Codex に読み込まれません。ユーザーは気づかないまま、何か月も CLAUDE.md の半分しか使えていなかった可能性があります。
• ガバナンステーブルの行を変更したのに、同じセクションの判断ロジックが矛盾したままにならないようにしてください。 事実を一つ編集したら、セクション全体を grep してください。
• メモリファイルを削除する前に、そのファイルへの [[cross-references]] がないか grep してください。 削除したファイルを参照するファイルが残ると、リンク切れになります。
• 内容がユーザー固有のコンテキストに依存する場合、削除するかどうかをエージェントにまとめて判断させないでください。 エージェントには「ユーザーが実際に何を重視するか」がわかりません。候補を提示し、ユーザー自身（または、十分なコンテキストを把握したあなた）が判断してください。
• ユーザーに確認作業をさせないでください。 codex を実行してログを grep する作業はエージェントが実行できます。検証のループは自分で担い、ユーザーに戻さないでください。
• 「シンボリックリンクが存在する」ことを Codex での検証とみなさないでください。 正しいシンボリックリンクは必要ですが、それだけでは不十分です。唯一の証拠は、インライン化した重要セクションがロールアウトログに含まれる、実際の codex exec セッションです。
• アーカイブを memory/ 内に置かないでください。 そこに置くと、ライブメモリとして引き続き読み込まれ、整理の意味がなくなります。memory/ の外にある隣接ディレクトリへ移動してください。
• 実名との対応表や PII をプロジェクトドキュメントに移行しないでください。 プロジェクトドキュメントはバージョン管理され、共有されます。メモリファイルに user3 → <a coworker's real name> のような対応表がある場合は、プライベートメモリに残してください（SSOT が別の場所にある場合は、ポインターだけに簡素化してください）。docs/ には移動しないでください。
• 差分を確認せずに、既存のドキュメントをメモリの重複内容で上書きしないでください。 多くのメモリファイルは、ドキュメントの一部だけを重複しています（例：architecture_v2_decision.md と docs/decisions/2026-02-21-v2-architecture.md）。移行するのは固有の詳細だけにし、既存のドキュメントを置き換えずに追記してください。
• メモリだけでなく、プロジェクトドキュメント内のリンクも付け替えてください。 CLAUDE.md や引き継ぎドキュメントでは、ベース名でメモリファイルを参照していることがよくあります。アーカイブする前に grep してください。
• どのルートを検索したのかわからないまま、サブエージェントの「ホームが見つからない」という報告を受け入れないでください。 プライベートなスキルリポジトリについて知らされていなかった 3 つの調査エージェントが、すでにドキュメント化されていた項目を 2 件、「移行が必要」として報告しました。
• プロジェクト 1 つのメモリを廃止するために、自動メモリをグローバルにオフにしないでください。 グローバルの設定を切り替えると、ほかのすべてのプロジェクトでメモリが読み込まれなくなります。プロジェクトの .claude/settings.local.json を使ってください。

失敗事例（実際に起きた問題の全容）

各「やってはいけないこと」の根拠と、実際に起きた問題については、references/failure_cases.md を参照してください。