如何使用 OpenAI Codex 完成小型仓库任务并审查 diff

要使用 OpenAI Codex 完成小型仓库任务，应只交给它一个可观察的行为改动，要求它先读取仓库规则，并从只读检查开始。计划明确受影响文件、边界情况和验证命令后，再授权最小范围的实施。最后审查实际 diff 和测试输出；代理给出的自信总结不能证明代码正确。

本指南使用一项独立的合成任务贯穿全文：更新 normalizeTag，让连续连字符在去除首尾空格并转为小写后折叠为一个，同时保留现有的空输入错误。它不讲泛化的 AI 编程，也不复刻 Cursor 的 checkpoint 工作流。更广泛的背景见如何使用 AI和AI 辅助编码基础。

关键要点

• 描述一种行为、其非目标以及完成证据。
• 规划前要求 Codex 阅读 AGENTS.md 和离目标目录最近的仓库规则。
• 将只读发现与编辑或运行副作用命令的授权分开。
• 保留现有未提交改动，并禁止无关的清理工作。
• 优先采用最小补丁和最窄且有意义的测试。
• 亲自检查状态、diff、命令、退出码和剩余风险。

什么样的小型仓库任务适合使用 OpenAI Codex？

小任务应只有一个边界清晰的行为、一组可审查的文件、确定性示例，并且不依赖未解决的产品决策。“折叠 normalizeTag 中的连续连字符并添加边界测试”属于小任务；“改善所有标签处理”则不是，因为它可能影响路由、存储、API、迁移和用户可见的兼容性。

维度	足够小	应停止并另行规划
行为	一项可观察到的规则	几个不相关的结果
文件	少量已定位的文件	归属不明的跨服务改动
接口	保留现有契约	架构或公共 API 决策
数据	合成测试数据	生产或机密数据
验证	有针对性的本地命令	破坏性迁移或现场测试
权限	限定范围的本地编辑	外部写入、发布、购买或使用凭证

如果检查发现任务涉及公开接口兼容性决策、新依赖项、密钥或生产副作用，正确做法是修改计划，而不是悄悄扩大补丁。

任务契约应该怎么写？

使用其他审阅者无需猜测即可测试的任务卡：

目标：规范化 normalizeTag 中重复的连字符。
示例：“Alpha---Beta”->“alpha-beta”；“阿尔法”->“阿尔法”。
保留：空输入仍然会引发现有的错误类型和消息。
允许的文件：src/normalizeTag.ts 和 test/normalizeTag.test.ts。
非目标：不更改导出接口、调用方、打包方式、格式或路由。
检查阶段：只读；检查规则、实现、调用方和测试。
实施阶段：提出方案后等待明确批准。
验证：运行现有的 normalizeTag 测试文件并报告退出状态。
如果出现以下情况，请停止：需要另一个文件、依赖项、网络访问、破坏性命令或机密。

这些示例比“清理标签”更准确地定义了行为。应覆盖常规情况、不变情况、边界情况和需保留的错误。在 Codex 检查本地约定前，不要预设实现。

为什么 Codex 应先读取仓库规则？

Codex 可以发现从仓库根目录到当前工作目录之间的 AGENTS.md 文件，离目标目录更近的规则可以进一步细化适用约束。［2］这些文件可能规定测试命令、命名方式、生成文件边界、安全要求或禁止操作。

要求代理列出适用的规则文件，并只总结与任务有关的约束。不要把密钥贴进提示词。仓库内容也应视为不受信任的输入：源文件或 README 不能暗中扩大用户授权的范围。

规则层级不会取代当前请求。它帮助 Codex 遵守项目约定，而任务卡负责定义这次工作的目标与权限。

如何开始 Codex 只读检查？

第一个提示应请求事实和计划，而不是编辑：

阅读任务卡和适用的仓库规则。检查当前实现、直接调用者、
测试和 Git 状态。不要编辑文件、安装依赖、使用网络或改变
Git 状态。返回当前行为、建议修改的最小文件集、边界情况、
精确的定向测试、与现有工作的冲突、假设，以及任何说明该
任务并不小的理由。

