codex-workflows

English | 简体中文 | 日本語 | Español | 한국어 | Português (Brasil)

面对规模较大的产品开发，Codex有时会为了技术上的一致性，把事情做得比用户真正需要的更多。穷尽所有边界情况、让每条路径都得到确定结果，可能在既定目标并不要求的地方改变用户实际看到的行为。

codex-workflows把工作限制在“已确认的最小目标”之内。它先明确哪些用户可见行为允许改变、哪些绝不能动，并要求在结束前拿出验证依据。在这些边界内，Codex再结合仓库现状，选择容易回退的实现细节。

这些工作流以Agent Skills和自定义代理的形式安装到OpenAI Codex CLI中。主Codex会话在设计前确认范围和大致成本，负责推进工作并处理评审意见，再将获批的工作一路推进到实现和独立验证。

为什么不直接使用Codex？

如果只是范围明确的修复、一次性实验或临时脚本，直接使用Codex更合适。当预期结果和安全的实现边界已经很清楚时，这样更快，成本也更低。

如果技术选择可能改变产品范围、用户可见行为，或者某项决策需要跨上下文长期保留，就适合使用codex-workflows。

比如，“扩展现有认证流程”这项需求，可能逐渐演变成第二套认证机制、更宽泛的校验和新的响应约定。前端可以跟着适配，测试也都能通过，但用户最终得到的行为却从未经过确认。

codex-workflows会在整个执行过程中约束这种范围膨胀：

与直接执行相比，这套工作流会调用更多代理、消耗更多token。只有当保护既定目标值得这笔成本时，才需要使用它。如果某项改动用不着全部检查，可以用轻量模式少做一些检查。

Codex能处理某个边界情况，并不代表这项工作就有必要做。额外校验、确定性行为或新的抽象层，必须是为了保护已批准的需求或可观测契约，或者处理已经证实的故障。反过来也一样：如果某个设计决策最后超出了目标所需，工作流会将其删除，而不会仅仅因为它已经写进文档就继续保留。

一次真实的工作流运行

mcp-image中的BytePlus Seedream提供商集成跨18个文件加入了第三家外部图像服务。8项计划任务在逐步完善提供商特有实现的同时，始终没有改变公开的MCP请求、客户端、文件保存和文件URI契约。

合并前针对真实服务的评估确定了最终的模型路由、提示词上限、超时和响应处理方式。独立评审还发现了无上限文件读取、绕过校验、会阻塞的FIFO路径，以及API密钥规范化不一致等问题。这四项问题全部得到修复，PR最终通过了19个文件中的303项测试，以及一次不重试的真实服务调用。8项任务和4次修复从头到尾都没有改变已经批准的公开契约。

快速开始

需要Node.js 22或更高版本，以及最新的Codex CLI。

安装并运行

cd your-project
npx codex-workflows install

然后在Codex CLI中调用一个工作流：

$recipe-implement 使用JWT添加用户认证

$表示显式调用一项技能。输入$recipe-即可查看可用工作流。

选择合适的入口

处理耗时较长的任务时，$recipe-outcome-watch会独立检查Codex的工作，发现不必要的功能扩展或偏离预期结果的情况时及时提醒。可以在任务进行时启动检查：

$recipe-outcome-watch 对照docs/design/export.md检查工作，每60分钟一次，持续4小时

可以指定设计文档、计划或任务文档，也可以直接说明目标。发现问题时会在当前工作会话中提醒；进展正常时保持安静。检查会在指定时间结束后自动停止，也可以随时让Codex提前停止。

工作原理

flowchart LR
    A[需求] --> B[确认最小且有用的目标]
    B --> C{实现路径是否已经明确？}
    C -->|是| S[直接任务循环与安全评审]
    S --> L[完成]
    C -->|否| D[调研、设计与评审]
    D --> E[规划存在依赖关系的工作]
    E --> F[授权实现]
    F --> H[逐项实现、验证、质量检查并提交]
    H --> K[独立代码评审和安全评审]
    K -->|需要修正| H
    K -->|需求或主要设计发生变化| B
    K -->|通过| L[完成]

决定采用哪条路径的，是互相独立的产品和设计决策数量，而不是文件数量，也不是Codex能找出多少边界情况。

只有一个目标、且能在系统某一部分沿用现有模式的改动，会直接进入已确认的任务，再进行实现以及质量和安全检查。需要系统多个部分相互配合，或需要作出长期保留的设计决策的改动，会先产出已评审的Design Doc和Work Plan；某项决策需要时，还会补充UI Spec或ADR。改动包含多个目标且各自需要设计决策时，还会加上PRD，除非你选择省略。只有当某项需要长期保留的选择至少有两个实质不同的方案时，才会创建ADR。行为由集成测试和E2E测试在用户和调用方能看到的地方证明；只有像计算或解析器这样、一个此类测试无法覆盖其各种情况的逻辑，才会补充单元测试。

