我把 OpenAI 官方三篇 Codex 指南读完了，整理成这一篇

一、写清楚你要什么#

Codex 不需要完美的提示词也能给出不错的结果，但如果你交代清楚，结果会更稳——尤其是大型项目或重要任务。

一个好的提示词包含四件事：

推理强度怎么选？

• 低：任务简单、范围清晰时
• 中 / 高：逻辑复杂、需要调试时
• 超高：长流程、多步骤、高推理量的任务

二、复杂任务先规划，再动手#

任务模糊、步骤多的时候，先让 Codex 规划，比直接让它写代码效果好很多。（就像你接了个需求直接开干，和先拉着 PM 对齐一遍，结果能差出一个返工来）

三种方式：

方式一：Plan 模式（最推荐）

用 /plan 命令或 Shift + Tab 切换到 Plan 模式。Codex 会先收集上下文、问几个关键问题，再开始实现，而不是直接动手乱改。

方式二：让 Codex 先问你问题

如果你自己思路还不清晰，直接告诉它：

“先问我问题，把我的想法梳理清楚，再开始写代码。”

它会帮你把模糊的想法变成具体的实现方向。

方式三：PLANS.md 执行计划（进阶）

对于超长流程任务，可以配合 PLANS.md 执行计划模板，让 Codex 跑几个小时的连续任务。

三、用 AGENTS.md 存下你的规则#

每次都在提示词里重复同样的要求很麻烦。AGENTS.md 就是解决这个问题的——把你的规范写进去，Codex 每次启动都会自动读取。

把这些内容写进 AGENTS.md：

• 项目结构和重要目录说明
• 怎么运行项目
• 构建、测试、Lint 命令
• 代码规范和 PR 要求
• 哪些地方不能改、不能碰
• 什么算”做完了”，怎么验收

快速创建： 在 CLI 里运行 /init，它会自动帮你生成一个起始版本，你再按实际情况修改。

文件放在哪里：

1
~/.codex/AGENTS.md        # 个人全局默认设置
2
~/.claude/AGENTS.md       # 同上 全局默认配置
3
项目根目录/AGENTS.md      # 团队共享规范
4
子目录/AGENTS.md          # 只针对这个模块的特殊规则
5
                          # （越靠近当前目录的规则优先级越高）

我的习惯是每个项目有单独的 AGENTS.md 下面仅供参考，有重复操作或流程时让AI自己总结写进去即可

三条实用建议：

• 宁可短而准，也不要长而空。一份简洁准确的 AGENTS.md 比洋洋洒洒的大文件有用得多
• Codex 犯了同样的错误两次？让它做个复盘，然后把结论加进 AGENTS.md
• 内容越来越多时，可以把详细内容拆成独立的 code_review.md、architecture.md 等文件，在主文件里引用

四、做完不算完，让它验证自己的工作#

让 Codex 改完代码之后，顺手让它跑测试、检查规范、确认结果。这一步很多人会跳过，但跳过的代价往往是”改好了一个地方，悄悄坏掉了另一个地方”。

可以要求它做的事：

• 给这次改动写或更新测试
• 跑相关测试套件
• 检查 Lint、格式化、类型检查
• 确认实际行为和需求一致
• Review diff，找潜在 bug 和回归风险

用 /review 命令来做代码审查：对比 base 分支做 PR 式审查、审查未提交的改动、审查某个 commit、自定义审查指令。

💡 如果你有 code_review.md 文件，在 AGENTS.md 里引用它，Codex 就会用里面的标准来做审查——对团队来说非常实用，保证每次审查风格一致。

五、用 MCP 接入外部信息#

有时候 Codex 需要的信息不在代码库里，比如数据库里的数据、Jira 里的任务、实时日志。这时候用 MCP 接入外部系统，比每次手动粘贴信息省事多了。

什么时候用 MCP？

• 需要的信息在代码库之外
• 数据会频繁变化
• 想让 Codex 直接调用某个工具，而不是靠你粘贴信息

建议： 不要一口气接入所有工具。先从一两个能真正减少手动步骤的工具开始，稳定之后再扩展。（贪多嚼不烂，这条对 MCP 尤其成立）

六、把重复的工作变成 Skill#

同一类工作反复做、每次都要写很长的提示词？把它封装成一个 Skill，下次直接调用就好。

Skill 适合做什么：

• 日志归因分析
• 起草发布说明
• 按 checklist 做 PR 审查
• 制定迁移计划
• 标准化的 Debug 流程

规则很简单：同样的提示词反复用超过两三次，就该变成 Skill 了。

顺带一提，我自己也刚做了一个配图决策的 Skill，上一篇文章有完整的实操记录，感兴趣可以去看看。

