Neo-ZQYY/docs/claude_code_migration.md

Cursor → Claude Code 反向迁移说明（2026-05-02）

迁移路径：旧服务器 → 本机 → Claude Code → Codex → Cursor → Claude Code（当前，单轨化）

0. 一句话总结

把上一轮主环境 Cursor 沉淀的所有用户手写资产（规则、skills、agents、hooks、MCP）反向迁回 Claude Code 原生格式，单轨化：删除 AGENTS.md / .cursor/ 等 Cursor 自带格式资产，保留 CLAUDE.md / .claude/ 等 Claude Code 原生格式。

1. 迁移原则

1. Cursor/Codex 自带模板 → 备份去除
2. 用户手写规则、agents、skills、MCP → 完整迁移
3. 迁移内容符合 Claude Code 要求和使用习惯
4. 还原或重建 Claude 需要的内容组件 / 索引
5. 最大程度还原使用习惯，回归到 Claude Code 进行开发

2. 关键决策

2.1 单轨化（核心变化）

去除 AGENTS.md 双轨，全面采用 Claude Code 原生 CLAUDE.md：

删除（已备份）：

• 根 AGENTS.md（130 行）
• apps/backend/AGENTS.md、apps/etl/connectors/feiqiu/AGENTS.md、apps/demo-miniprogram/AGENTS.md、db/AGENTS.md
• .cursor/（整个目录，含 rules/.mdc、skills/、hooks/、mcp.json、hooks.json）
• .cursorignore

保留（重写或验证等价）：

• 根 CLAUDE.md（226 行）：保留用户已选定的项目规则全集，追加迁移所需 5 节（CLI/Shell 中文与编码、Claude Code 资产入口、Hook 与权限、不破坏原则、历史追溯）
• 4 个子模块 CLAUDE.md（验证内容已与对应 AGENTS.md 等价，无需合并）
• .claude/commands/（5 个 slash 命令）、.claude/hooks/（8 个 Python hook）、.claude/settings.json
• .mcp.json（单一源；prod 库 disabled: true、test 库 disabled: false）
• .ignore（ripgrep 工具，非 Cursor 自带，保留）

保留为冷备：

• tools/cursor/、tools/codex/（.mcp.json 仍引用 tools/codex/mcp-postgres.ps1）
• ~/.cursor/（用户级 Cursor 配置）

2.2 用户级 skills 回迁

12 个用户级 skill 从 ~/.cursor/skills/ 反向迁移到 ~/.claude/skills/，剥掉 Cursor 时代的兼容包装：

• 删除每个 SKILL.md 头部的"迁移说明：本 skill 从 ... 转换而来"前言
• 删除 frontmatter 里的 disable-model-invocation: true（Cursor 专属字段）
• 简化 description，去掉"从 Claude Code 迁移；当用户提到 $xxx、原 Claude skill"的兼容话术
• neozqyy-cursor-migration 重命名为 neozqyy-claude-code-migration，重写内容指向 Claude Code 原生路径

触发策略（需求文档第 10 节原样照搬）：

• 自动触发（2 个）：neozqyy-claude-code-migration、strategic-compact（claude-api 是系统内置 skill，不在用户目录）
• 显式触发（10 个）：agent-introspection-debugging / claude-agent-roles / claude-rules-reference / code-tour / codebase-onboarding / repo-scan / rules-distill / search-first / security-review / tdd-workflow — description 末尾追加 Explicit invocation only — invoke via Skill tool with name=<X> or by typing $<X>.

不迁移：

• ~/.cursor/skills-cursor/ 13 个 Cursor 元工具（babysit / canvas / create-* / cursor-sdk / migrate-to-skills / shell / split-to-prs / statusline / update-cli-config / update-cursor-settings）
• 这些是 Cursor IDE 自带的命令工具，与 Claude Code 工作模式不兼容，原位保留为冷备

2.3 用户级 agents 不动

~/.claude/agents/ 已有 8 个 subagent（architect / code-reviewer / database-reviewer / planner / python-reviewer / refactor-cleaner / security-reviewer / tdd-guide），与需求一致。~/.cursor/agents/ 同名 8 个不再迁移（已存在）。

2.4 项目级 .claude/ 不创建 agents/skills 子目录

按用户决策"还原 Claude 默认配置"：

