用 Workflows 编排任务

Codex 最适合被当作一个 teammate（队友）来使用：你给它明确上下文，也给它清楚的 done definition（完成定义）。

本篇给出 Codex IDE extension、Codex CLI 和 Codex cloud 的端到端 workflow examples（工作流示例）。

如果你刚开始使用 Codex，建议先读 Prompting：

https://developers.openai.com/codex/prompting

然后再回到这里看具体 recipes（做法）。

如何阅读这些示例

每个 workflow 都包含：

• When to use it：什么时候使用它，以及最适合哪个 Codex surface（IDE、CLI 或 cloud）。
• Steps：步骤和示例 user prompts。
• Context notes：Codex 会自动看到哪些上下文，你应该额外附上哪些内容。
• Verification：如何检查输出。

Note: IDE extension 会自动把 open files（已打开文件）作为上下文带入。CLI 中通常需要显式提到路径，或者用 /mention 和 @ path autocomplete 附加文件。

Explain a codebase

当你 onboarding（入职 / 接手）、继承一个服务，或者需要理解 protocol、data model 或 request flow 时，使用这个 workflow。

IDE extension workflow（本地探索最快）

1. 打开最相关的文件。
2. 选中你关心的代码。可选，但推荐。
3. 提示 Codex：

请解释请求是如何流经所选代码的。

请包含：
- 每个相关模块职责的简短总结
- 哪些数据在哪里被校验
- 修改这里时需要注意的一两个坑

Verification：

让 Codex 给出可以快速验证的 diagram（图示）或 checklist：

请把请求流程总结成编号步骤，然后列出涉及的文件。

CLI workflow（适合保留 transcript 和 shell commands）

1. 启动交互会话：

codex

2. 附加文件，可选，然后提示：

我需要理解这个服务使用的协议。请阅读 @foo.ts 和 @schema.ts，解释 schema 以及 request / response 流程。重点说明必填字段、可选字段和向后兼容规则。

Context notes：

• 可以在 composer 里使用 @ 插入 workspace 中的文件路径，也可以用 /mention 附加特定文件。

Fix a bug

当你能在本地复现失败行为时，使用这个 workflow。

CLI workflow（复现和验证的紧凑循环）

1. 在 repo root 启动 Codex：

codex

2. 给 Codex 复现步骤，加上你怀疑的文件：

Bug：在设置页面点击 "Save" 时，有时会显示 "Saved"，但改动没有真正保存。

复现步骤：
1. 启动应用：npm run dev
2. 打开 /settings
3. 切换 "Enable alerts"
4. 点击 Save
5. 刷新页面：开关恢复原状态

约束：
- 不要修改 API shape。
- 保持修复尽量小；如果可行，添加回归测试。

请先在本地复现这个 bug，然后提出 patch 并运行检查。

Context notes：

• 你提供：复现步骤和约束。这些比高层描述更重要。
• Codex 提供：命令输出、发现的 call sites，以及它触发的 stack traces。

Verification：

• 修复后，Codex 应该重新运行复现步骤。
• 如果你有标准检查流水线，要求它运行：

修复后，请运行 lint 和最小相关测试套件。报告具体命令和结果。

IDE extension workflow

1. 打开你认为 bug 所在的文件，以及离它最近的 caller。
2. 提示 Codex：

请找出导致显示 "Saved" 但没有保存改动的 bug。提出修复后，告诉我如何在 UI 里验证。

Write a test

当你想非常明确地指定测试范围时，使用这个 workflow。

IDE extension workflow（基于选区）

1. 打开包含目标 function 的文件。
2. 选中定义该 function 的行。从 command palette 选择 Add to Codex Thread，把这些行加入上下文。
3. 提示 Codex：

请为这个函数写单元测试。遵循项目中其他测试的约定。

Context notes：

• Add to Codex Thread 命令会提供你选中的行，也就是 line number scope（行号范围），以及已打开文件。

CLI workflow（在 prompt 中描述路径和行范围）

1. 启动 Codex：

codex

2. 用 function name 提示：

请为 @transform.ts 里的 invert_list 函数添加测试。覆盖 happy path 和边界情况。

Prototype from a screenshot

当你有 design mock、screenshot 或 UI reference，并希望快速得到可运行 prototype 时，使用这个 workflow。

CLI workflow（图片 + prompt）

1. 把截图保存到本地，例如 ./specs/ui.png。
2. 运行 Codex：

codex

3. 把图片文件拖进终端，附加到 prompt。

4. 补充约束和结构：

请根据这张图片创建一个新的 dashboard。

约束：
- 使用 react、vite 和 tailwind。代码用 typescript 编写。
- 尽量贴近图片中的间距、字体和布局。

交付：
- 一个能渲染该 UI 的新 route / page
- 必要的小组件
- README.md，说明如何本地运行

