102 lines
4.5 KiB
Markdown
102 lines
4.5 KiB
Markdown
# Claude 项目上下文迁移到 Codex：设计说明
|
||
|
||
## 目标
|
||
|
||
在不删除或修改现有 `.claude` 配置的前提下，把 `factory` 项目中仍有效的 Claude 项目知识迁移成 Codex 可稳定使用的项目级上下文。
|
||
|
||
迁移后的配置应做到：
|
||
|
||
- Codex 每次进入仓库时都能读取关键项目约束。
|
||
- 较长的背景资料和历史排障记录不会挤占常规任务上下文。
|
||
- 发版流程只在用户明确要求时启用。
|
||
- 不复制数据库口令等敏感信息。
|
||
- Claude 与 Codex 可以继续并行使用。
|
||
|
||
## 现状
|
||
|
||
项目内现有 Claude 配置：
|
||
|
||
- `.claude/settings.local.json`：Claude 工具授权历史，包含大量机器相关命令及明文数据库连接信息。
|
||
- `.claude/commands/release.md`：后端发版命令。
|
||
- Claude 用户目录中的项目 memory：包含前后端关系、动态路由、Python 虚拟环境、生产库只读查询约束、脚本忽略规则、发版约束、套壳 App 背景及一次历史缺陷排查。
|
||
|
||
项目当前没有根目录 `CLAUDE.md`、`AGENTS.md` 或项目级 Codex memory。
|
||
|
||
## 采用方案
|
||
|
||
采用分层兼容结构：
|
||
|
||
1. 根目录 `AGENTS.md`
|
||
- 放置每次工作都应遵守的稳定规则。
|
||
- 内容保持简短，避免把一次性历史排障细节注入所有任务。
|
||
- 指向更详细的 memory 和按需 skill。
|
||
|
||
2. `.agents/skills/release/SKILL.md`
|
||
- 把 `.claude/commands/release.md` 转换为 Codex 项目 skill。
|
||
- 仅在用户明确要求“发版”“release”或“bump 版本”时使用。
|
||
- 保留版本生成、更新 `SYS_VERSION`、检查 changelog、提交、打 tag 和推送的顺序。
|
||
- 去掉 Claude 专属的 `Co-Authored-By` 署名。
|
||
- 保留远端写操作前的工作区检查和失败处理约束。
|
||
|
||
3. `.codex/memory/`
|
||
- `MEMORY.md` 作为主题索引。
|
||
- 按主题保存项目背景、用户反馈和历史排障资料。
|
||
- 去除 Claude 的 session ID、Claude 专属元数据和 wiki 链接语法。
|
||
- 使用普通 Markdown 相对链接，便于人工和 Codex 按需读取。
|
||
|
||
4. `.claude/`
|
||
- 原样保留，不删除、不重写。
|
||
|
||
## 内容映射
|
||
|
||
必须进入 `AGENTS.md` 的规则：
|
||
|
||
- 配套前端位于 `../ehs_web`；后端 API 变化时检查对应前端调用。
|
||
- `ehs_web` 菜单和路由由后端动态下发，新页面不要修改 `src/config/route.js`。
|
||
- Django/Python 命令使用项目根目录 `.venv/Scripts/python.exe`。
|
||
- `scripts/*.py` 是有意忽略的一次性脚本，未经明确要求不得 `git add -f`。
|
||
- 不自动提升版本或发版，只有用户明确要求时才执行 release skill。
|
||
- 生产数据库只允许只读查询；任何写操作需要用户另行明确授权。
|
||
- 不在项目文档、skill 或命令中保存数据库口令。
|
||
|
||
保存在 `.codex/memory/` 的资料：
|
||
|
||
- 前后端工程关系与统计页面惯例。
|
||
- 生产数据库只读验证方法，但连接参数只指向本地忽略配置，不记录凭据。
|
||
- 前端独立发版流程。
|
||
- 两个 WebView 套壳 App 的位置与交互约定。
|
||
- `material_ofrom` 合批历史缺陷的排查结论和后续接续点。
|
||
- 上述关键反馈规则的详细原因。
|
||
|
||
不迁移的内容：
|
||
|
||
- `.claude/settings.local.json` 中的 Claude 权限语法。
|
||
- 临时 scratchpad 路径、历史会话 ID、一次性命令白名单。
|
||
- 数据库用户名、密码及可直接复用的带密码命令。
|
||
|
||
## 安全与错误处理
|
||
|
||
- 新文件中扫描常见密码片段和 `PGPASSWORD`，确认没有凭据泄漏。
|
||
- 不读取或修改被 `.gitignore` 排除的本地数据库配置。
|
||
- 不连接生产数据库验证迁移，因为本任务只迁移文档和工作约束。
|
||
- 不删除 `.claude`，迁移失败时现有 Claude 工作流不受影响。
|
||
- 不执行 release skill；仅验证其结构与引用路径。
|
||
|
||
## 验证
|
||
|
||
完成迁移后执行：
|
||
|
||
1. 检查 `AGENTS.md`、`.agents/skills/release/SKILL.md` 和 `.codex/memory/*.md` 均存在。
|
||
2. 检查 `AGENTS.md` 中的索引链接均能解析到实际文件。
|
||
3. 搜索新文件中的密码、`PGPASSWORD`、Claude session ID 和临时 scratchpad 路径。
|
||
4. 对照原 memory 索引，确认所有仍有效主题均已覆盖。
|
||
5. 检查 Git diff，确认 `.claude` 没有变化，且没有混入用户现有未跟踪文件。
|
||
|
||
## 完成标准
|
||
|
||
- Codex 项目级入口、按需发版 skill 和 memory 索引全部建立。
|
||
- 原 Claude 配置保持不变。
|
||
- 原有 9 个 memory 主题均被迁移或被更高层规则覆盖。
|
||
- 新配置不含明文凭据或 Claude 专属运行痕迹。
|
||
- 验证命令通过，Git diff 只包含本次迁移相关文件。
|