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