# 变更审计记录：Cursor → Claude Code 反向迁移与单轨化

| 字段 | 值 |
|------|-----|
| 日期 | 2026-05-02 |
| 类型 | 开发环境迁移 + 项目规则单轨化 |
| Git HEAD（迁移前） | 81e4173 |
| 当前分支 | dev |
| 备注 | 第二轮迁移（第一轮 commit 6facb2d 已被用户 git reset 回滚） |

## 操作摘要

把项目主开发环境从 Cursor 反向迁回 Claude Code，并完成**单轨化**：删除 AGENTS.md 双轨、删除 `.cursor/` Cursor 自带格式资产，全面采用 Claude Code 原生 CLAUDE.md / `.claude/` 结构。用户级 12 个手写 skills 从 `~/.cursor/skills/` 剥包装回迁到 `~/.claude/skills/`。`docs/ai-env-history/` 顶层索引（8 个 md/json + 2 个 CSV）入仓。新建 `tools/claude-code/migrate_ai_environment.py` 作为决策固化与校验脚本。

**与第一轮的差异**：本轮保留用户在 reset 后选定的 226 行 CLAUDE.md（更全），**仅追加** Claude Code 必需的 5 节迁移内容（CLI/Shell 编码、资产入口、Hook、不破坏原则、历史追溯），不重写为精简版。

## 变更文件

### 新增

- `docs/claude_code_migration.md`（迁移说明、决策记录、回滚步骤）
- `docs/audit/changes/2026-05-02__claude_code_migration.md`（本文件）
- `tools/claude-code/migrate_ai_environment.py`（决策固化 + `--check` 模式校验 14 项）
- `docs/ai-env-history/`（顶层 10 个文件首次入仓：README + 4 csv + 1 json + 4 md；含本次新追加 conversation_index.csv 与 file_impact_index.csv 的 .gitignore 调整）

### 修改

- `CLAUDE.md`（追加 5 节：CLI/Shell 中文与编码强制 + Claude Code 资产入口表 + Hook 与权限表 + 不破坏原则 + 历史追溯；保留原 226 行项目规则不动）
- `.gitignore`（开放 conversation_index.csv 与 file_impact_index.csv，sessions/ 与 claude-history/ 仍排除）
- `docs/ai-env-history/topic_timeline.md`（追加"反向迁移 Cursor → Claude Code"主题节，已在第一轮保留）

### 删除

- `AGENTS.md`（根，130 行，已备份）
- `apps/backend/AGENTS.md`（52 行，已备份；CLAUDE.md 等价保留）
- `apps/etl/connectors/feiqiu/AGENTS.md`（81 行，已备份；CLAUDE.md 等价保留）
- `apps/demo-miniprogram/AGENTS.md`（18 行，已备份）
- `db/AGENTS.md`（60 行，已备份）
- `.cursor/`（整目录：rules/.mdc × 8 + skills/SKILL.md × 5 + hooks.json + ai_env_guard.py + mcp.json，已完整备份）
- `.cursorignore`（已备份）

### 用户级（仓外）

- 重新生成 `~/.claude/skills/`（12 个 skill 目录，63 文件；从 `~/.cursor/skills/` 剥包装）
- 备份 `~/.claude/backups/pre-claude-code-migration-2026-05-02/`（项目+用户级源资产 + BACKUP_MANIFEST.md）

## 改动注解

### 高风险文件

**`CLAUDE.md`（根）**

- 类型：修改（追加 5 节迁移内容到 226 行版本末尾）
- 原因：Claude Code 原生加载 `CLAUDE.md`；保留用户主动选定的 226 行项目规则全集；追加 Claude Code 必需的工作机制描述
- 思路：第一轮重写为 179 行被用户回滚（用户偏好保留完整规则）；本轮策略为"追加"而非"重写"，把"CLI/Shell 中文与编码"插入"语言（强制）"之后，把"Claude Code 资产入口"+"Hook 与权限"+"不破坏原则"+"历史追溯"4 节追加到末尾
- 风险：高（项目权威规则）；回滚：`git checkout HEAD -- CLAUDE.md` 即恢复到 81e4173 版本

**`docs/ai-env-history/` 入仓**

