project-directory-migration

プロジェクトディレクトリの移行

プロジェクトディレクトリの名前を変更する際に、Claude Code のプロジェクトコンテキスト（セッション、メモリ、履歴）を安全に移行します。

自己進化型スキル：このスキルは使用を通じて改善されます。手順に誤りがある場合、パラメーターが変化した場合、または回避策が必要になった場合は、後回しにせず、すぐにこのファイルを修正してください。実際に再現可能な問題がある場合にのみ更新してください。

このスキルを使用するタイミング

次の場合にこのスキルを使用してください。

• プロジェクトディレクトリの名前を変更する場合（例：my-old-name/ から my-new-name/ へ）
• プロジェクトを別のパスに移動する場合
• ディレクトリ名の変更後に「会話が見つかりません」と表示される場合
• ワークスペースディレクトリを再編成する場合
• パッケージ名の変更に合わせて、ディレクトリ名を GitHub リポジトリ名に一致させる必要がある場合
• ディレクトリの移動後に孤立したセッションを復元する場合

対話型ワークフロー

フェーズ 1：情報の収集

AskUserQuestion を使用して、移行元と移行先のパスを収集します。

Question 1 (header: "Source"): "What is the current project directory path?"
  Options:
    - "Use current directory: $PWD" (Recommended)
    - "Specify a different path"

Question 2 (header: "Target"): "What should the new directory path be?"
  Options:
    - (User provides via "Other" free text)

フェーズ 2：ドライラン監査

移行スクリプトを --dry-run モードで実行し、移行が必要な項目を確認します。

bash "<skill-scripts>/claude-code-migrate.sh" --dry-run "$OLD_PATH" "$NEW_PATH"

確認結果をユーザーに提示します。

• 見つかったセッションファイルの数
• 書き換え対象の history.jsonl エントリー数
• 自動メモリ（MEMORY.md）の有無
• 検出された環境ツール（uv、direnv、asdf。残存する mise 設定は廃止済みとして警告されます）

フェーズ 3：範囲の確認と確定

Question 3 (header: "Scope", multiSelect: true):
  "What should be included in migration?"
  Options:
    - "Claude Code sessions + history (Recommended)"
    - "Auto-memory (MEMORY.md) (Recommended)"
    - "Backward-compatibility symlink (Recommended)"
    - "Auto-fix environment: venv recreate (Recommended)"

Question 4 (header: "Execute"):
  "Ready to migrate? The script creates a timestamped backup first."
  Options:
    - "Execute migration now (Recommended)"
    - "Export copy-paste commands for manual execution"
    - "Cancel"

ユーザーが「コピーして貼り付けるコマンドをエクスポート」を選択した場合：Claude Code を終了した後にターミナルへ貼り付けて実行できる、正確なコマンドを生成します。移行中に Claude Code がプロジェクトファイルへアクセスしないため、これが最も安全な方法です。

フェーズ 4：移行後の報告

移行が完了したら、次の内容を報告します。

• 移行したセッション、書き換えた履歴エントリー
• 適用した環境の修正（venv の再作成）
• 残っている手動作業（git remote の更新など）
• 問題が発生した場合のロールバックコマンド

---

クイックリファレンス

Claude Code のパスエンコーディング

Claude Code は / を - に置き換えてディレクトリパスをエンコードします。

/Users/alice/projects/my-app  -->  -Users-alice-projects-my-app

保存場所

アセット	場所
セッション	~/.claude/projects/{encoded-path}/*.jsonl
メモリ	~/.claude/projects/{encoded-path}/memory/MEMORY.md
セッションインデックス	~/.claude/projects/{encoded-path}/sessions-index.json
履歴	~/.claude/history.jsonl
サブエージェント	~/.claude/projects/{encoded-path}/{session-id}/subagents/

パス参照を含むファイル

ファイル	パスを含むフィールド	書き換えが必要？
sessions-index.json	originalPath、entries[].projectPath、entries[].fullPath	はい
history.jsonl	各エントリーの project フィールド	はい
セッションの .jsonl ファイル	なし	いいえ
MEMORY.md	なし（内容のみ）	いいえ

---

移行スクリプト

​​scripts/claude-code-migrate.sh にあります。

使用方法

# Dry run (preview what would happen)
bash scripts/claude-code-migrate.sh --dry-run /old/path /new/path

# Execute migration
bash scripts/claude-code-migrate.sh /old/path /new/path

# Rollback from most recent backup
bash scripts/claude-code-migrate.sh --rollback

# Show help
bash scripts/claude-code-migrate.sh --help

9 フェーズの実行

1. 事前検証 — 7 項目を確認します（パス、Claude Code ディレクトリ、python3、実行中のセッションがないこと）
2. バックアップ — ~/.claude/migration-backup-YYYYMMDD-HHMMSS/ にタイムスタンプ付きのコピーを作成します
3. プロジェクトディレクトリの移動 — ~/.claude/projects/ 内で名前を変更します
4. sessions-index.json の書き換え — projectPath、fullPath、originalPath を更新します
5. history.jsonl の書き換え — project フィールドを更新します（JSON セーフで、Unicode を保持します）
6. 後方互換性シンボリックリンク — 古いエンコード済みパスから新しいパスへのシンボリックリンクを作成します
7. リポジトリディレクトリの名前変更 — mv /old/path /new/path
8. 環境の修正 — venv の再作成、direnv/asdf の警告、残存する mise 設定の警告
9. 事後検証 — セッション数、メモリ、シンボリックリンク、環境の状態を確認します

---

リファレンスドキュメント

• セッションストレージの構造 — Claude Code がプロジェクトデータを保存する方法
• トラブルシューティングガイド — 移行後によくある問題とその解決方法
• 進化ログ — スキルの改善履歴

---

トラブルシューティング

問題	自動修正？	手動での解決方法
シェルプロンプトに (old-name) が表示される	はい（フェーズ 8）	ターミナルを再起動するか、uv sync を実行します
VIRTUAL_ENV のパスが一致しない	はい（フェーズ 8）	uv sync --dev で venv を再作成します
「会話が見つかりません」	はい（フェーズ 4）	移行スクリプトを再実行します
.envrc が許可されていない	警告（フェーズ 8）	direnv allow を実行します
Git のプッシュ認証に失敗する	いいえ	資格情報ヘルパーまたはリモート URL を更新します
セッションのサブディレクトリが見つからない	いいえ	--rollback を使用して再試行します

実行後の振り返り

このスキルの実行が完了したら、タスクを終了する前に振り返ってください。

0. 現在地を特定します。 — 編集する前に、この SKILL.md の正規のパスを確認します。
1. 何が失敗しましたか？ — 原因となった指示を修正します。
2. 期待以上にうまくいったことは何ですか？ — 推奨される実践方法として取り入れます。
3. 現状と食い違っているものは何ですか？ — 実態に合わなくなったスクリプト、リファレンス、依存関係を修正します。
4. 記録します。 — きっかけ、修正内容、根拠を含む進化ログのエントリーを追加します。

先送りしないでください。次回の実行では、あなたが残した状態が引き継がれます。