Antigravity 到 Codex 迁移上手指南
面向已经习惯 Antigravity 的软件工程师，这份文档的目标很直接：让你在最短时间内建立 Codex 的正确心智模型，形成稳定的高频工作流，并能独立完成日常开发、排障、重构、验证和文档沉淀。

这不是产品说明书，也不是功能罗列。你可以把它理解成一份“工作方式迁移指南”：

在 Antigravity 里你通常怎么想、怎么发任务
到 Codex 里应该怎么改写任务、怎么控制执行边界
哪些旧习惯继续有效，哪些必须主动调整

1. 一句话结论
   Codex 更像一个工程执行代理，不只是帮你补代码，而是帮你读仓库、改文件、跑验证、沉淀文档。
   Antigravity 更偏向 agent-first 和多代理编排，Codex 更强调主代理在明确边界内完成闭环。
   在 Codex 中，探索、计划、执行、验证、沉淀 是需要显式提出的阶段，不建议默认混在一起。
   迁移初期最常见的坑，不是“不会用命令”，而是仍然按 Antigravity 的编排预期来使用 Codex。
   给 Codex 下任务时，模糊目标的效果会明显差于“可验证目标 + 约束 + 验收标准”。
   你不能默认它会自动替你完成所有后续动作，尤其是审批、破坏性操作、联网安装、服务启动这类高风险步骤。
   真正高效的用法不是让它“写更多”，而是让它“先探索清楚，再小步实现，再主动验证”。
2. 心智模型迁移
   这一节最重要。如果心智模型不切换，你会觉得 Codex 不如 Antigravity 顺手；一旦切换过来，反而会发现它在工程闭环和可控执行上更稳定。

2.1 从 agent-first 编排，转到工程执行代理
在 Antigravity 中，你更容易形成这样的习惯：

把复杂任务丢给系统
默认期待它自行拆解子任务
允许多个代理在后台并行推进
你更多扮演编排者和审阅者
在 Codex 中，更推荐的思路是：

先明确目标、边界、约束和成功标准
让主代理先探索仓库和环境
再进入实现、验证、文档沉淀的闭环
你是“技术负责人 + 授权者”，不是纯粹的旁观审阅者
一句话概括：

Antigravity 更像“任务编排中心”
Codex 更像“受控的工程执行代理”
2.2 从“默认会编排完成”，转到“显式声明阶段”
在 Codex 里，下面这五个阶段最好显式出现：

探索：只读分析，不改仓库
计划：先锁定目标、边界、方案和验收标准
执行：实际改代码、跑命令、做验证
验证：构建、测试、日志、端口、接口回归
沉淀：更新 README、设计文档、workflow 文档
一个典型的 Antigravity 用户迁移错误，是直接说：

帮我把这个问题处理掉

在 Codex 里，更好的写法是：

先探索当前仓库中和该问题相关的模块，给出根因分析；确认方案后直接修改代码，并在完成后执行构建/测试和更新相关 Markdown 文档。

2.3 从“能力边界模糊”，转到“执行边界清晰”
Codex 的强项之一，是对 sandbox、approval、文件修改、命令执行、联网等边界有明确约束。你要把这看作优势，而不是束缚。

为什么这很重要：

复杂工程里最危险的不是“写不出代码”，而是“在不完整上下文里做了错误操作”
可控的审批和授权机制，更适合真实项目协作和生产工程
你可以更清楚地知道：它做了什么、没做什么、为什么停下来
迁移建议：