Context notes：

• 图片提供视觉要求，但你仍然需要指定 implementation constraints，例如 framework、routing、component style。
• 为了获得更好结果，应该用文字补充任何不明显的行为，例如 hover states、validation rules、keyboard interactions。

Verification：

让 Codex 启动 dev server，如果权限允许，并告诉你具体在哪里查看：

请启动开发服务器，并告诉我查看 prototype 的本地 URL / route。

IDE extension workflow（图片 + 现有文件）

1. 在 Codex chat 中附加图片，可以拖拽或粘贴。
2. 提示 Codex：

请创建一个新的 settings page。把附加截图作为目标 UI。
遵循这个项目中其他文件的设计和视觉模式。

Iterate on UI with live updates

当你希望形成紧凑的 “design → tweak → refresh → tweak” 循环，并让 Codex 持续编辑代码时，使用这个 workflow。

CLI workflow（运行 Vite，然后用小 prompt 迭代）

1. 启动 Codex：

codex

2. 在另一个终端窗口启动 dev server：

npm run dev

3. 提示 Codex 修改：

请为 landing page 提出 2-3 个样式改进方向。

4. 选择一个方向，用小而具体的 prompts 迭代：

选择方案 2。

只修改 header：
- 让字体排版更有编辑感
- 增加留白
- 确保移动端仍然好看

5. 用聚焦请求继续：

下一轮迭代：降低视觉噪音。
保持布局不变，但简化颜色，并移除多余边框。

Verification：

• 在浏览器中随着代码更新实时审查变化。
• 喜欢的改动 commit，不喜欢的改动 revert。
• 如果你 revert 或手动修改了某个改动，要告诉 Codex，避免它在下一个 prompt 中覆盖你的修改。

Delegate refactor to the cloud

当你希望先本地认真设计，然后把长时间实现交给可以并行运行的 cloud task 时，使用这个 workflow。

Local planning（IDE）

1. 确认当前工作已经 committed，或者至少 stashed，这样后面能清楚比较 changes。
2. 让 Codex 生成 refactor plan。如果你有 $plan skill，可以显式调用：

$plan

我们需要重构 auth subsystem：
- 拆分职责：token parsing、session loading、permissions 分开
- 减少循环导入
- 提高可测试性

约束：
- 不改变用户可见行为
- 保持 public APIs 稳定
- 包含一步一步的迁移计划

3. 审查计划并协商调整：

请修改计划：
- 明确每个 milestone 中哪些文件会移动
- 加入 rollback strategy

Context notes：

• 当 Codex 能本地扫描当前代码，例如 entrypoints、module boundaries、dependency graph hints，规划效果最好。

Cloud delegation（IDE → Cloud）

1. 如果还没有设置 Codex cloud environment，先设置：

https://developers.openai.com/codex/cloud/environments

2. 点击 prompt composer 下方的 cloud icon，并选择你的 cloud environment。
3. 输入下一条 prompt 后，Codex 会在 cloud 中创建一个 new thread，并带上现有 thread context，包括 plan 和任何 local source changes。

请实现计划中的 Milestone 1。

4. 审查 cloud diff，必要时继续迭代。
5. 直接从 cloud 创建 PR，或者把 changes 拉到本地测试并完成收尾。
6. 继续迭代计划中的其他 milestones。

Do a local code review

当你想在 commit 或创建 PR 之前获得第二双眼睛时，使用这个 workflow。

CLI workflow（审查 working tree）

1. 启动 Codex：

codex

2. 运行 review 命令：

/review

3. 可选：提供自定义审查重点：

/review 重点关注边界情况和安全问题

Verification：

• 根据 review feedback 修复问题，然后重新运行 /review，确认问题已解决。

Review a GitHub pull request

当你希望在不把分支拉到本地的情况下获得 review feedback，使用这个 workflow。

使用前，需要在仓库上启用 Codex Code review。见：

https://developers.openai.com/codex/integrations/github

GitHub workflow（通过评论驱动）

1. 在 GitHub 上打开 pull request。
2. 留一条评论，标记 Codex，并给出明确关注点：

@codex review

3. 可选：提供更明确的指令。

@codex review 请重点审查安全漏洞和安全风险

Update documentation

当你需要一次准确、清楚的文档改动时，使用这个 workflow。

IDE or CLI workflow（本地编辑 + 本地验证）

1. 找到需要修改的 doc file(s)。在 IDE 中打开它们，或者在 IDE / CLI 中用 @ mention 它们。
2. 用 scope（范围）和 validation requirements（验证要求）提示 Codex：

请更新 "advanced features" 文档，加入认证故障排查说明。验证所有链接都有效。

3. Codex 起草改动后，审查文档并按需要迭代。

Verification：

• 阅读 rendered page（渲染后的页面）。