Neo
f2e0de8fab
- 删除 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）
128 lines
7.5 KiB
Markdown
128 lines
7.5 KiB
Markdown
# 变更审计记录：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 迁移文件 |
|