dbs-agent-migration：Agent 工作台迁移

一句话定义

dbs-agent-migration

• Claude Code → Codex

• Codex → Claude Code

• Claude + Codex 双端统一

• 混乱项目 → 标准 Agent 工作台

• 商业诊断本身
• 知识库内容优化
• 单个 skill 方法论质量评审
• 业务文案创作

什么时候用

• 想把 Claude Code 项目迁到 Codex
• 想把 Codex 项目补回 Claude Code
• 想同时兼容 Claude Code 和 Codex
• 觉得自己的 Agent 工作台很乱，想统一整理
• 想把 Claude 和 Codex 两边统一起来
• 问

  CLAUDE.md

  、

  AGENTS.md

  、skill bridge、真源怎么设计
• 本地 skill 很乱，散落在各处，不知道怎么收编
• 已经复制过

  CLAUDE.md

  、已经建过一些 bridge，但不确定是否做完整了

核心原则

原则 1：迁移不是复制文件，也不是单向搬家

CLAUDE.md

AGENTS.md

1. 项目级规则文件
2. skill 真源位置
3. bridge 命名规则
4. Claude / Codex 双端一致
5. 可持续维护

• Claude Code → Codex
• Codex → Claude Code
• 双端统一

原则 2：真源优先，bridge 从真源生成

• skills/

  是理想真源目录

• ~/.claude/skills/

  和

  ~/.codex/skills/

  都只是 bridge
• 不要把长期逻辑维护在 bridge 里

原则 3：不能假设项目已经规范

1. 已有

   CLAUDE.md

   +

   AGENTS.md

   +

   skills/

2. 只有

   CLAUDE.md

3. 只有

   AGENTS.md

4. skill 散落在项目各处，根本没有

   skills/

1. 只有 Claude 侧
2. 只有 Codex 侧
3. 两边都有，但不一致

原则 4：多步确认是产品的一部分

• 你刚刚看到了什么
• 你帮他判断了什么
• 你下一步准备改什么
• 为什么要这样改

工作流程

Phase 1：迁移审计

• CLAUDE.md

• AGENTS.md

• SOURCE_OF_TRUTH.md

• 项目中是否存在

  skills/

• 项目中是否存在散落的 skill 候选
• 是否已有

  ~/.claude/skills

  /

  ~/.codex/skills

  bridge
• 当前主工作台更偏 Claude 还是 Codex

• A 类：双文件双桥接，可能只是半迁移
• B 类：有

  CLAUDE.md

  ，缺

  AGENTS.md

• C 类：有

  AGENTS.md

  ，缺 Claude 兼容层
• D 类：没有规范，skill 散落

• 当前是 Claude 主、Codex 缺
• 当前是 Codex 主、Claude 缺
• 当前是 双端都有，但不一致
• 当前是 两端都不成体系

Phase 1 输出格式

1. 你现在属于哪一类
2. 已经做对了什么
3. 真正缺的是什么
4. 我建议先动哪一层

我已经完成第一轮审计。接下来我准备处理 {下一阶段}，继续吗？

Phase 2：规则文件迁移

CLAUDE.md

• 拆出平台无关规则 → 写入

  AGENTS.md

• 保留 Claude 专属规则在

  CLAUDE.md

• 删除过时、重复、宿主绑定太强的内容

CLAUDE.md

• 直接根据项目类型创建最小可用

  AGENTS.md

• 如果用户需要补回 Claude 兼容层，再创建一个薄的

  CLAUDE.md

AGENTS.md

• 以

  AGENTS.md

  为主规则
• 拆出 Claude 专属兼容层
• 只补必要的

  CLAUDE.md

SOURCE_OF_TRUTH.md

• 明确告诉用户：不是硬门槛，但强烈建议建立
• 用户同意再补

Phase 2 写入前确认

• 这次要新建还是改写哪个文件
• 会保留什么
• 会删除什么
• 为什么这样分层

Phase 3：识别或建立 skill 真源

情况 A：已有

skills/

• 把

  skills/

  定为真源
• 排除历史版本、备份、示例、成品文档

情况 B：没有

skills/

1. 扫描类似

   SKILL.md

   、

   *skill*.md

   、带明确触发方式和执行步骤的文件
2. 排除文章、备份、测试案例、导出稿
3. 生成“候选真源清单”
4. 告诉用户哪些建议收编、哪些不建议
5. 用户确认后，再新建项目级

   skills/

• 不要硬建

  skills/

• 明确告诉用户：现在只是“有 prompt 资产”，还没形成 skill 系统

Phase 3 确认要求

• 哪些文件会被认定为真源
• 哪些不会
• 为什么

Phase 4：统一命名与 frontmatter

• 顶层 frontmatter

• name

• description

• bridge 规范名

1. 优先沿用用户已经长期使用的历史名字
2. 再决定 Claude / Codex 两边统一名
3. 最后回写真源 frontmatter

Phase 5：生成 Claude / Codex bridge

• tools/sync-claude-skills.js

• tools/sync-codex-skills.js

• 稳定映射表，例如

  tools/skill-bridge-map.md

• 只做入口，不维护长逻辑
• 指向项目真源
• Claude / Codex 使用同一套规范名
• 能从任一侧重新生成另一侧，不依赖单向历史

Phase 5 写入前确认

• 会生成哪些 bridge
• 会覆盖哪些旧 bridge
• 是否会清理旧目录

Phase 6：验证

1. AGENTS.md

   是否可独立工作
2. 真源是否明确
3. frontmatter 是否补齐
4. bridge 是否能指回真源
5. Claude / Codex 两边的项目 bridge 集合是否一致
6. 是否存在悬空引用

Phase 6 输出

• 真源是否完成
• 规则层是否完成
• Claude bridge 是否完成
• Codex bridge 是否完成
• 双端集合是否一致

禁止事项

• 不要把复制

  CLAUDE.md

  当成完整迁移
• 不要假设用户一定有

  skills/

• 不要把所有散落文档一股脑认定为 skill
• 不要在没确认时直接移动一堆文件
• 不要让 bridge 命名随脚本临场发挥
• 不要在 bridge 中维护长期逻辑

推荐收尾话术

1. 现在这个项目属于“可运行迁移”还是“完整迁移”
2. 已经补了哪些结构层
3. 后面还有什么可选优化
4. 如果别人照着做，最小步骤是什么