不要把 Codex 当“无限权限的全自动代理”
要把它当“高执行力、但边界明确的工程搭档”
3. 工作流对照表
场景 在 Antigravity 中的典型使用方式 在 Codex 中的推荐做法 迁移时要主动改变的习惯 一句话实践建议
新需求实现 直接下发较宽泛目标，期待后台自动拆解并推进 明确“需求、边界、验收标准、是否直接改代码”，让它先探索再落地 不要只给抽象目标 先讲清“做成什么样算完成”
Bug 排查 倾向让系统并行探索多个方向 先让它只读排查，给出根因与受影响范围，再决定是否修复 不要一上来就改文件 先锁定根因，再做修改
大范围重构 倾向多代理并行处理子模块 先要求整体方案和风险分析，再分阶段重构并逐步验证 不要默认一次性重构到底 先分层拆解，再逐层落地
接口联调 让系统同时看前后端并联动验证 明确接口契约、错误码、数据流和验证步骤，必要时要求检查端口和日志 不要只盯代码，不盯运行态 联调必须把日志和接口返回一起纳入验收
构建/测试失败定位 期待系统自动吸收上下文并回收结果 让它先读取报错、分析根因、定位改动点，再修复并复测 不要只贴一句“构建失败了” 把报错文本、命令和预期结果一起给出
文档生成 让代理基于上下文自动生成 artifacts 明确文档受众、用途、结构和是否需要模板/示例 不要只说“写文档” 文档先定读者，再定深度
代码 Review 期待系统主动找出主要问题并汇总 明确要求以 review 视角输出，优先列 findings、风险、缺失测试 不要把 review 写成改进建议杂谈 review 先讲问题，再讲总结
迁移时最值得牢记的 5 条操作建议
Antigravity 里能用宽目标驱动的任务，到 Codex 里尽量补上验收标准。
Antigravity 里常见的并行思路，到 Codex 里优先转成“探索 -> 方案 -> 执行”的显式阶段。
不要默认“生成代码 = 完成任务”，要把 验证 和 沉淀 一起写进任务。
对高风险改动，先要求 Diff 驱动分析，再实施。
涉及服务、端口、日志、数据库、网络的任务，必须把运行态验证写进要求里。
4. Codex 核心使用技能
这一节讲的是高频实战技能，不是功能列表。

4.1 如何提任务：从宽目标改成可验证目标
不推荐：

帮我优化一下这个模块

推荐：

请先分析这个模块的性能瓶颈，重点关注数据库查询、接口调用频率和前端渲染；在不改变对外行为的前提下完成优化，并在修改后执行构建/测试，说明 Diff 原因和影响范围。

推荐提示词模板：

请以资深技术专家身份响应。
先探索当前仓库中与该任务相关的代码和配置，再给出简要分析。
目标：

• [明确目标]
  约束：
• [不能改什么]
• [必须遵循什么]
  验收标准：
• [可验证结果]
  完成后请：
• 修改代码
• 执行必要验证
• 说明 Diff 原因与受影响范围
• 更新相关 Markdown 文档
  4.2 如何让 Codex 先探索再修改
  适用场景：

你不熟悉该仓库
涉及多个模块
问题根因不明
改动可能引起连锁影响
推荐提示词模板：

先不要改代码。
请先探索当前仓库中与 [问题/需求] 相关的模块、入口、配置和数据流，
输出：

1. 当前实现路径
2. 根因或缺口
3. 推荐修改点
4. 风险与受影响范围
   确认后再进入实现。
   4.3 如何要求它做 Diff 驱动分析
   适用场景：

重构
性能优化
安全修复
接口行为变更
推荐提示词模板：

请以 Diff 驱动方式分析并实施修改：

1. 先说明为什么要改
2. 再说明改动影响哪些模块、接口、数据结构或行为
3. 修改后列出验证结果
4. 如果有 workaround，请明确标注局限性与长期建议
   4.4 如何要求它同时做实现、验证、文档沉淀
   这是 Codex 相对普通聊天工具的关键优势之一。不要只让它“写代码”，要让它完成工程闭环。

推荐提示词模板：

请直接落地实现，不停留在分析阶段。
要求：

• 修改代码时保持与现有代码风格一致
• 完成后主动执行构建、测试或关键验证
• 检查端口、日志或接口返回是否符合预期
• 补充或更新相关 Markdown 文档
• 最终按“问题分析 / 方案设计 / 代码实现 / 验证结果”输出
  4.5 什么情况下停在方案阶段，什么情况下直接执行
  适合先停在方案阶段：