• .claude/agents/ 不创建（沿用用户级 ~/.claude/agents/）
• .claude/skills/ 不创建（项目级流程通过 .claude/commands/*.md 暴露为 slash 命令）

2.5 Hook 设计

.claude/hooks/*.py 8 个分立 Python 文件结构（来自上轮 Codex 迁移），不复用 Cursor 的单文件 dispatcher（ai_env_guard.py）。Hook 命令使用裸 python，依赖 .claude/settings.local.json 配置的 PATH（.venv/Scripts 已在 PATH 头部）。

2.6 MCP 单一源

.mcp.json 是唯一权威源。Cursor 时代留下的 .cursor/mcp.json（仅 test 库子集）随 .cursor/ 整体归档删除。

Server	默认状态	备注
pg-etl	disabled	生产 ETL 库，按需开启
pg-app	disabled	生产业务库，按需开启
pg-etl-test	enabled	测试 ETL 库（默认）
pg-app-test	enabled	测试业务库（默认）
weixin-devtools-mcp	enabled	微信开发者工具
playwright	enabled	Playwright
openapi	enabled	后端 OpenAPI

DSN 通过 tools/codex/mcp-postgres.ps1 间接读取（PG_DSN / APP_DB_DSN / TEST_DB_DSN / TEST_APP_DB_DSN），不写入文档。

2.7 历史索引入仓

docs/ai-env-history/ 顶层 8 文件 + 2 个 CSV 索引入仓（敏感扫描通过，无密钥/DSN 泄露）。本次反向迁移作为新一节追加到 topic_timeline.md，README 头部追加迁移路径说明。sessions/ 子目录 109 个原文摘要继续本地保留（gitignore 排除）。

2.8 CLAUDE.md 处理（本次新策略）

与 5 月 2 日早些时候的迁移决策不同：本次保留用户主动选定的 226 行版本（包含完整的项目规则、常用命令、架构模式、子代理、审计等章节），仅追加 Claude Code 必需的 5 节迁移内容，而不是重写为精简版。原因：用户在第一次迁移完成后做了 git reset 并保留了更全的版本，这是用户偏好。

3. 不做的事

• 不删除 tools/cursor/、tools/codex/（冷备 + .mcp.json 引用）
• 不触碰 ~/.claude/projects/c--Project-NeoZQYY/memory/（用户记忆持久化）
• 不触碰 124 个未提交业务变更（AI 模块重构、runtime_context、sandbox 等）
• 不修改 ~/.claude/agents/ 8 个文件（已存在）
• 不创建 .claude/agents/ 或 .claude/skills/（保留 Claude Code 默认结构）

4. 验证（migrate_ai_environment.py --check）

执行 python tools/claude-code/migrate_ai_environment.py --check：

检查项	期望	实际
迁移备份目录	存在 + 含 BACKUP_MANIFEST.md	OK
根 CLAUDE.md 5 节迁移章节	全部存在	OK
CLAUDE.md 单轨保留（5 个）	全部存在	OK
AGENTS.md 已归档（5 个）	全部不存在	OK
.cursor/ + .cursorignore 已归档	全部不存在	OK
.claude/ 项目级资产（14 个）	全部存在	OK
用户级 8 个 subagent	全部存在	OK
用户级 12 个 skills	全部存在	OK
Skills 已剥 Cursor 包装	无残留	OK
MCP 单一源 + prod/test 状态	正确	OK
docs/ai-env-history/ 入仓	≥100 文件	OK 117
历史索引敏感扫描	0 hit	OK
冷备资产保留	全部存在	OK
用户记忆未受影响	文件数 ≥5	OK 13

5. 回滚步骤

详见 ~/.claude/backups/pre-claude-code-migration-2026-05-02/BACKUP_MANIFEST.md。

部分回滚（仅恢复 AGENTS.md 双轨）：

cp ~/.claude/backups/pre-claude-code-migration-2026-05-02/project_root/AGENTS.md .
for sub in apps/backend apps/etl/connectors/feiqiu apps/demo-miniprogram db; do
  cp ~/.claude/backups/pre-claude-code-migration-2026-05-02/project_root/$sub/AGENTS.md $sub/
done

6. 备份位置

~/.claude/backups/pre-claude-code-migration-2026-05-02/

7. 已知遗留

• 124 个未提交业务变更：迁移前已存在（AI 模块重构、runtime_context、sandbox 等），与本次迁移无关，未触碰
• docs/audit/audit_dashboard.md：当前已被业务变更修改（M），将在业务变更收尾时统一刷新
• apps/etl/connectors/feiqiu/.env 已修改：业务变更产物
• ~/.cursor/skills-cursor/ 13 个 Cursor 元工具：原位保留为冷备
• tools/codex/：保留为冷备 + .mcp.json 仍引用 mcp-postgres.ps1，不删除

8. 历史回顾

本次迁移在 5 月 2 日有过两轮：

1. 第一轮（commit 6facb2d）：把根 CLAUDE.md 重写为 179 行精简版（吸收 AGENTS.md）。提交后用户做了 git reset 81e4173 并保留了更全的 226 行 CLAUDE.md，删除了 tools/claude-code/、docs/claude_code_migration.md 等迁移产物，并 rm -rf ~/.claude/skills/。
2. 第二轮（本次）：尊重用户保留的 226 行 CLAUDE.md，仅在末尾追加 5 节迁移必需内容；其余产物（用户级 skills、迁移脚本、说明、审计记录）重新生成。