Claude Code のメモリを設計する｜2層構造とGit管理で”教え直し”を根絶する実践ガイド

「このプロジェクトでは pnpm を使う、と先週も教えたのに——」。Claude Code を複数のプロジェクトや複数のデバイスで使っていると、この感覚は避けられません。Claude Code のメモリはデフォルトでプロジェクトごとに完全に分断されているため、あるプロジェクトで学習させたフィードバックは別プロジェクトに引き継がれません。デバイスを変えた瞬間、その学習はリセットされます。

この問題の解決策は「メモリをどこに置くか」ではなく「メモリをどう設計するか」です。本記事では、Claude Code のメモリを Global 層と Project 層の2層に分けてGitで管理する設計アーキテクチャを体系的に解説します。単なるセットアップ手順ではなく、「なぜ2層か」「どの知識をどの層に置くか」「description の書き方でパフォーマンスがどう変わるか」「メモリが腐敗するとどうなるか」という設計の根拠まで掘り下げます。

「教え直し」の根本原因：メモリの分断

Claude Code にフィードバックを与えたとき、そのフィードバックはどこに保存されるのでしょうか。

デフォルトでは ~/.claude/projects/<hash>/memory/ 配下に保存されます。<hash> はプロジェクトディレクトリのパスから生成されるため、プロジェクトが違えば別のハッシュになり、記憶が共有されません。

この問題はメモリの「物理的な分断」から来ています。分断を解消するには、メモリの保存場所を変えるのではなく、どの知識をどこに置くかを意識的に設計する必要があります。

Claude Code のメモリ構造：ファイル・読み込み・種別

設計を始める前に、Claude Code のメモリが内部でどう動いているかを理解しておきます。

ファイルの保存場所と読み込みの仕組み

Claude Code のメモリシステムは2つのファイルで構成されます。

この設計の重要な含意は、MEMORY.md のインデックス説明文がコンテキストの使用量を決めるということです。説明文が曖昧だとメモリが余分に読まれ、具体的だと必要なときだけ読まれます（詳細は後述）。

5種類のメモリ種別

個別メモリファイルの frontmatter には type フィールドで種別を指定します。種別は管理のためのラベルであり、Claude Code の動作を変えるわけではありませんが、どの情報をどの層（Global/Project）に置くかの判断基準になります。

fixes 種別の配置（Global か Project か）は最も判断が難しく、誤ると後で問題になります。これは「昇格ルール」で詳しく扱います。

2層設計の原則：Global と Project の役割分担

「教え直し」問題を解決する設計は、メモリを2つの層に分けることです。

なぜ1層（すべて Global）ではダメか

「すべてを Global に入れれば常に参照できて便利ではないか」と思うかもしれません。しかし全情報を Global に入れると3つの問題が生じます。

• ノイズの増加：Project 固有の情報（「このAPIはステージング環境でのみ動く」）が全プロジェクトのコンテキストを汚染する
• コンテキストの肥大化：MEMORY.md が大きくなるほど常時読み込みのオーバーヘッドが増え、Claude が全エントリを参照し続ける
• 情報の陳腐化：Project 固有の「マージフリーズ」「一時的な設定変更」が Global に入ると、プロジェクト終了後も残り続けて混乱の原因になる

なぜ3層以上にしないか

Global → Team → Project のような3層設計も考えられますが、実用上は2層が最適です。

• 3層以上になると「どの層に入れるか」の判断コストが高くなる
• Team 層の管理は複数人の同意が必要になり、運用が複雑になる
• Claude Code はファイルを読む際に層の概念を持っていないため、人間側の管理コストだけが増える
• ほとんどの知識は「全プロジェクト共通」か「このプロジェクト固有」かのどちらかに分類できる

チームで共有したい場合は、Global メモリのリポジトリをチームのプライベートリポジトリにして全員がクローンする方法が最もシンプルです。

description の書き方：読まれるメモリ・読まれないメモリ

2層設計で最も見落とされやすいのが MEMORY.md の説明文（description）の品質です。Claude Code はインデックスの説明を見て「このセッションで読む必要があるか」を判断します。説明が曖昧なら余計なメモリを読み込み、具体的なら必要なときだけ読まれます。

悪い description の例

## Feedback
- [feedback_misc.md] — Various feedback
- [fixes_env.md] — Environment fixes
- [reference_stuff.md] — Project references