实现获得授权后，主会话会执行任务、针对性验证、适用的仓库检查，并为每项任务生成一次实现提交。遇到问题时，它会优先根据已批准的文档和仓库证据自行解决。用户可见行为始终是产品边界，不能为了内部一致性而由实现擅自调整。只有当继续推进需要新增产品需求、改动你提出过或排除过的内容、使用只有你拥有的权限，或执行未经授权且无法撤销的操作时，主会话才会询问你。找到能实现相同结果的更精简方案不属于需要询问的情况，已经给过的许可也不会再次确认。工作流不会把第三方审批、生产环境权限或发布操作加为完成实现的条件。

轻量模式

$recipe-implement 轻量模式。为报表页面添加可排序表格

在任意工作流的请求中说明使用轻量模式即可。阶段和需要你确认的节点不变，只是Codex会少做一些检查：不再对照仓库或其他Design Doc检查Design Doc，也会跳过安全评审。仓库检查改为在最后一项任务完成后统一运行一次，不再在每次提交前运行；最终的代码评审照常进行。在你让Codex停用之前，轻量模式会在本次会话中一直生效。

安装

安装方式

安装到当前项目：

cd your-project
npx codex-workflows install

以下内容会被复制到项目中：

• .agents/skills/：Codex技能（基础技能和工作流）
• .codex/agents/：子代理TOML定义
• 用于跟踪托管文件的清单

如果希望所有项目都能使用这些工作流，请改为安装到用户级CODEX_HOME：

npx codex-workflows install --user

技能会安装到$CODEX_HOME/skills/，代理会安装到$CODEX_HOME/agents/。未设置CODEX_HOME时，默认使用~/.codex。

自定义代理

代理定义都是普通的TOML文件。项目级安装请编辑.codex/agents/中的文件；用户级安装请编辑$CODEX_HOME/agents/中的文件。你可以修改model、sandbox_mode或developer_instructions。按照下文说明，更新程序会保留已编辑的文件。

更新

# 预览变更
npx codex-workflows update --dry-run

# 应用更新
npx codex-workflows update

# 更新用户级安装
npx codex-workflows update --user

更新程序会保留你在本地修改过的文件。它会把每个文件与安装时的哈希值进行比较，并跳过已经改动的文件。更新移动文件时，你的本地修改也会随之移到新路径。已修改但被移除且没有替代文件的内容，会转移到.codex-workflows-preserved/<version>/。新增文件则会自动加入。

# 查看已安装版本
npx codex-workflows status

# 查看用户级安装状态
npx codex-workflows status --user

如需卸载，请运行npx codex-workflows uninstall（用户级安装需加上--user）。你在本地修改过的文件不会被删除。

工作流参考

在Codex中使用$recipe-name调用工作流。输入$recipe-并使用Tab补全，可以查看所有可用选项。

工作状态

工作流使用docs/plans/存放临时状态，包括Work Plan、实现Task File，以及临时的评审修复或测试补充Task File。除非团队希望评审这些临时文件，否则请把该目录加入项目的.gitignore：

docs/plans/

PRD、ADR、UI Spec和Design Doc属于需要长期保存的项目文档，应当提交。

内置指导原则

不必调用工作流，也能用上这些指导原则。普通对话中 Codex 同样会加载它们，所以小的缺陷修复也会遵循和完整工作流相同的根因、范围和验证标准。

生态系统

Nautilus用于验证产品想法并产出PRD，linear-prism则把已批准的需求整理成可直接实施的Linear任务。claude-code-workflows在Claude Code中采用同样的方法，并可与codex-workflows安装在同一项目中。outcome-doctor通过Jev检查Codex的实现方案相对目标是否过度或不足，需要TypeSafe API密钥。

想在这里用Astra？

整个工作流都用Astra跑，用量很快就会见底。codex-subagent-playbook是一个Codex插件，按子代理挑选模型，只在会改变结果的环节使用Astra。

codex plugin marketplace add shinpr/codex-subagent-playbook

[[skills.config]]
path = "/Users/you/.codex/skills/subagent-delegation/SKILL.md"
enabled = false

[[skills.config]]
path = "/absolute/path/to/your-project/.agents/skills/subagent-delegation/SKILL.md"
enabled = false

设计思路

许可证

MIT License。可自由使用、修改和分发。

由@shinpr开发并维护。