需求不清晰
有多个架构选型分支
涉及大范围重构
涉及迁移、兼容性、数据变更
适合直接执行：

目标明确
改动边界清楚
验收标准明确
风险可控
推荐提示词模板：

如果存在高影响不确定项，请先给方案，不要直接改代码。
如果仓库上下文已经足够明确，请直接执行并完成验证。
4.6 如何让它按资深工程师方式输出
推荐提示词模板：

请以资深技术专家身份响应，中文优先。
要求你同时具备：

• 架构视角
• 实战编码能力
• 健壮性、性能、安全意识
  请按以下结构输出：

1. 问题分析
2. 方案设计
3. 代码实现
4. 验证结果
5. 风险与后续建议
6. 常见开发场景模板
   这一节给的是可直接复制的 prompt 模板。你不需要每次都从零组织语言。

模板 1：新功能开发
适用场景：

新增页面
新增接口
新增业务功能
推荐输入模板：

请基于当前仓库直接实现一个新功能。
先探索相关模块，再完成实现。

需求：

• [功能描述]

约束：

• 保持现有代码风格和分层
• 不破坏现有接口行为
• 关注错误处理、资源释放和边界情况

验收标准：

• [可验证标准]

完成后：

• 运行必要的构建/测试
• 说明关键 Diff 和影响范围
• 更新相关 Markdown 文档
  期望输出：

根因/现状说明
实施后的代码修改
验证结果
文档更新说明
常见补充约束：

指定技术栈
指定页面设计稿尺寸
指定数据库字段或接口格式
模板 2：排查线上问题
适用场景：

接口报错
服务启动失败
数据异常
推荐输入模板：

请先排查问题，不要立刻大改代码。

问题现象：

• [现象描述]

已知信息：

• [日志/报错/接口返回]

要求：

• 先定位根因和影响范围
• 再给出修复方案
• 如果上下文足够明确，直接修复并验证
• 说明是否存在临时 workaround 以及长期优化建议
  期望输出：

根因分析
修复方案
验证结果
常见补充约束：

限制改动范围
需要保留向后兼容
需要检查端口、日志、数据库
模板 3：接口设计与实现
适用场景：

新增 REST API
数据聚合接口
后台管理接口
推荐输入模板：

请基于当前仓库实现一个接口，并从系统设计高度分析。

接口目标：

• [接口用途]

要求：

• 明确请求参数、响应结构、错误处理
• 关注并发、幂等、性能和安全
• 如涉及数据库，请说明索引建议
• 实现后完成接口验证
  期望输出：

接口设计说明
关键代码
验证方式
常见补充约束：

指定分页
指定鉴权方式
指定是否需要兼容旧接口
模板 4：前端页面性能优化
适用场景：

页面卡顿
首屏过慢
轮询过多
推荐输入模板：

请先分析当前前端页面的性能瓶颈，再进行优化。

重点关注：

• API 调用频率
• 组件渲染次数
• 图表或列表更新方式
• 打包体积

要求：

• 不改变用户可见行为
• 修改后执行构建验证
• 说明优化前后的关键差异
  期望输出：

性能瓶颈定位
优化修改
构建或运行验证结果
常见补充约束：

Vue 中说明 v-if / v-show 取舍
图表组件注意销毁和重建
必须做分包或懒加载分析
模板 5：安全审计与修复
适用场景：

接口安全审计
密钥泄露风险
输入校验不足
推荐输入模板：

请以安全审计视角检查当前模块，并在必要时直接修复。

重点关注：

• SQL 注入
• 配置密钥明文
• 输入校验
• 权限绕过
• 危险命令或文件操作

要求：

• 先列出风险点及严重级别
• 再实施修复
• 修复后说明是否有兼容性影响
  期望输出：

风险清单
修复方案
验证结果
常见补充约束：

不允许引入重型依赖
需保持接口兼容
模板 6：代码 Review
适用场景：

合并前检查
功能回归
重构后复审
推荐输入模板：

请对当前改动做 code review。
要求：