これらの説明では Claude Code は「このセッションで必要かどうか」を判断できません。結果として常に読まれるか、逆に必要なときに読まれないという二択になります。

良い description の例

## Feedback
- [feedback_no_coauthor.md] — Co-Authored-By トレーラーを付けない（明示的に要求された場合のみ付ける）
- [feedback_no_comment_bloat.md] — 既存のコメントがない関数にコメントを追加しない。説明ではなく変更された箇所のみコメント
- [feedback_concise_response.md] — 応答の末尾に「以上が変更内容です」などの要約を付けない

## Fixes
- [fixes_eslint9_flat_config.md] — ESLint 9以降で .eslintrc.js が廃止・flat config（eslint.config.js）への移行方法
- [fixes_nextjs_app_router_params.md] — Next.js 15以降で params が Promise になった変更への対処
- [fixes_pnpm_workspace.md] — pnpm workspace でのパッケージ解決の問題と workaround

## User
- [user_profile.md] — スキルレベル・好む説明スタイル・使用ツールの前提知識

良い description の条件を整理します。

description は「未来の Claude Code への検索クエリ」だと考えてください。そのセッションで問題が起きたとき、Claude Code が description を見て「このファイルを読めば解決できる」と判断できる説明文が理想です。

昇格ルール：どの知識をいつ Global に上げるか

2層設計の運用で最も重要かつ難しい判断が「昇格」です。Project メモリの知識を Global に移すタイミングと基準を間違えると、Global が肥大化するか、本来共有すべき知識が埋もれます。

昇格すべき知識の判断基準

Global への昇格は「2つ以上のプロジェクトで同じ問題が再発したとき」を基本的な閾値にします。ただし以下のように種別によって判断が変わります。

昇格のトリガーを検知する方法

問題は「同じことが別プロジェクトで起きた」という事実に気づかないと昇格のタイミングを逃すことです。以下のパターンで気づけます。

• 同じ fixes の説明を書いた：Project メモリに「これはまたやった」という記憶を加えたとき
• 同じ feedback を繰り返し伝えた：「また Co-Authored-By を付けてきた」と感じたとき
• 別プロジェクトのセットアップ時に同じ指示をした：新規プロジェクトで過去のフィードバックを再入力したとき

これらを感じたら、該当する Project メモリを Global に移動（コピーではなく移動）します。

昇格は一方向：Global → Project には戻さない

Global に昇格したメモリをプロジェクト固有版として Project にコピーすることは避けます。理由はDrift（乖離）です。

Global に「ESLint 9 の flat config 移行」が入っていて、Project にも「このプロジェクトの ESLint 設定」が入っていると、両方を更新しなければならなくなります。一方を更新して他方を忘れると、2つのメモリに矛盾する情報が入り、Claude Code がどちらを信じればいいか分からなくなります。

昇格すべきでない知識の罠

よくある誤りが「汎用的に見える fixes を Global に入れすぎる」ことです。

セットアップ手順：GitHub リポジトリ + CLAUDE.md 設定

GitHub にプライベートリポジトリを作成する

Global メモリを Git で管理するためのリポジトリを作成します。gh CLI（GitHub CLI）を使うと SSH 鍵の設定なしで新しいデバイスでもクローンできます。

# GitHub CLI のインストール（まだの場合）
# macOS: brew install gh
# Windows: winget install --id GitHub.cli

# GitHub CLI でログイン（まだの場合）
gh auth login

# プライベートリポジトリを作成して ~/.claude/global-memory にクローン
gh repo create claude-global-memory --private --clone
mv claude-global-memory ~/.claude/global-memory

# または既存リポジトリを直接クローン
gh repo clone <your-account>/claude-global-memory ~/.claude/global-memory

gh repo clone を使う理由は、gh の認証（GitHub CLI のトークン）をそのまま使えるため、SSH 鍵を別途設定しなくても新しいデバイスで即座にクローンできる点です。新しいデバイスに移ったときは gh auth login と gh repo clone の2コマンドだけで Global メモリが揃います。

初期ファイル構成を作る

cd ~/.claude/global-memory

# インデックスファイル
touch MEMORY.md

# 種別ごとにサブディレクトリは不要（フラットに置く）
touch feedback_no_coauthor.md
touch feedback_response_style.md
touch user_profile.md

# Git に追加
git add -A
git commit -m "init: global memory structure"
git push

MEMORY.md のインデックスを書く