七、稳定的流程可以设置自动化#

当某个工作流已经稳定可靠之后，可以设置定时自动运行。

自动化适合做什么：

• 定期总结最近的 commit
• 扫描代码中的潜在 bug
• 起草版本更新说明
• 生成每日站会摘要

⚠️ 流程还不稳定就别急着自动化——先把它做成 Skill，反复跑通之后再设定自动化计划。自动化一个不稳定的流程，等于把问题变成了定时炸弹。

八、新手最容易踩的坑#

三个核心概念#

Skills（技能）：可重复调用的操作手册

Skill 是一个文件包 + 一个 SKILL.md 说明文件。你可以把它想象成版本化的操作手册——需要做某件事的时候，Codex 就翻出来按照手册执行。

每个 Skill 暴露给 Codex 的信息是：名称、描述、路径。Codex 根据这些来决定要不要调用它，调用的时候才会读完整的 SKILL.md。

Shell 工具：给 Codex 一个真实的终端

Shell 工具让 Codex 在真实的终端环境里干活：

• OpenAI 托管的容器：通过 Responses API 运行，有状态、支持多轮连续操作，可以安装依赖、跑脚本、生成输出文件
• 本地 Shell：你自己控制机器，工具语义一样，迭代快、调试方便

上下文压缩：防止长任务被”撑死”

任务跑得越长，上下文窗口越容易撑满。两种处理方式：

• 自动压缩：上下文超过阈值时在流式输出中自动触发，什么都不用做
• 手动压缩：调用 /responses/compact 端点，自己控制压缩时机

为什么要一起用？

1
Skills  → 把稳定的流程和模板从提示词里移走，需要的时候再加载
2
Shell   → 提供完整的执行环境，真正能跑代码、生成文件
3
压缩    → 保证长流程不会因为上下文撑满而中断
4

5
三者结合 = 可重复执行的真实工作流，而不是脆弱的巨型提示词

十条实用技巧#

1. Skill 的描述要回答三个问题

Skill 的 description 是 Codex 决定要不要调用它的依据，写得好坏直接影响触发准确率。描述里要回答：

• 什么时候该用这个 Skill？
• 什么时候不该用？
• 这个 Skill 的输入、输出和成功标准是什么？

建议在描述里加一个短小的「用 vs. 不用」对比块，写得越具体越好。

2. 加上反面例子，减少误触发

有个反直觉的现象：把 Skill 加进来之后，一开始准确率可能会下降。原因是模型不确定什么时候该用，于是乱触发或者不触发。

修复方式：在描述里加上明确的「不要在 X 情况下调用这个 Skill（应该用 Y 替代）」的案例。

Glean 的实测数据：加入 Skill 路由后，触发率最初下降了约 20%，加上反面例子和边缘情况覆盖后完全恢复。

3. 模板和示例放进 Skill，不要堆在系统提示词里

把报告模板、格式示例放进 Skill 而不是系统提示词，好处有两个：

• 按需加载：只有 Skill 被调用时才占用上下文
• 质量更好：模板在需要的时候清清楚楚地呈现给模型

特别适合有固定输出格式的场景：结构化报告、数据解析报告、升级摘要……

Glean 反馈：这种模式带来了他们生产环境中最大的质量提升和延迟改善。

4. 一开始就规划好容器复用和压缩

长期任务很少能靠一次提示跑完。从设计阶段就要考虑连续性：

• 跨步骤复用同一个容器，保持依赖、缓存文件和中间输出的稳定
• 传入 previous_response_id，让模型在同一线程里继续工作
• 把压缩当成默认选项，而不是撑不住了才用的应急手段

5. 需要确定性时，直接告诉模型用哪个 Skill

默认情况下 Codex 自己决定调不调用 Skill，这通常够用。但如果你在跑一个有明确要求的生产流程，直接说：

“使用 <skill 名称> 技能。”

这是最简单的可靠性手段——把模糊的路由变成明确的指令。

6. Skill + 网络访问 = 高风险，要谨慎设计

这是容易忽视、但后面很难补救的安全点。Skill 加上开放网络访问，是数据泄露的高风险组合。

推荐的默认姿态：

1
Skills：允许
2
Shell：允许
3
网络：默认不开，需要时只开白名单里精确的域名

使用了网络的工具输出要视为不可信数据，不要直接拿来执行。

7. 用 /mnt/data 作为输出文件的统一存放点

在托管 Shell 里，把所有输出文件（报告、清洗后的数据、电子表格）统一写到 /mnt/data。

好的工作模式：工具写磁盘 → 模型在磁盘上推理 → 开发者从磁盘取结果。

