用 Workflows 编排任务

Workflow 是 Codex 任务的可复用执行方法。它不是一段长 prompt，而是一套明确的“什么时候用、给什么上下文、怎么执行、如何验证”。

OpenAI 的 workflow examples 覆盖 IDE、CLI 和 Cloud 等入口。本页把它整理成可复用模板。

Workflow 的基本结构

flowchart LR
    When["When<br/>什么时候用"] --> Context["Context<br/>需要哪些上下文"]
    Context --> Steps["Steps<br/>执行步骤"]
    Steps --> Verify["Verification<br/>怎么验收"]
    Verify --> Deliver["Deliver<br/>交付什么"]

每个 workflow 至少写清：

• 适用场景。
• 推荐入口：IDE、CLI、App、Cloud。
• 需要用户提供哪些上下文。
• Codex 可以自动读取哪些上下文。
• 执行步骤。
• 验证方式。
• 输出格式和风险说明。

如果一个 workflow 说不清验证方式，暂时不要自动化。

常见 workflow 类型

解释代码库

适合 onboarding、接手陌生服务、理解数据流。

输入：

• 目标模块或目录。
• 你关心的问题。
• 已知入口文件或请求路径。

执行：

请只读分析这个服务，不要修改文件。
输出请求流、模块职责、关键文件、数据校验位置和修改风险。
把事实和推断分开写。

验证：

• 要求 Codex 列出读取过的文件。
• 让它画出请求流程图。
• 抽查关键文件是否确实存在。

修复 bug

适合有复现步骤、日志、测试失败或明确症状的问题。

输入：

• 复现步骤。
• 报错、日志或截图。
• 相关路径。
• 不允许修改的范围。

执行：

请先复现或定位问题。
确认相关文件和根因后，再提出最小修复计划。
不要做无关重构。

验证：

• 修复前后同一个复现路径。
• 相关测试或类型检查。
• 若无法运行，说明环境阻塞和替代验证。

写测试

适合需求明确、函数或行为边界清楚的场景。

输入：

• 目标函数、组件或 API。
• 期望行为。
• 边界条件。
• 项目测试框架。

执行：

请为这个行为补测试。
先查看现有测试风格，再添加最小测试。
不要修改生产逻辑，除非测试暴露真实 bug。

验证：

• 新测试能运行。
• 测试覆盖目标行为。
• 不用 stub 掩盖真实逻辑。

从截图做原型

适合 UI prototype、页面重建、设计稿落地。

输入：

• 截图或设计稿。
• 使用的框架和组件约束。
• 目标路由或组件位置。
• 响应式和交互要求。

执行：

请根据截图实现一个可运行原型。
复用项目已有组件和样式，不新增设计系统。
先说明文件位置和实现计划，再修改。

验证：

• 启动 dev server。
• 检查桌面和移动端。
• 截图或人工验收。

迭代 UI

适合前端页面微调。

输入：

• 当前页面 URL。
• 具体视觉问题。
• 不允许改动的范围。
• 目标 viewport。

执行：

只修改 header 区域。
目标是减少文字溢出并保持桌面布局不退化。
改完检查 375px 和 1440px。

验证：

• 浏览器截图。
• 无控制台错误。
• 目标区域未影响其他模块。

入口选择

IDE：

• 最适合当前文件附近的局部开发。
• 上下文来自打开文件、选区和编辑器状态。

CLI：

• 最适合终端、脚本、SSH 和可重复检查。
• 需要显式说明路径和验证命令。

App：

• 最适合多 thread、worktree 和 diff review。
• 适合把 workflow 变成长期任务工作台。

Cloud：

• 最适合异步、远程环境、GitHub workflow。
• 需要先配置 environment、secrets、网络和权限。

从 workflow 到 skill

当某个 workflow 重复出现，就应该沉淀成 skill。

判断标准：

• 至少重复多次。
• 步骤稳定。
• 输入和输出清楚。
• 验证方式明确。
• 风险边界可描述。

沉淀后，workflow 负责“方法”，skill 负责“可触发复用”。如果还需要定时运行，再考虑 automation。

Workflow 模板

名称：
{workflow 名称}

适用场景：
{什么时候用，什么时候不用}

入口：
{IDE / CLI / App / Cloud}

输入：
- {用户必须提供的信息}
- {Codex 应读取的上下文}

边界：
- 不修改 {范围}
- 不新增 {依赖/功能/权限}

步骤：
1. 只读收集上下文。
2. 输出计划和风险。
3. 按确认范围修改。
4. 运行验证。
5. 交付 diff、证据和未验证项。

验证：
{命令、截图、人工检查或其他验收方式}

Workflow 的目标是让 Codex 每次都按同一套工程标准完成任务，而不是靠临场发挥。