# Global Memory

Claude Code がすべてのプロジェクトで参照するグローバルメモリ。
Project 固有の情報はプロジェクト側のメモリに置く。
昇格ルール：同一問題が2プロジェクト以上で再発 → Global に移動（Project からは削除）。

## User
- [user_profile.md] — 開発者のスキルレベル・好む説明スタイル・ツール環境の前提

## Feedback
- [feedback_no_coauthor.md] — Co-Authored-By トレーラーを付けない（明示的に要求された場合のみ）
- [feedback_response_style.md] — 応答末尾に要約を付けない・箇条書きは情報が複雑な場合のみ

## Fixes
（2プロジェクト以上で再発した fixes のみここに追加する）

個別メモリファイルの書き方

---
name: no-co-authored-by
description: Co-Authored-By トレーラーをコミットメッセージに追加しない
type: feedback
---

コミットメッセージに Co-Authored-By トレーラーを追加しないこと。
ユーザーが明示的に「Co-Authored-By を付けて」と要求した場合のみ追加する。

**Why:** バージョン管理システムの表記ルールに関する好み。
**How to apply:** git commit -m の内容を生成する際に常に適用。

---
name: user-profile
description: 開発者のスキルレベル・作業スタイル・ツール前提知識
type: user
---

**スキルレベル**
- TypeScript/JavaScript: 上級（10年以上）
- Python: 中級（業務スクリプト中心）
- インフラ/DevOps: 初〜中級

**作業スタイルの好み**
- 短く直接的な回答を好む（前置きや言い換えは不要）
- 説明よりコードを見せることを好む
- 実行したことを事後に長々と説明しない

**ツール前提**
- パッケージマネージャ: pnpm（npm は使わない）
- フォーマッタ: Prettier（tabs=false, singleQuote=true）

~/.claude/CLAUDE.md に読み込み指示を追加する

Claude Code がセッション開始時に Global メモリを参照するよう、グローバルの CLAUDE.md に指示を追加します。

# Global Memory

タスク開始時に `~/.claude/global-memory/MEMORY.md` を読み込み、
その内容に基づいて必要な個別メモリファイルをオンデマンドで読む。

昇格ルール：Project メモリの知識が2つ以上のプロジェクトで再発したら
`~/.claude/global-memory/` に移動（Project からは削除）する。
逆向き（Global → Project へのコピー）は行わない。

同期の運用：手動同期と Hooks による自動化

手動同期（最小構成）

最もシンプルな運用は「必要なときだけ手動で同期する」です。

Claude に「sync memory」と伝えると、Claude Code が git pull/push を実行します。この程度の手動操作であれば、自動化のコストを掛けなくても十分機能します。

Hooks による自動同期（上級者向け）

Claude Code の Hooks 機能を使うと、セッション開始時に自動で git pull できます。

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "cd ~/.claude/global-memory && git pull --quiet --rebase 2>/dev/null || true"
          }
        ]
      }
    ]
  }
}

末尾の || true はネットワーク接続がないオフライン環境でも Claude Code が起動するようにするためです。git pull に失敗してもセッションはそのまま開始します。

Push の自動化（Stop Hook）については、Global メモリへの追記はセッション中に Claude Code が行うため、Stop Hook で git add -A && git commit && git push を追加することも可能です。ただし意図しない変更が自動コミットされるリスクがあるため、最初は手動 push の運用から始めることを推奨します。

Memory Rot を防ぐ：メモリが腐敗するとどうなるか

“Memory Rot”（メモリの腐敗）は、一度正しかった情報が時間の経過とともに誤りになる現象です。これはメモリシステムを運用するうえで避けられない問題です。

Memory Rot の予防策

完全に予防することはできませんが、発生を遅らせ、発見を早める仕組みが作れます。

1. 個別メモリファイルに作成日を記録する：frontmatter に created: "2026-03" を追加。6ヶ月以上前のファイルは定期的に見直す
2. fixes 種別に依存バージョンを明記する：「ESLint 9 で発生」のようにバージョンを description と本文に含める。バージョンアップ時に検索できる
3. 月次の棚卸しルーティンを設ける：月に1回、~/.claude/global-memory/ の全ファイルを見直して古いものを削除・更新
4. 「このメモリはいつまで有効か」を本文に書く：期限が明確なものは expires: "2026-03-31" フィールドを使う