这样有清晰的交接边界，输出可以被检索、审查，或传给下一步流程。

8. 网络白名单是两层结构

1
组织级白名单（管理员配置）：设定最大允许的目标域名集合
2
请求级 network_policy：必须是组织白名单的子集

实操建议：组织白名单保持小而稳定，只放你真正信任的域名；请求白名单更小，只放这个任务实际需要的域名。

9. 用 domain_secrets 传认证信息，别把密钥暴露给模型

如果需要调用需要鉴权的 API，用 domain_secrets——模型只会看到占位符（比如 $API_KEY），真实的值只在请求到达批准的目标域名时才被注入。

10. 本地开发 + 云端部署，Skills 保持不变

1
本地 Shell 模式  → 自己执行 shell_call，迭代快、调试方便
2
托管容器         → 需要可重复性、隔离和部署一致性时切换
3

4
推荐流程：本地跑 → 快速迭代 → 稳定后迁移到托管容器
5
Skills 在两种模式下保持一致——工作流不变，只是执行环境换了

三种组合模式#

模式 A：安装依赖 → 拉取数据 → 生成文件

最简单的 Shell 用法：安装几个库、调接口或抓数据、把报告写到 /mnt/data/report.md。这是”真实工作代理”的基础，输出结果清晰，可以展示给用户、存日志，或传给下一步。

模式 B：Skills + Shell 实现可重复工作流

跑几次 Shell 工作流之后会发现：提示词一飘，可靠性就下降。这时候引入 Skills：把步骤、规则、模板写进 Skill，让 Codex 按照 Skill 执行，稳定产出。特别适合：表格分析、数据清洗 + 摘要生成、定期业务报告。

模式 C（进阶）：Skills 作为企业工作流载体

当你需要多工具协作时，Skills 可以让工具调用逻辑变得程序化，而不需要把所有东西塞进系统提示词。

Glean 的实测数据：一个面向 Salesforce 的 Skill 把评估准确率从 73% 提升到 85%，首 token 响应时间缩短了 18.1%。

Skills 最终会变成组织的活的操作手册（SOP）：随业务演进而更新，由代理稳定执行。

1. 规划阶段#

过去的痛点： 评估功能可行性、拆解工作范围，需要工程师深入翻代码库，还要跟各方开多轮对齐会议。

Codex 能做什么：

• 读取功能规格，跟代码库交叉比对，自动标出模糊点和依赖关系
• 把工作拆成子任务，估算难度
• 追踪某个功能涉及哪些服务——以前这个工作可能要花几小时手动挖代码，现在几秒出结果

工程师做什么： 代理负责初步的可行性分析；团队负责审核结果的准确性、评估风险、做最终的优先级和方向决策。

起步清单：

• 找出哪些流程需要把功能描述和代码库对齐（比如功能范围确认、工单拆解）
• 先从简单的工作流开始，比如自动标记重复需求
• 进阶：让代理在工单进入某个阶段时自动补充更多细节

2. 设计阶段#

过去的痛点： 原型搭建慢，设计稿和实现之间总有落差，需要多轮返工。

Codex 能做什么：

• 接受自然语言描述，直接生成符合团队规范的组件骨架或原型代码
• 把设计稿转成代码，提出可访问性改进建议
• 分析代码库中的用户流程和边缘情况

原来几天才能出的原型，现在几小时就能迭代多版。设计师可以把更多时间放在评估用户体验上，而不是等实现落地。

工程师做什么： 代理负责初始实现和模板搭建；团队负责审核组件质量、无障碍标准、系统集成；架构决策和整体用户体验方向仍由人来掌舵。

起步清单：

• 使用支持图片输入的多模态编码代理（可以直接丢设计稿进去）
• 通过 MCP 把设计工具和编码代理打通
• 用 TypeScript 等有类型的语言来约束代理生成的组件属性

3. 构建阶段#

过去的痛点： 这是工程师最累的阶段——把规格变成代码、跨文件复制模式、填写模板代码，哪怕一个小功能也可能要好几个小时的体力活。

Codex 能做什么：

• 根据书面规格，一次性生成从数据模型、API、UI 组件到测试和文档的完整功能
• 在几十个文件里搜索和修改代码，保持一致性
• 遇到构建错误时自动修复，不需要暂停等人
• 生成符合内部规范的 PR，附带 commit message

Cloudwalk 案例：工程师、PM、设计师每天都在用 Codex 把规格变成可运行的代码——一个脚本、一条新的风控规则、或者一整个微服务，几分钟搞定。

工程师做什么： 代理负责第一遍实现；工程师转变为审查者、编辑者和方向把控者——专注于架构合理性、业务逻辑正确性、性能关键路径，以及那些真正需要深度判断的部分。

