# 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 双轨）：

```bash
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、迁移脚本、说明、审计记录）重新生成。