---
name: nextjs15-params-promise
description: Next.js 15以降で params が Promise になった変更への対処（searchParams含む）
type: fixes
created: "2026-02"
version-specific: "Next.js 15+"
---

Next.js 15 から `params` と `searchParams` が Promise 型になった。

## 対処
```typescript
// Before (Next.js 14)
export default function Page({ params }: { params: { id: string } }) {}

// After (Next.js 15+)
export default async function Page({ params }: { params: Promise<{ id: string }> }) {
  const { id } = await params;
}
```

## 注記
- `page.tsx` だけでなく `layout.tsx` の `params` も同様
- Next.js 14 との互換モードは存在しない
- Next.js 16 以降でこの挙動が変わる場合は本メモリを更新すること

Memory Rot を発見したときの対処

Claude Code が古いメモリに従って間違った出力をしたとき（たとえば廃止された API を使ったとき）、そのまま「これは間違いです」と修正指示を出すだけではなく、必ずメモリファイル自体も更新します。

1. 「このメモリは古くなっています。更新してください」と Claude Code に伝える
2. Claude Code が該当ファイルを特定・更新する
3. git add -A && git commit -m "fix: update xxx memory (deprecated api)" && git push で反映

修正指示だけ出してメモリを更新しないと、次のセッションで同じ間違いが再発します。

auto-memory との役割分担を整理する

Claude Code には組み込みの auto-memory 機能（Projects の Memory 機能）があります。本記事の2層構造設計と auto-memory は補完関係にあり、どちらかを選ぶものではありません。

実践的な使い方は「auto-memory に短い事実の自動蓄積を任せ、重要なルールや繰り返し発生する問題の解決策は2層構造で管理する」という役割分担です。

auto-memory が「このプロジェクトは TypeScript を使う」と自動記録し、2層構造の Global が「TypeScript の Strict モードで ts18046 が出たときの対処」という詳細な知識を管理します。この組み合わせが現時点での最も強力なメモリ管理体制です。

よくある失敗パターンと対処法

実際に2層構造を運用し始めると、以下のような問題に遭遇することがあります。

昇格の具体的なシナリオ：Before / After で見る

抽象的な昇格ルールより、実際のシナリオで理解する方が運用に役立ちます。

シナリオ1：feedback の昇格

最初の React プロジェクトで Claude Code がコミットメッセージに Co-Authored-By を付けてきた。「付けないでください」と伝え、Project メモリに記録された。

この昇格で「React プロジェクト限定のルール」が「全プロジェクト共通のルール」に格上げされました。以降はすべてのプロジェクトで Co-Authored-By が自動的に省略されます。

シナリオ2：fixes の昇格判断（昇格すべき vs すべきでない）

2つの fixes が Project に入っていたとします。どちらを昇格すべきか考えます。

判断のポイントは「このツール・ライブラリを他のプロジェクトでも使うか？」です。汎用ツール（ESLint・Prettier・TypeScript等）の問題は Global 候補になり、プロジェクト固有のシステムの問題は Project のままにします。

シナリオ3：project 種別は昇格しない

Project メモリに「スプリント3のマージフリーズは3/31まで」という project 種別のエントリがありました。4月になっても削除されず残っていました。

この種別は絶対に Global に昇格しません。そもそも期限が過ぎたら Project から削除するのが正しい対応です。project 種別のファイルは定期的に見直し、有効期限が切れたものを積極的に削除します。

Global メモリの実践的なサンプル集

実際にどんな内容を Global メモリに入れるかのサンプルです。自分の環境に合わせてカスタマイズしてください。

feedback 種別のサンプル

---
name: response-style
description: 応答スタイルの指針（前置き・要約・箇条書きに関するルール）
type: feedback
created: "2026-01"
---

**やめること**
- 回答の冒頭で「承知しました」「もちろんです」などの肯定フレーズを使わない
- 実行した内容を末尾に長々と再説明しない（diff を見れば分かる）
- 単純な質問に箇条書きで回答しない（複雑な内容の場合のみ使う）
- 見出し・絵文字を過剰に使わない

**やること**
- 答えから始める（理由・背景は後で）
- コードで示せる場合はコードを先に見せる
- ファイル・関数への参照は `file:line` 形式で

---
name: no-docstring-bloat
description: 変更していない関数にコメント・docstring を追加しない
type: feedback
created: "2026-02"
---

変更していないコードにコメントや docstring を追加しないこと。

