---
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="/zh-Hant/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 每次都按同一套工程標準完成任務，而不是靠臨場發揮。