• 以 finding 为主，按严重程度排序
• 优先指出 bug、回归风险、遗漏测试和设计问题
• 给出文件位置和具体原因
• 如果没有明显问题，也请说明剩余风险和测试缺口
  期望输出：

findings 列表
开放问题
简短总结
常见补充约束：

指定 review 某个目录
指定 review 某次 diff
模板 7：生成文档 / workflow
适用场景：

编写 README
团队工作流说明
API 联调文档
推荐输入模板：

请基于当前项目生成一份文档。

受众：

• [谁看]

用途：

• [解决什么问题]

要求：

• 中文优先，保留必要英文术语
• 结构清晰，强调可执行性
• 结合当前仓库实际实现，不写成通用模板
• 如有必要，补充示例、命令和注意事项
  期望输出：

可直接落地的 Markdown 文档
常见补充约束：

指定写入 docs 目录
指定是否需要迁移对照表
6. Codex 使用边界与风险
这是 Antigravity 用户特别需要适应的一节。Codex 很强，但不是“默认全自动”的黑盒。

6.1 何时需要审批 / 授权
通常涉及以下情况时，要预期存在 approval 或执行限制：

需要联网安装依赖
需要访问沙箱外目录
需要运行高权限命令
需要启动外部服务或 GUI 程序
需要执行潜在破坏性操作，例如删除、重置、覆盖
正确心态不是：

为什么它不直接做完
而是：

很好，它在高风险动作前停下来等我确认
6.2 为什么要先探索仓库再修改
如果跳过探索，常见后果是：

改错模块
风格不一致
漏掉上游/下游依赖
修了一个点，破坏另一个点
尤其在以下任务里，必须先探索：

多模块需求
老项目排障
架构级变更
数据库和接口联动改动
6.3 为什么不要在不确定上下文里直接做破坏性操作
高风险动作包括：

批量删除文件
覆盖已有改动
强制重置 Git 状态
直接迁移数据库而不确认上下文
正确做法：

先探索
再分析
再说明影响范围
最后小步执行并验证
6.4 如何避免“只生成代码，不做验证”
这是迁移期最容易出现的问题之一。你习惯了让工具快速产出，但工程里真正需要的是闭环。

默认建议你在任务中显式写入：

修改后运行构建或测试
如涉及服务，检查端口和日志
如涉及接口，做接口回归验证
如涉及文档，补充 Markdown 沉淀
6.5 如何避免“聊天式问答”替代“工程闭环”
不推荐：

先问一堆概念，再让它给一段示意代码，最后自己收尾
推荐：

明确让它探索真实仓库
直接落地改动
主动验证
最终输出受影响范围和后续建议
Do / Don’t
Do Don’t
明确写出目标、约束、验收标准 只说“帮我优化一下”
先探索再修改 不看上下文直接改
把验证写进任务 只要求生成代码
对重大改动要求 Diff 驱动分析 直接做大范围重构却不说明影响
对高风险操作接受 approval 流程 把受控执行误解成能力不足
7. Antigravity 用户的迁移误区
误区 1：以为 Codex 会默认像 Antigravity 一样主动编排全部子任务
表现：

给一个宽泛目标，期待它自动拆解、自动推进、自动闭环
根因：

把 agent-first 编排体验直接投射到 Codex
正确做法：

主动声明阶段：先探索、再执行、最后验证和沉淀
误区 2：以为 Codex 更适合纯 GUI 式探索
表现：

希望像 IDE 编排环境那样自然在多视图、多面板中漫游
根因：

忽略了 Codex 更偏终端和工程执行工作流
正确做法：

把重点放在仓库探索、命令执行、文件修改和验证闭环上
误区 3：以为 prompt 越短越好
表现：

任务输入极短，省略目标、边界、约束和验收标准
根因：

误把“自然语言足够智能”理解成“不需要提供工程上下文”
正确做法：

对复杂任务给足背景、约束和成功标准
误区 4：以为只要生成代码就算完成
表现：

只关注代码片段，不关心构建、测试、日志和文档
根因：

