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：迁移后报告

迁移完成后，报告：

• 已迁移的会话、已重写的历史记录条目
• 已应用的环境修复（重新创建虚拟环境）
• 仍需手动完成的步骤（更新 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
子 Agent	~/.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 如何存储项目数据
• 故障排除指南 — 常见的迁移后问题及其解决方法
• 演进日志 — Skill 改进历史

---

故障排除

问题	自动修复？	手动解决方法
shell 提示符中的 (old-name)	是（阶段 8）	重启终端或运行 uv sync
VIRTUAL_ENV 路径不匹配	是（阶段 8）	uv sync --dev 重新创建 venv
“No conversations found”	是（阶段 4）	重新运行迁移脚本
.envrc 未获允许	已警告（阶段 8）	direnv allow
Git 推送身份验证失败	否	更新凭据助手或远程 URL
会话子目录缺失	否	使用 --rollback，然后重试

执行后反思

此 Skill 完成后，请在结束任务前进行反思：

0. 确认自身位置。 — 编辑前找到此 SKILL.md 的规范路径。
1. 哪里失败了？ — 修复导致问题的指令。
2. 哪些地方比预期更顺利？ — 将其提升为推荐做法。
3. 哪些内容发生了偏差？ — 修复不再符合实际情况的脚本、参考资料或依赖项。
4. 记录下来。 — 在演进日志中记录触发原因、修复方法和证据。

请勿推迟。下一次调用会继承你留下的一切。