**理由：** 「改善」として追加されたコメントが意図しない diff を作り、
コードレビューの際にノイズになった実績がある。

**How to apply：**
- ファイルを編集する際、変更箇所以外のコメントを追加・修正しない
- 「このコードを分かりやすくするためにコメントを追加しました」はやらない
- ユーザーが明示的にコメント追加を依頼した場合のみ対応

fixes 種別のサンプル（複数プロジェクトで再発した例）

---
name: eslint9-flat-config
description: ESLint 9 以降で .eslintrc.js が廃止・flat config への移行（eslint.config.js）
type: fixes
created: "2026-01"
version-specific: "ESLint 9+"
---

## 症状
`eslint` 実行時に `.eslintrc.js` が無視される、または
`ESLint couldn't find the config file` エラーが出る。

## 原因
ESLint 9 から `.eslintrc.*` 形式が廃止され、
flat config（`eslint.config.js`）が必須になった。

## 対処
```javascript
// eslint.config.js（プロジェクトルートに作成）
import js from "@eslint/js";
import globals from "globals";

export default [
  js.configs.recommended,
  {
    languageOptions: {
      globals: {
        ...globals.browser,
        ...globals.node,
      },
    },
    rules: {
      // プロジェクト固有のルールはここに追加
    },
  },
];
```

## TypeScript プロジェクトの場合
```javascript
import tseslint from "typescript-eslint";

export default tseslint.config(
  ...tseslint.configs.recommended,
);
```

## 注記
- `eslint-plugin-*` 系のプラグインも flat config 対応版に更新が必要な場合がある
- ESLint 8 との後方互換モード（`ESLINT_USE_FLAT_CONFIG=false`）は ESLint 10 で廃止予定

user 種別のサンプル

---
name: user-profile
description: 開発者プロフィール・スキルレベル・ツール設定の前提知識
type: user
created: "2026-01"
---

## 経験・スキル
- JavaScript/TypeScript: 上級（10年以上・フロントエンド〜バックエンド）
- Python: 中級（スクリプト・自動化・データ処理）
- Go: 基礎レベル（読める・書けるが深い知識なし）
- SQL/Oracle: 上級（PL/SQL・チューニング経験あり）

## 作業スタイル
- 高度な内容は前置きなしで話せる（基本的な説明は不要）
- 短く直接的な回答を好む
- 「なぜ」より「どうする」を先に教えてほしい
- コードで示せるなら文章より先にコードを見せる

## ツール環境
- OS: Windows 11（WSL2 併用）・macOS（MacBook Pro）
- エディタ: VS Code + Claude Code
- パッケージマネージャ: pnpm（npm は使わない）
- フォーマッタ: Prettier（tabs=false, singleQuote=true, semi=false）
- バージョン管理: Git（コミットメッセージは日本語可）

実践的な運用フロー：日常の使い方

設計が完成したら、日常の Claude Code 利用でどう動くかを確認します。

新規プロジェクトを始めるとき

1. Claude Code を開く → SessionStart で Global メモリを git pull（Hooks 設定済みの場合は自動）
2. プロジェクト固有の CLAUDE.md を作成して技術スタック・制約を記載
3. セッション中に出てきた Project 固有の知識は Project メモリに Claude Code が自動的に追加

別デバイスに切り替えるとき

1. gh auth login（初回のみ）
2. gh repo clone <account>/claude-global-memory ~/.claude/global-memory
3. Claude Code を開く → Global メモリが即座に有効

同じ問題が別プロジェクトで再発したとき

1. 「このメモリを Global に昇格してください」と Claude Code に伝える
2. Claude Code が該当ファイルを ~/.claude/global-memory/ に移動し MEMORY.md を更新
3. Project メモリから該当エントリを削除
4. cd ~/.claude/global-memory && git add -A && git commit -m "promote: ..." && git push

よくある質問

まとめ：設計することで Claude Code は”賢くなり続ける”

本記事のポイントを整理します。

Claude Code は使えば使うほど賢くなるポテンシャルを持っています。しかし設計なしにフィードバックを与え続けると、すぐに分断・重複・腐敗が起きます。メモリを設計することが、Claude Code を本当の意味で育てるということです。auto-memory と本設計を組み合わせ、Hooks で自動化を加えれば、セッションをまたいでもデバイスをまたいでも、一貫した知識を持った AI として機能し続けます。