chore(migration): Cursor → Claude Code 反向迁移 + 单轨化（v2）
- 删除 5 个 AGENTS.md（根 + 4 子模块）与 .cursor/、.cursorignore，全部已备份 - 在 CLAUDE.md 末尾追加 5 节迁移必需内容（CLI/Shell 中文与编码、Claude Code 资产入口、Hook 与权限、不破坏原则、历史追溯），保留用户选定的 226 行项目规则全集 - 用户级 12 个 skills 从 ~/.cursor/skills/ 剥包装回迁到 ~/.claude/skills/（neozqyy-cursor-migration → neozqyy-claude-code-migration） - docs/ai-env-history/ 顶层 10 文件入仓（含 conversation_index.csv、file_impact_index.csv，已脱敏）；sessions/ 原文继续本地保留 - 新增 tools/claude-code/migrate_ai_environment.py（--check 14/14 通过） - 新增 docs/claude_code_migration.md 与 docs/audit/changes/2026-05-02__claude_code_migration.md - .gitignore 调整：开放 2 个 CSV 索引入仓，保留 sessions/ 与 claude-history/ 排除 - 不混入 124 个业务变更（AI 模块重构、runtime_context、sandbox 等保持 unstaged） - 备份位置：~/.claude/backups/pre-claude-code-migration-2026-05-02/ 第二轮迁移（第一轮 commit 6facb2d 已被 git reset 回滚；本轮策略为追加而非重写 CLAUDE.md）
This commit is contained in:
160
docs/claude_code_migration.md
Normal file
160
docs/claude_code_migration.md
Normal file
@@ -0,0 +1,160 @@
|
||||
# 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、迁移脚本、说明、审计记录）重新生成。
|
||||
Reference in New Issue
Block a user