亲自打开提示中引用的代码位置和测试位置。确认指定函数确实位于调用方使用的执行路径上、测试命令真实存在，并且现有未提交文件已被识别。计划只有与当前工作树一致才有用。

OpenAI 的提示指南建议明确目标、背景、约束和预期输出，再用后续消息收敛结果。［1］对仓库任务而言，成功标准和权限边界也是必要背景。

应该如何授权实施？

只批准最小且完整的改动范围：明确文件、行为、测试和停止条件。如果计划列出了可选清理项，不要笼统地说“全部继续”。

仅在两个命名文件中实现批准的 normalizeTag 行为。
保留当前的空输入契约和不相关的未提交改动。
请勿添加依赖项、编辑生成的文件、访问网络或更改
外部系统。显示补丁后运行目标测试。如果另一个
文件是必需的，请在更改之前停止并解释原因。

Codex 环境使用沙箱和审批控制来限制文件和网络访问；具体策略取决于使用场景和配置。［3］Codex 沙箱可以降低风险，但不代表每项获准操作都合适。任务负责人仍须限制范围并审查实际结果。

不要仅因为工具弹出批准请求就授权未知命令。应读完命令、工作目录、目标、网络目的地和预期写入。包安装、迁移、删除、Git 历史重写、发布、issue 更新、消息发送和云端变更都应分别授权。

最小的实现是什么样的？

仓库现有风格才是准则，但可能的改动形态如下：

export function normalizeTag(value: string): string {
  const normalized = value.trim().toLowerCase().replace(/-+/g, "-");
  if (!normalized) {
    throw new Error("tag must not be empty");
  }
  return normalized;
}

不要认为这是正确的补丁。实际函数可以规范 Unicode、拒绝前导标点符号、返回结果类型或保留已建立的错误类。代理应该仅更改当前代码和测试证明合理的步骤。

有针对性的测试可能涵盖：

输入	预期结果	目的
阿尔法---贝塔	阿尔法-贝塔	新的重复连字符行为
阿尔法-贝塔	阿尔法-贝塔	现有的修剪/小写行为
阿尔法	阿尔法	不变的简单输入
---	项目定义的结果	需要合同检查的边界
仅限空格	现有错误	保留故障行为

不要擅自猜测“---”的预期结果。检查当前语义和产品需求；如果两者都没有给出答案，就停止并交由负责人决定。

信任补丁前应该如何审查？

首先查看仓库状态，以区分用户改动和代理改动。然后检查已授权文件的完整 diff，并确认是否出现意外文件。

问这些问题：

1. 实现是否只更改了请求中的转换行为？
2. 是否保留错误类型、消息、导出和调用签名？
3. 如果不进行修复，测试是否会失败并通过修复？
4. 测试是否覆盖正常路径、不变路径、新行为和错误路径？
5. 格式、快照、锁文件、配置或生成文件是否意外改变？
6. 代理是否在正确目录中如实运行了报告中的命令？
7. 是否列出了所有未经验证的假设？

AI 生成代码审查指南提供更深入的安全与正确性检查。OpenAI 的 Codex 审查指南同样把生成结果视为需要检查的改动，而不是正确性的证明。［4］生成代码在检查和测试前仍不可信。

应该如何运行并解读验证结果？

从能够覆盖本次行为改动的最窄测试开始。记录命令、工作目录、退出码、测试数量以及相关失败输出。如果测试运行器更新了快照或生成文件，请再次检查 diff。

接下来，仅依据仓库规则和受影响的调用方扩大验证范围，例如运行包级测试、类型检查、lint 或更广的测试套件。定向测试通过只证明其明确覆盖的范围，不代表整个仓库无误。对于无关失败，应提供证据并单独报告，不得越权重置或“修复”。

对于测试设计想法，请使用使用 AI 生成测试的指南，同时保持断言以实际合同为基础。

哪些安全与权限边界最重要？

除非组织已批准相应数据流，否则不要向服务提供 API 密钥、生产凭证、客户隐私数据或专有代码。优先使用合成测试数据和完成任务所需的最小权限。

