代码生成结束不等于任务完成。补丁可能通过编译，却在错误处理、并发、权限或兼容性上留下回归；也可能修复了症状，却没有覆盖真正的根因。让 Codex 在交付前承担一次独立审查，可以显著提高发现问题的概率，但前提是审查范围明确、发现有证据、修复后重新验证。 先固定审查基线 Codex 的 /review 可以针对不同差异工作：与基础分支比较适合模拟 Pull Request 审查；审查未提交改动适合提交前检查；指定提交适合确认一个独立变更；自定义说明则用于聚焦安全、边界条件或性能。 选择范围时，先回答“这次准备交付的变化到底是什么”。如果工作区混有实验文件，直接审查全部未提交内容会制造噪声；如果功能分散在多个提交，只看最后一个提交又会丢失上下文。开始前查看 Git 状态和差异基线，确保代理看到的内容与评审者将收到的内容一致。 /review Focus on regressions, error handling, authorization boundaries, and missing tests. Ignore formatting unless it changes behavior. 好的聚焦说明描述风险，而不是预设结论。不要要求“找出至少五个问题”，这种指标会鼓励低价值发现。也不要把格式化规则交给模型反复评论；能够由 lint 或格式化工具稳定执行的规则，应该交给自动化检查。 要求可行动的发现 一条有效发现应包含位置、触发条件、实际影响和判断依据。严重程度应反映用户或系统风险，而不是措辞强度。阻断数据写入、绕过权限或导致崩溃的问题优先级高；只影响极端日志格式的建议不应与它们并列。 收到发现后不要立即批量接受。先让 Codex 展示相关调用路径、构造最小复现，或者指出违反了哪项现有约束。对于依赖框架行为的判断，应查看项目锁定的版本和官方资料。证据不足的猜测可以保留为待确认风险，但不应该包装成已经证实的缺陷。 团队反复强调的领域规则可以写进最接近代码的 AGENTS.md，例如支付流程不得基于请求中的展示金额结算。规则要说明应阻止的行为，同时给出安全路径或例外。Codex Code Review 是额外评审者，不替代分支保护、必需审批和测试门禁。 从发现走到验证 审查闭环可以固定为五步： 复现：在修改前证明问题存在，记录输入、环境和失败结果； 修复：只处理已确认问题，避免借机重写无关代码； 回归测试：优先添加一个修改前失败、修改后通过的针对性测试； 扩大检查：运行相关测试后，再执行仓库要求的 lint、类型检查和构建； 复审：重新运行 /review，确认原发现消失且补丁没有引入新风险。 并非每个问题都能自动化测试，例如只在特定外部系统发生的故障。这时应提供最强的可重复验证手段，如最小脚本、日志对比、截图或人工步骤，并明确记录证据缺口。不能验证和已经验证是两种完全不同的交付状态。 测试范围应与改动风险匹配。纯函数修复通常从单元测试开始；跨模块契约要覆盖调用双方；数据库迁移需要前向、回滚和旧数据场景；界面变化还要检查交互、窄屏和无障碍状态。只运行最容易通过的测试，并不能证明真实行为正确。 让人工评审关注真正的取舍 自动审查最适合扫描遗漏、追踪调用路径和执行重复检查。人仍然需要判断需求是否正确、风险是否值得、界面是否符合预期，以及一次改动是否应该现在发布。让 Codex 在提交前整理变更摘要、验证命令和剩余风险，可以把人工注意力从机械核对移到这些取舍上。 合并前的最终记录应该足够具体：审查的是哪个分支或提交，接受并修复了哪些发现，哪些发现被判定为误报，运行了哪些命令，以及是否仍有未覆盖场景。这样的记录既方便 Pull Request 评审，也为后续回归提供可追踪依据。 交付清单 审查范围与准备提交的差异一致； 高优先级发现有明确位置、影响和复现证据； 修复包含针对性回归测试，或明确记录无法测试的原因； 仓库规定的检查全部运行并报告结果； 修复后完成复审，最终仍由人决定是否合并。 上一篇：从模糊需求到可验证补丁 ...
Codex 实战（二）：从模糊需求到可验证补丁
“优化一下这个页面”或者“修复登录问题”足以开启讨论，却不足以定义一次可靠的工程交付。Codex 可以主动探索仓库，但它无法从代码中推断产品取舍、风险偏好和真正的验收标准。高质量提示词的作用不是规定每一行实现，而是给代理一个清晰的问题边界，以及证明任务已经完成的方法。 用四个部分定义任务 一个稳定的起点是 Goal、Context、Constraints 和 Done when 四段式结构： Goal 描述要改变的用户行为或系统结果，而不是指定某个函数必须怎样改； Context 指向相关目录、错误信息、复现步骤、设计稿或已有实现； Constraints 固定不能破坏的接口、依赖、安全边界和改动范围； Done when 列出测试、构建、页面行为或性能指标等可验证结果。 例如，要求 Codex 给 Hugo 博客增加文章，可以这样写： Goal: 新增三篇可直接发布的中文文章，并让它们出现在首页和分类页。 Context: 站点配置在 hugo.toml，文章放在 content/posts，public 已被 Git 跟踪。 Constraints: 不要修改 PaperMod 子模块；沿用 TOML Front Matter；保留现有改动。 Done when: hugo --minify 成功，文章页、RSS、标签页和站点地图都包含新 URL。 这份提示没有替 Codex 决定具体模板实现，却明确了探索范围和交付证据。代理仍可以从仓库中发现真实结构，而不是被一份可能过时的文件清单绑住。 复杂任务先规划 当需求涉及多个模块、存在兼容风险，或者验收标准尚不清楚时，先进入规划阶段。支持的 Codex 界面可以使用 /plan；也可以直接要求它先阅读仓库、提出问题并给出实施方案，在确认前不要编辑文件。 规划的核心不是生成一份很长的待办清单，而是消除会改变实现方向的未知项。目录位置、依赖版本和现有测试属于可发现事实，应先从仓库查证；发布策略、兼容范围和产品优先级属于偏好，才需要向人提问。一份可执行计划还应说明数据如何流动、失败时如何表现、哪些接口保持不变，以及每个风险如何验证。 小而明确的改动则不必为了形式强行规划。修正文案、调整单个配置值等任务，在边界和验证都清楚时可以直接执行。判断依据是错误决策的代价，而不是文件数量。 让执行过程保持可审查 开始实现后，可以要求 Codex 遵循一个简单闭环： 读取入口、相邻实现、测试和工作区状态，确认没有覆盖他人改动； 先复现问题或建立基线，再选择最小的行为改动； 按仓库现有模式实现，并补充与风险相称的测试； 运行最小相关检查，再扩大到构建、类型检查或集成测试； 审阅最终差异，报告命令、结果和仍未覆盖的风险。 这里的“最小”不是追求最少行数，而是避免顺手重构无关模块。上下文不足时，代理应该继续查找；只有无法从环境得到、且答案会实质改变方案的问题，才需要暂停询问。 权限同样属于任务设计。Codex 在沙箱内运行本地命令，越过文件或网络边界时会遵循审批策略。不要为了省一次确认就授予整台机器的宽泛权限。更好的做法是保持工作区干净，给出准确命令，并只批准当前任务确实需要的能力。 ...
Codex 实战（一）：用 AGENTS.md 建立可靠的仓库上下文
把 Codex 放进一个真实仓库后，最先遇到的问题通常不是模型不会写代码，而是它不知道团队如何写代码。入口在哪里、哪些目录是生成产物、测试应该跑哪一组、什么操作必须先确认，这些信息如果只存在于成员记忆里，代理就只能边猜边做。AGENTS.md 的价值，是把这类长期有效的协作约定变成仓库的一部分。 上下文不是越多越好 一次性任务中的目标和验收条件应该留在提示词里；跨任务稳定存在的规则才适合进入 AGENTS.md。如果把产品需求、临时排期和大段架构历史全部塞进去，关键约束反而容易被噪声淹没。 一个实用的判断标准是：下个月换一项任务，这条说明是否仍然成立？如果答案是肯定的，它可能属于仓库指南；如果只服务当前需求，就应该留在当前会话。凭据、内部地址和个人数据则不应该进入任何会被提交的指令文件。 理解指令的作用域 Codex 会在开始工作前查找 AGENTS.md。全局目录可以保存个人通用偏好，仓库根目录承载团队级约定，子目录则可以覆盖局部规则。代理从项目根目录向当前工作目录逐层组合指令，离目标文件更近的说明优先级更高。同一目录存在 AGENTS.override.md 时，它用于替代该层的普通指南。 这种分层适合大型仓库。例如根文件要求所有改动通过格式化和安全检查，services/payments/AGENTS.md 再补充支付服务的集成测试命令。局部文件只描述差异，不必复制根文件全文。这样既减少重复，也避免两份规则长期漂移。 写入真正能执行的信息 一份有效的仓库指南至少回答四类问题： 代码、测试、配置和生成文件分别放在哪里； 如何安装依赖、启动项目、构建并运行最小相关测试； 命名、格式、模块边界和兼容性有哪些硬约束； 完成任务前必须检查什么，以及哪些动作不能擅自执行。 以这个 Hugo 博客为例，最有用的信息不是“保持高质量”，而是下面这种可以直接采取行动的说明： - 文章源文件放在 `content/`，生成站点位于 `public/`。 - PaperMod 位于 Git 子模块中；优先使用 `layouts/` 做本地覆盖。 - 本地预览运行 `hugo server -D`，提交前运行 `hugo --minify`。 - 检查生成的 `public/`，不要提交无关构建变化。 反过来，“写出优雅代码”“测试要充分”这类口号缺少判定方式。把它们改成具体命令、可观察结果或明确禁止项，Codex 才能据此决定下一步。 还要区分指令与工具配置。AGENTS.md 说明团队希望工作怎样完成；模型、沙箱、审批策略和外部工具连接等运行设置属于 .codex/config.toml；需要反复执行且包含固定步骤的专项流程，更适合封装成 skill。把不同职责拆开，能让指南保持短小，也避免修改写作规则时意外改变运行权限。 把指南当成可维护的工程资产 不要试图第一次就覆盖全部边界。先记录最常用的目录、命令和完成标准，然后观察代理反复出现的错误：是否选错测试范围，是否修改了生成文件，是否忽略兼容要求。只有当问题确实重复时，再加入一条短而明确的规则。 修改指南后，应在新的 Codex 会话中验证，因为指令链通常在一次运行开始时加载。可以让 Codex 概括当前生效的说明，再给它一个小任务，检查它是否选择了正确目录和验证命令。对于子目录规则，还要分别从仓库根目录和目标子目录验证，确保覆盖关系符合预期。 最后保留人工检查：指南是否仍与真实脚本一致，是否引用了已经删除的命令，是否把建议误写成强制规则。过期但语气坚定的文档，比没有文档更危险。 实践清单 从仓库结构、构建命令、测试入口和禁止操作开始； 用可执行命令与可观察结果代替抽象口号； 根目录写共享规则，子目录只补充局部差异； 不保存秘密，也不混入一次性需求； 用真实任务验证，并根据重复失误持续精简更新。 下一篇：从模糊需求到可验证补丁 参考资料 Codex Best practices Custom instructions with AGENTS.md