把 AI 当成代码生成器，而不是工程代理
正确做法：

明确要求它完成实现、验证和沉淀
误区 5：以为计划和执行不需要明确切换
表现：

一会儿想先要方案，一会儿又期待它立即改代码
根因：

没把“计划”和“执行”当作不同模式
正确做法：

在任务里明确：现在是只做方案，还是直接实施
8. 7 天迁移练习路径
这部分不是考试大纲，而是一套最短迁移训练路线。目标是让你在 7 天内形成 Codex 的稳定肌肉记忆。

第 1 天：仓库探索和问答
训练目标：

习惯让 Codex 先探索上下文
推荐任务：

让它梳理项目目录
让它说明入口文件、数据流、关键模块
让它回答“这个功能现在是怎么实现的”
成功标准：

你能通过它快速建立对仓库结构的整体理解
第 2 天：小修小补 + 验证
训练目标：

建立“小改动也要验证”的习惯
推荐任务：

修一个文案问题
改一个接口字段
修一个明显 bug
成功标准：

每次改动后都要求它执行构建、测试或必要验证
第 3 天：接口开发
训练目标：

练习从需求到实现再到接口验证的完整链路
推荐任务：

新增一个查询接口
增加一个统计字段
增加错误处理
成功标准：

你能稳定要求它说明参数、返回、错误处理和验证结果
第 4 天：前后端联调
训练目标：

习惯把运行态纳入任务要求
推荐任务：

新增前端展示字段
打通一个后台接口到页面
检查端口、日志和接口返回
成功标准：

你不再只盯代码，而是同时关注运行效果
第 5 天：性能 / 安全专项
训练目标：

让 Codex 参与更高阶的工程分析
推荐任务：

做一次页面性能优化
做一次接口安全检查
做一次 SQL / 索引优化建议
成功标准：

你能要求它从架构、性能和安全多个维度给出结果
第 6 天：Review 与文档沉淀
训练目标：

把“修改完成”升级为“可审查、可传承”
推荐任务：

对一次改动做 review
让它补 README
生成一份联调说明或工作流文档
成功标准：

你开始习惯要求它输出 findings、风险和文档说明
第 7 天：完整任务闭环
训练目标：

形成一套稳定的 Codex 使用习惯
推荐任务：

从一个真实需求开始
让它先探索
再实施
再验证
最后沉淀文档
成功标准：

你能完整驱动一次“需求 -> 方案 -> 实现 -> 验证 -> 文档”的闭环，而不是停留在代码生成层
9. 一套完整闭环示例
如果你只记住一套用法，记住下面这套。

请以资深技术专家身份响应，中文优先。

先探索当前仓库中与 [任务名称] 相关的模块、配置和数据流，不要立刻修改代码。
输出：

1. 当前实现方式
2. 存在的问题或缺口
3. 推荐修改方案
4. 风险与受影响范围

如果上下文已经足够明确，请继续直接实施，要求：

• 保持与现有代码库风格一致
• 关注错误处理、性能和安全
• 对重大改动做 Diff 驱动分析
• 修改后主动执行构建、测试或必要验证
• 检查端口、日志、接口返回等关键运行态
• 更新相关 README 或 Markdown 工作流文档

最终请按以下结构输出：

1. 问题分析

2. 方案设计

3. 代码实现

4. 验证结果

5. 风险与后续建议
   这套模板的意义在于，它把 Antigravity 用户常依赖的“后台自动推进”，转化成了 Codex 更擅长的“显式闭环工程执行”。

6. 最后给 Antigravity 用户的迁移建议
   如果你已经熟悉 Antigravity，说明你并不缺“AI 协作意识”，你真正要迁移的是工作方式：

从“交给系统编排”，转为“明确目标和边界后驱动执行”
从“默认它会自动闭环”，转为“显式要求探索、验证和沉淀”
从“只关注产出代码”，转为“关注工程结果是否可运行、可验证、可交付”
一旦完成这一步，你会发现 Codex 的价值不只是写代码，而是让你以更可控、更工程化的方式推进真实开发工作。