---
title: "用 Workflows 编排任务"
description: "把 Codex 任务组织成可复用 workflow：使用场景、上下文、步骤、验证和交付标准。"
verifiedAt: "2026-05-06"
---

import { Cards, Card } from 'fumadocs-ui/components/card';

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

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

> [!NOTE]
> 好 workflow 的核心不是步骤多，而是每一步都有输入、边界和验证。缺少验证的 workflow 只是提示词集合。

<Cards>
  <Card title="Codex Workflows" href="https://developers.openai.com/codex/workflows">
    查看官方 workflow examples 和当前入口说明。
  </Card>
  <Card title="Prompting" href="https://developers.openai.com/codex/prompting">
    学习如何给 Codex 明确目标、上下文、约束和完成标准。
  </Card>
  <Card title="Best Practices" href="/docs/codex/official/04-model-pricing/63-best-practices">
    把 workflow 与 AGENTS.md、skills、MCP 和 automations 连接起来。
  </Card>
</Cards>

## Workflow 的基本结构

```mermaid
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、接手陌生服务、理解数据流。

输入：

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

执行：

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

验证：

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

### 修复 bug

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

输入：

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

执行：

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

验证：

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

### 写测试

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

输入：

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

执行：

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

验证：

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

### 从截图做原型

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

输入：

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

执行：

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

验证：

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

### 迭代 UI

适合前端页面微调。

输入：

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

执行：

```text
只修改 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 模板

```text
名称：
{workflow 名称}

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

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

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

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

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

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

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