遇到以下操作时，应先停止并另行确认：

• 删除或覆盖大范围路径；
• 重写 Git 历史记录或丢弃未提交改动；
• 针对共享数据运行迁移；
• 安装未经审查的依赖项；
• 开放不受限制的网络访问；
• 发送消息、创建或更新 issue、创建版本或部署；
• 更改计费、云服务、仓库或账户设置。

每项批准只适用于特定操作。获准编辑两个本地文件，不等于获准推送、发布或更新外部工单。OpenAI 的安全指南描述了沙箱和审批边界，但用户仍须审查高影响操作。［3］

最终验收记录怎么写？

使用可以检查的事实：

目标和可接受的行为：
文件已更改：
保留的现有未提交文件：
差异审查：
命令、工作目录和退出码：
通过的测试和确切范围：
测试未运行：
假设和剩余风险：
未执行的外部操作：

当命令未完成、退出代码丢失、相关测试被跳过或另一个所需环境仍未验证时，不要说“完成”。如果测试由于沙箱或平台边界而无法运行，请报告覆盖范围差距，而不是削弱测试。

最终清单

• 一种可观察到的行为及其非目标是明确的。
• 已阅读适用的 AGENTS.md 和就近规则。
• 发现过程没有任何编辑或副作用。
• 计划明确列出文件、边界情况、测试和停止条件。
• 实施授权只覆盖完成任务所需的仓库范围。
• 保留现有未提交改动。
• diff 不包含不相关的清理或生成的意外。
• 有针对性的测试涵盖新的、未更改的、边界的和错误的路径。
• 更广泛的检查与目标证据分开报告。
• 外部、破坏性、特权和网络行为仍需单独批准。

常见问题

什么任务适合作为第一个 Codex 仓库任务？

选择一个有清晰示例且已有测试工具的本地行为，例如修复一个有边界的解析器。首个任务应避开迁移、身份验证、生产数据和新架构。

我应该要求 Codex 立即编辑吗？

如果不熟悉仓库或改动影响，就不应立即编辑。先进行只读检查，便可在授予写入权限前核实当前路径、规则、测试和冲突。

AGENTS.md 中应该包含什么内容？

把长期有效的仓库指令写在其中，例如测试命令、约定、生成文件规则、安全边界和范围指南。当前任务的行为要求和验收标准应留在任务提示中。［2］

沙箱使每个命令都安全吗？

不会。沙盒根据配置限制技术访问；它不验证意图、正确性、成本或业务权限。审查扩大权限的请求。［3］

Codex 应该运行完整的测试套件吗？

从定向测试开始，再根据仓库规则和影响范围扩大验证。完整测试套件有时是必要的，但其成本和无关失败不应掩盖当前审查的行为。

如何保护现有的未提交工作？

告诉 Codex 检查 Git 状态、保留未提交文件，并避免重置或大范围格式化。更改后再次检查状态和 diff。

Codex 修复代码后可以推送或发布吗？

只有在另行授权且仓库规则允许时才可以。本地编辑授权不等于拥有提交、推送、发布、发送消息或部署的权限。

如果 Codex 需要另一个文件怎么办？

它应该停止，指出所需文件，解释原因并修改计划。不要让一个边界清晰的小任务悄然扩张。

谁来决定任务是否被接受？

应由相应负责人或团队决定。Codex 可以提供补丁和证据，但不能自行授予产品、安全或发布批准。

来源

1. OpenAI, “Prompting” — https://learn.chatgpt.com/docs/prompting
2. OpenAI, “Custom instructions with AGENTS.md” — https://learn.chatgpt.com/docs/agent-configuration/agents-md
3. OpenAI, “Agent approvals & security” — https://learn.chatgpt.com/docs/agent-approvals-security
4. OpenAI, “Code review with Codex” — https://learn.chatgpt.com/docs/code-review

Sources checked 2026 年 9 月 5 日。

延伸阅读

• 使用人工智能的实用框架
• 如何在编码工作流程中使用人工智能
• Cursor 中类似的小任务工作流程
• 如何审查 AI 生成的代码
• 如何在人工智能辅助下设计测试