起步清单：

• 从描述清晰的任务开始
• 让代理通过 MCP 或 PLAN.md 先做规划，再动手
• 检查代理执行的命令是否都在正常跑通
• 持续迭代 AGENTS.md，把”跑测试”、“跑 Lint”这类反馈循环配置好

4. 测试阶段#

过去的痛点： 写测试耗时、上下文切换频繁，赶 deadline 时测试覆盖率往往是第一个被牺牲的。

Codex 能做什么：

• 读需求文档和功能代码，自动建议测试用例——包括开发者容易忽略的边缘情况
• 随着代码演进自动更新测试，减少脆弱测试的积累

工程师做什么： 测试不是能被代理完全替代的——恰恰相反，随着代理能跑测试并根据结果迭代，写好测试变得比以前更重要。定义高质量测试，往往是让代理成功构建功能的第一步。工程师更多关注测试覆盖的整体模式，审查代理是否走了捷径（比如写了空实现或假断言）。

起步清单：

• 让代理在单独的会话里生成测试，先确认新测试会失败，再做功能实现（TDD 流程）
• 在 AGENTS.md 里写明测试覆盖要求
• 给代理提供代码覆盖率工具，让它知道覆盖率现状

5. 代码审查阶段#

过去的痛点： 平均每周花 2-5 小时做代码审查。时间压力下，很多 PR 只是走个过场，导致 bug 溜进生产。

Codex 能做什么：

• 给每个 PR 提供一致的基础审查，不会因为时间紧就偷懒
• 不只是静态规则匹配——可以执行代码、追踪跨文件的逻辑，发现真正的问题

Sansan 案例：用 Codex 审查竞态条件和数据库关联关系（这类问题人工很容易漏掉），还能发现不当的硬编码，甚至预见到未来的扩展性问题。在 OpenAI 内部，Codex 审查了 100% 的 PR，让工程师在提交给同事前就能发现并修掉问题。

工程师做什么： 工程师委托代理做第一遍审查；自己的审查重心转向架构对齐、可组合性、功能是否符合需求——最终 merge 的责任还是在人。

起步清单：

• 整理一批高质量 PR（包含代码和 review 评论）作为评估基准
• 选专门针对代码审查训练过的模型，通用模型信噪比太低
• 定义审查质量的衡量指标，推荐用”评论是否被采纳”来低摩擦地打标

6. 文档阶段#

过去的痛点： 文档欠债严重，追平成本高；关键知识存在个人脑子里；文档写完就开始过时。

Codex 能做什么：

• 读代码库，自动生成功能说明、模块概述、系统架构图（支持 Mermaid 语法）
• 在构建功能时顺手更新文档，而不是事后专门补
• 接入发布流程，自动总结这次发版包含哪些关键变更

在 AGENTS.md 里加上”需要时更新文档”的指令，文档维护就变成了每次代理运行的标配。

工程师做什么： 工程师从”亲手写每一篇文档”变成”设计文档体系、审查关键文档、把控质量标准”。低风险的内容（模块概述、输入输出说明、PR 摘要）可以全部交给代理；核心服务、公开 API、Runbook 等文档由工程师审核后再发布。

起步清单：

• 先直接提示代理生成文档，看看质量如何
• 把文档规范加进 AGENTS.md
• 识别哪些工作流（比如发版周期）可以自动触发文档生成

7. 部署与运维阶段#

过去的痛点： 发生故障时，工程师需要在日志工具、代码、部署记录之间来回切换，手动关联信息，既耗时又容易出错。

Codex 能做什么：

通过 MCP 把日志工具和代码库都接入代理，工程师只需一个提示词：“帮我看看这个接口最近的报错”——代理会：

1. 查看日志
2. 在代码库里追踪相关代码
3. 翻 git 历史，找出可能引入问题的变更

Virgin Atlantic 案例：通过 VS Code 插件 + Azure DevOps MCP + Databricks MCP，工程师在 IDE 里就能完成日志分析、跨代码追踪、变更审查，大幅缩短了故障定位时间。

工程师做什么： 代理负责日志解析、异常指标上报、可疑变更识别，甚至生成初步修复方案；工程师负责验证诊断结果、确认修复方案符合可靠性和安全要求；高风险的生产变更，最终决策仍由人来做。

起步清单：

• 通过 MCP 把日志和部署系统接入 Codex
• 设置访问权限范围，确保代理能读日志和代码历史，但保持安全边界
• 建几个常用的提示词模板，比如”分析 X 接口的报错”、“排查部署后的日志异常”
• 用模拟故障场景测试工作流，再推到真实场景