很多团队第一次把 Codex 引入开发流程时，关注的是“它能不能更快写代码”。真正进入企业项目后，问题很快会变成另一组：
- Codex 是否理解这个仓库的真实边界？
- 需求变更后，哪些行为必须保持不变？
- 代码改完以后，谁来判断它真的完成了？
- 测试没跑、权限没审、回滚没准备，能不能发布？
- 换一个会话或换一个工程师后，工作能不能继续？
这些问题不能靠一条越来越长的 Prompt 解决。更稳定的做法，是把项目事实、任务契约、质量门禁和交付记录固化到仓库中，让 Codex 每次都从同一组可审查的材料开始工作。
本文以一套 Codex 企业级工作流模板为例，整理一条从需求到发布的实践路径。模板中的文件名可以按团队习惯调整，但它们承担的职责最好保持清晰、互不重叠。
一、企业工作流的核心不是 Prompt，而是交付协议
一次性 Prompt 通常只能解决当前对话中的问题。它很容易遗漏项目背景、隐含约束和验证标准，也无法在会话中断后自动恢复。
一个可持续的 Codex 工作流至少要固定四件事：
- 上下文：项目是什么，代码在哪里，哪些文档是事实来源；
- 授权：当前任务允许改什么，不允许碰什么，哪些操作必须再次确认；
- 验收：什么条件满足后才算完成，用什么命令或证据证明；
- 交付：如何测试、审查、发布、观察和回滚。
可以把它理解成一份写给人和 AI 共同遵守的工程协议：
1 | 项目事实 |
OpenAI 的官方模型指导也强调类似方向：先描述目标、成功标准、约束和可用证据，再给模型选择执行路径的空间；长流程需要保留已完成动作、假设、工具结果、阻塞项和下一步，而不是只保留一段模糊的“继续做”。
二、先解决文档职责：一个事实只有一个主文档
模板最重要的设计，是给每份文档规定唯一职责。这样可以避免同一个配置、接口或决策被复制到多个地方，最后出现“文档互相矛盾”的情况。
| 文件 | 只负责什么 | 什么时候更新 |
|---|---|---|
AGENTS.md |
仓库级长期规则、读取顺序、命令、授权和完成标准 | 工程规则变化时 |
AI_CONTEXT.md |
项目当前快照、文档索引、活动任务和已知风险 | 里程碑或上下文变化后 |
PROJECT.md |
稳定的目标、边界、技术栈和环境 | 项目级事实变化时 |
PRD.md |
用户问题、产品需求、范围和验收标准 | 需求评审或需求变更时 |
TASK.md |
当前唯一活动任务的执行契约 | 每次任务开始、变更和完成时 |
PLANS.md |
跨模块或高风险任务的阶段计划 | 计划执行中持续更新 |
ARCHITECTURE.md |
组件边界、数据流、接口和非功能设计 | 架构发生实质变化时 |
TESTING.md |
测试命令、测试数据和质量门槛 | 测试体系变化时 |
SECURITY.md |
数据分类、权限、密钥、输入和发布安全 | 安全边界变化时 |
RUNBOOK.md |
部署、观察、告警、事故和回滚 | 运维流程变化时 |
DECISIONS.md / docs/adr/ |
不可逆或跨团队决策 | 作出重要决策时 |
TODO.md |
尚未进入执行范围的工作 | 发现或调整待办时 |
CHANGELOG.md |
已交付的用户和运维可感知变化 | 发布时 |
这里有三个容易被忽略的规则：
AI_CONTEXT.md只做摘要和导航，不复制完整 PRD、架构或测试文档；- 未知内容写成
TBD，推测内容标记为ASSUMPTION，不要悄悄删除或伪装成事实； - 发现范围外问题时进入
TODO.md，不要顺手扩大当前任务。
文档越多不一定越好。真正重要的是每份文档都短、可读，并且知道什么时候该读、谁负责更新。
三、AGENTS.md：规定 Codex 如何工作
AGENTS.md 适合放长期有效的仓库规则，不适合放某一次需求的细节。它应该回答：Codex 开始工作前读什么、可以做什么、如何验证、完成后必须留下什么。
一个精简的结构可以是：
1 | # AGENTS.md |
如果一个仓库包含多个独立模块，还可以在子目录放更具体的 AGENTS.md，让模块规则覆盖通用规则。规则应尽量写成真正的不变量；对于“什么时候搜索”“是否需要拆计划”这类判断，不要全部写成无条件的 ALWAYS 或 NEVER。
四、TASK.md：把一句话需求变成执行契约
“加一个审计日志”“优化接口性能”“修复线上问题”都不是足够清晰的任务。Codex 需要知道目标、边界、验收方式和回滚路径。
TASK.md 可以固定以下内容：
1. 目标
用一句话描述可观察的结果，而不是描述实现动作。
1 | 目标：管理员可以查看最近 30 天的登录审计记录，并能按用户和时间筛选。 |
2. 范围和禁止改变项
明确包含什么、不包含什么，以及哪些已有行为必须保持稳定：
1 | 包含：审计事件模型、写入逻辑、查询接口、后台列表和测试。 |
3. 验收标准
尽量写成 Given / When / Then，避免“功能正常”“体验良好”这类无法验证的描述：
1 | - [ ] 给定管理员已登录，打开审计页面时能看到最近 30 天记录。 |
4. 影响、约束和风险
任务还应该列出涉及的模块、数据迁移、兼容性、性能、安全、依赖和回滚策略。这样 Codex 在实施前就知道哪些地方不能凭经验猜测。
任务完成后，TASK.md 还要记录实际修改、验证命令、未运行的检查、剩余风险和关键文件。它不是一张静态需求单，而是一次交付的证据索引。
五、复杂任务才使用 PLANS.md
小任务不必为了“看起来专业”而创建长计划。涉及多个模块、数据迁移、生产风险或无法在一次短会话内完成时，再使用 PLANS.md。
一个可恢复的计划至少包含：
- 目标结果和不变量；
- 相关文件、入口和依赖；
- 按里程碑拆分的动作和可演示结果；
- 每个里程碑的验证命令和检查点；
Progress：已经完成什么；Discoveries：发现了什么，证据在哪里；Decision Log：为什么选择这个方案；- 回滚和恢复方式。
计划不要写成“完善功能”“处理异常”这种空泛步骤。更好的写法是：
1 | Milestone 1：确认现有登录事件链 |
每个里程碑都应该能独立回答“做了什么”和“如何证明做对了”。这样即使会话中断，下一次也能从最后一个检查点继续，而不是重新猜测进度。
六、推荐的 Codex 日常工作流
模板把不同阶段拆成独立 Prompt，但真正重要的是阶段之间的交接关系：
1 | 需求或问题 |
1. 启动：先读，再动手
建议的读取顺序是：
1 | AGENTS.md |
如果文档和代码冲突，不要静默选一个。先指出冲突，再用可运行代码和测试描述当前事实，用已批准的 PRD 或 ADR 描述目标状态。
2. 调查：确认入口、调用链和验证路径
在修改前检查工作区、相关入口、数据模型、接口、测试和部署配置。调查的结果应该进入任务或计划，而不是只存在于当前对话里。
3. 实施：保持最小、可审查
沿用项目已有的命名、错误处理、日志和测试模式。不要因为发现一个无关的旧问题，就顺便重构整个模块或升级依赖。
4. 验证：先跑最小相关检查
修改纯函数，先跑对应单元测试和类型检查；修改 API，增加契约、授权和集成测试；修改数据模型，验证迁移、旧数据、并发和回滚；修改 AI Prompt 或模型逻辑，使用固定评测集比较质量、成本、延迟和安全指标。
5. 审查：把 diff 当作交付物检查
审查不只看代码风格，还要检查验收标准、权限绕过、敏感信息、输入边界、错误路径、兼容性、测试有效性和范围外改动。没有发现问题时，也要明确写出仍未覆盖的验证盲区。
6. 收尾：同步文档，再交付
根据变化类型更新对应主文档：需求变更更新 PRD，架构变化记录 ADR，测试门槛变化同步 TESTING，发布和回滚变化同步 RUNBOOK，已交付行为进入 CHANGELOG，当前任务状态写回 TASK 和 AI_CONTEXT。
七、把测试、安全和发布变成门禁
测试门禁
TESTING.md 不只是列几个命令，还应该说明核心用户路径、不可接受的失败、测试数据规则和 CI 门槛：
- 格式、Lint、类型检查和最小相关测试通过；
- 跨模块变更运行集成测试，用户流程变更运行 E2E；
- 缺陷先建立失败复现，再加入回归测试；
- 默认使用合成或脱敏数据，不能把生产凭据复制到测试夹具；
- Flaky test 不能靠重复执行掩盖，必须记录根因或获得隔离审批；
- 无法运行的测试要写明阻塞原因、替代验证和残余风险。
安全门禁
SECURITY.md 应该明确数据分类、认证授权、外部输入、文件处理、密钥、依赖、日志和漏洞响应。至少要检查：
- 没有把真实密钥、令牌、个人数据写入代码、日志、截图和测试；
- 外部输入在信任边界处验证，数据库访问使用参数化方式；
- 权限有正向测试，也有反向测试；
- 依赖和镜像扫描没有未批准的高危问题；
- 审计日志经过脱敏，并明确保留与访问策略。
发布门禁
RUNBOOK.md 要让另一个值班工程师能够按文档完成发布和回滚。它至少包含：
1 | 发布前检查 |
生产发布不是“命令执行成功”就结束。还要验证关键用户路径、错误率、延迟、数据一致性和告警状态，并为高风险步骤写清负责人、观察信号和停止条件。
八、阶段 Prompt 是启动器，不是第二套文档
模板提供了 prompts/00 到 prompts/08，它们分别对应：
| 阶段 | Prompt | 用途 |
|---|---|---|
| 初始化 | 00-project-bootstrap.md |
读取仓库并建立项目上下文 |
| 需求 | 01-requirement-to-prd.md |
把模糊需求整理成可评审 PRD |
| 计划 | 02-task-planning.md |
调查现状并生成 TASK/PLANS |
| 实现 | 03-implementation.md |
按任务契约实施、验证和收尾 |
| 调试 | 04-debugging.md |
复现、定位根因并做最小修复 |
| 审查 | 05-code-review.md |
只读审查工作区、提交或 PR |
| 发布 | 06-release.md |
准备发布清单和回滚方案 |
| 交接 | 07-handover.md |
中断或换线程时保存可继续状态 |
| 刷新 | 08-context-refresh.md |
对齐文档、代码和配置现状 |
每次只选择最接近当前目标的一份，不要把九份 Prompt 全部拼成一个超级 Prompt。Prompt 负责触发阶段动作，稳定事实仍然应该回到项目文档中。
如果某种流程长期重复、输入输出稳定，可以把它升级成 Codex Skill；不要继续把一次性 Prompt 越写越长。
九、上下文中断时，如何快速恢复
AI_CONTEXT.md 的价值不在于保存所有历史，而在于让下一次启动快速定位：项目当前阶段是什么、活动任务是哪一个、当前分支是什么、已经完成到哪里、有什么阻塞、下一检查点是什么。
一次交接应该留下：
- 目标和当前状态；
- 已修改的关键文件；
- 最后一次成功的验证命令和结果；
- 失败或未执行的验证；
- 已确认的假设和重要决策；
- 外部操作产生的 ID 或链接；
- 下一条可以直接执行的命令；
- 需要谁批准的权限或决策。
当文档可能已经落后于代码时，使用上下文刷新流程：只读检查仓库结构、依赖、入口、测试、CI、迁移和部署配置，列出“文档说法 vs 代码证据”的冲突，只更新能够被证据确认的内容。
十、不要一开始就把所有模板复制进仓库
企业级不等于文档数量多。建议分三步落地：
第一阶段：最小可用
先加入 AGENTS.md、AI_CONTEXT.md、PROJECT.md、TASK.md 和 TESTING.md。先把读取顺序、任务目标、验收标准和最小验证跑起来。
第二阶段：补齐风险边界
当项目涉及生产数据、权限、外部服务或多模块协作时，增加 SECURITY.md、ARCHITECTURE.md、RUNBOOK.md 和 ADR。
第三阶段：接入团队门禁
把测试、安全扫描、构建、迁移检查和发布后烟雾测试接入 CI；用 CHANGELOG.md 和任务完成记录保留交付证据；把稳定的重复流程沉淀成 Skill。
模板中的占位符不能原样提交。未知信息写 TBD，并把它变成具体的待确认项；不要为了让文档看起来完整而编造阈值、SLO、权限模型或回滚命令。
十一、每个 Codex 任务的完成清单
在最终声明完成前，至少逐项检查：
1 | [ ] 目标和验收标准清楚，范围内外没有歧义 |
这套流程的目标不是让 Codex 变得更慢，而是把“看起来完成”变成“有证据地完成”。当目标、边界、验证和授权都写清楚后，Codex 才能在更大的代码库、更长的任务和更多参与者之间稳定工作。
总结
一套可落地的 Codex 企业级工作流，可以浓缩成四句话：
- 用
AGENTS.md固化长期规则，用AI_CONTEXT.md保存当前快照； - 用
PRD.md描述产品目标，用TASK.md约束当前执行； - 用测试、安全、架构和运行手册把风险变成可检查的门禁；
- 用计划、审查、变更记录和交接，让每个结果都能被验证、恢复和追溯。
AI 可以提高代码产出速度，但企业真正需要的是可控的交付速度。代码只是结果的一部分，清晰的上下文、明确的授权和可靠的验证，才是 Codex 工作流能够长期运行的基础。
官方模型指导：OpenAI Model guidance。