- 类型：新增（10 个顶层文件首次入仓）
- 原因：上轮 Cursor 迁移产生但未入仓；本次反向迁移要求"复用历史索引"，需固化到 git
- 思路：先做敏感扫描（DSN/API key/JWT/AWS），仅 2 个 hit 经核实是文档中描述敏感扫描正则模式自身（误报）；`sessions/` 子目录 109 文件因体积大、是原文摘要，继续 .gitignore 保留本地
- 结果：10 文件入仓（README、apps_current_worklist、cursor_migration_manifest、dev_environment_inventory、topic_timeline.md、topic_timeline.csv、vscode_insiders_extensions.csv、w0-01_worktree_split_execution、conversation_index.csv、file_impact_index.csv），无密钥/DSN 泄露
- 风险：低；回滚：`git rm -r --cached docs/ai-env-history/`

**`.cursor/` 整目录删除**

- 类型：删除
- 原因：Cursor 自带格式资产，与 Claude Code 不兼容；rules/.mdc 内容已提炼进 CLAUDE.md，skills 已镜像到 `.claude/commands/`，hooks 已转为 `.claude/hooks/*.py`
- 风险：高（项目级规则源）；回滚：备份在 `~/.claude/backups/pre-claude-code-migration-2026-05-02/project_cursor/.cursor/`

**用户级 skills 回迁**

- 类型：新增（~/.claude/skills/ 12 个目录）
- 原因：原则 #2 "用户手写规则、skills 完整迁移"；这些 skill 的 description 明确标注"从 Claude Code 迁移"，本质是用户在 Claude Code 时代的手写资产，被搬到 Cursor 时包了一层兼容层
- 思路：批量脚本剥掉迁移说明前言、`disable-model-invocation` 字段、Codex 时代尾部话术；按需求文档第 10 节触发策略调整 description（自动触发 2 个、显式触发 10 个）；`neozqyy-cursor-migration` 重命名为 `neozqyy-claude-code-migration` 并重写指向 Claude 原生路径
- 风险：低（用户目录，备份完整）；回滚：`rm -rf ~/.claude/skills`，~/.cursor/skills/ 原位保留

### 普通文件

- 4 个子模块 `CLAUDE.md` 未改动（diff 显示与对应 AGENTS.md 等价，仅符号差异 `→` vs `->`）
- `.claude/commands/`、`.claude/hooks/`、`.claude/settings.json`、`.mcp.json` 未改动
- 用户级 `~/.claude/agents/` 8 个未改动

## 数据库变更

无。本次迁移不涉及任何 schema/迁移/DDL/RLS 变更。

## 风险与回滚

### 风险点

- **中**：CLAUDE.md 追加章节后总行数 ~290 行，内容偏多但分章节清晰；下次会话开始会自动加载新版本，按 Claude Code 规范行为
- **低**：用户级 12 个 skills 的触发关键词调整后，模型自动匹配命中率可能轻微下降（显式触发的 10 个本就要求显式调用）
- **低**：`.cursor/` 删除后，如果同一仓库被 Cursor 打开，Cursor 会读不到规则；用户已确认主用 Claude Code，Cursor 作为冷备
- **可忽略**：`.ignore` 文件保留（ripgrep 用），但 Cursor 时代设置的某些 ignore 规则已删（`.cursorignore`）

### 回滚要点

- 完整回滚：见 `docs/claude_code_migration.md` 第 5 节 + `BACKUP_MANIFEST.md`
- 部分回滚（仅恢复 AGENTS.md）：从 `~/.claude/backups/pre-claude-code-migration-2026-05-02/project_root/` 复制对应文件
- Skills 回滚：`rm -rf ~/.claude/skills`（~/.cursor/skills/ 原位未动）
- CLAUDE.md 回滚到追加前：`git checkout HEAD -- CLAUDE.md`

## 验证

### 已执行

- `python tools/claude-code/migrate_ai_environment.py --check` → **14/14 通过**

### 待用户后续验证

- IDE 中输入 `/audit` 等 5 个 slash 命令是否能加载（需 Claude Code 重新加载会话）
- 8 个 subagent 通过 `Agent` 工具调用是否正常
- MCP 测试库 `pg-etl-test` / `pg-app-test` `SELECT 1` 通过

## 合规检查

| 项目 | 状态 |
|------|------|
| `docs/claude_code_migration.md` | 已创建（迁移说明） |
| `docs/audit/changes/2026-05-02__claude_code_migration.md` | 本文件 |
| `docs/audit/audit_dashboard.md` | 已被 124 个业务变更修改（M），收尾时统一刷新 |
| `docs/ai-env-history/` 入仓 | 顶层 10 文件 |
| 敏感扫描 | 0 hit |
| 备份完整性 | BACKUP_MANIFEST.md 含回滚步骤 |
| 不混入 124 个业务变更 | 仅 add 迁移文件 |
