跳到主要内容

本文为非官方中文翻译，内容以 OpenAI 官方英文文档为准。
官方来源：https://developers.openai.com/codex/workflows

工作流

使用 Codex 的开发使用模式

当你把 Codex 当作一个拥有明确上下文和清晰“完成”定义的队友来使用时，效果最好。 本页为 Codex IDE 扩展、Codex CLI 和 Codex cloud 提供端到端的工作流示例。

如果你刚开始使用 Codex，请先阅读提示编写，然后再回到这里查看具体做法。

如何阅读这些示例​

每个工作流都包括：

  • 何时使用，以及最适合的 Codex 入口（IDE、CLI 或 cloud）。
  • 步骤，附带示例用户提示。
  • 上下文说明：Codex 会自动看到什么，以及你应当附加什么。
  • 验证：如何检查输出结果。

注意： IDE 扩展会自动将你当前打开的文件作为上下文包含进去。在 CLI 中，你通常需要显式提及路径（或使用 /mention 和 @ 路径自动补全来附加文件）。

解释代码库​

当你正在熟悉项目、接手某个服务，或试图理解某个协议、数据模型或请求流时，请使用此工作流。

IDE 扩展工作流（本地探索最快）​

  1. 打开最相关的文件。

  2. 选中你关心的代码（可选，但推荐）。

  3. 向 Codex 提示：

    Explain how the request flows through the selected code.

    Include:
    - a short summary of the responsibilities of each module involved
    - what data is validated and where
    - one or two "gotchas" to watch for when changing this

验证：

  • 让它给出一个你可以快速核对的图示或清单：
Summarize the request flow as a numbered list of steps. Then list the files involved.

CLI 工作流（适合你想保留对话记录 + shell 命令时）​

  1. 启动一个交互式会话：

    codex

  2. 附加文件（可选）并提示：

    I need to understand the protocol used by this service. Read @foo.ts @schema.ts and explain the schema and request/response flow. Focus on required vs optional fields and backward compatibility rules.

上下文说明：

  • 你可以在编辑器中使用 @ 从工作区插入文件路径，或使用 /mention 来附加特定文件。

修复 bug​

当你有一个可以在本地复现的失败行为时，请使用此工作流。

CLI 工作流（围绕复现和验证的紧凑循环）​

  1. 在仓库根目录启动 Codex：

    codex

  2. 给 Codex 一个复现步骤，以及你怀疑的文件：

    Bug: Clicking "Save" on the settings screen sometimes shows "Saved" but doesn't persist the change.

    Repro:
    1) Start the app: npm run dev
    2) Go to /settings
    3) Toggle "Enable alerts"
    4) Click Save
    5) Refresh the page: the toggle resets

    Constraints:
    - Do not change the API shape.
    - Keep the fix minimal and add a regression test if feasible.

    Start by reproducing the bug locally, then propose a patch and run checks.

上下文说明：

  • 由你提供：复现步骤和约束（这些比高层描述更重要）。
  • 由 Codex 提供：命令输出、找到的调用点，以及它触发的任何堆栈跟踪。

验证：

  • Codex 应在修复后重新运行复现步骤。
  • 如果你有标准检查流水线，让它运行：
After the fix, run lint + the smallest relevant test suite. Report the commands and results.

IDE 扩展工作流​

  1. 打开你认为 bug 所在的文件，以及离它最近的调用方。

  2. 向 Codex 提示：

    Find the bug causing "Saved" to show without persisting changes. After proposing the fix, tell me how to verify it in the UI.

编写测试​

当你希望非常明确地指定要测试的范围时，请使用此工作流。

IDE 扩展工作流（基于选择）​

  1. 打开包含该函数的文件。

  2. 选中定义该函数的代码行。从命令面板中选择 “Add to Codex Thread”，将这些行添加到上下文中。

  3. 向 Codex 提示：

    Write a unit test for this function. Follow conventions used in other tests.

上下文说明：

  • 由 “Add to Codex Thread” 命令提供：选中的代码行（这是“行号”范围），以及已打开的文件。

CLI 工作流（在提示中描述路径 + 行范围）​

  1. 启动 Codex：

    codex

  2. 使用函数名进行提示：

    Add a test for the invert_list function in @transform.ts. Cover the happy path plus edge cases.

根据截图制作原型​

当你有设计稿、截图或 UI 参考图，并希望快速得到一个可运行的原型时，请使用此工作流。

CLI 工作流（图片 + 提示）​

  1. 将你的截图保存在本地（例如 ./specs/ui.png）。

  2. 运行 Codex：

    codex

  3. 将图片文件拖入终端，把它附加到提示中。

  4. 然后补充约束和结构：

    Create a new dashboard based on this image.

    Constraints:
    - Use react, vite, and tailwind. Write the code in typescript.
    - Match spacing, typography, and layout as closely as possible.

    Deliverables:
    - A new route/page that renders the UI
    - Any small components needed
    - README.md with instructions to run it locally

上下文说明：

  • 图片提供了视觉需求，但你仍需指定实现约束（框架、路由、组件风格）。
  • 为获得最佳效果，请用文字补充任何不明显的行为（悬停状态、验证规则、键盘交互）。

验证：

  • 让 Codex 运行开发服务器（如果允许），并准确告诉你去哪里查看：
Start the dev server and tell me the local URL/route to view the prototype.

IDE 扩展工作流（图片 + 现有文件）​

  1. 在 Codex 聊天中附加图片（拖放或粘贴）。

  2. 向 Codex 提示：

    Create a new settings page. Use the attached screenshot as the target UI.
    Follow design and visual patterns from other files in this project.

通过实时更新迭代 UI​

当你希望在 Codex 修改代码时，以紧凑的“设计 → 微调 → 刷新 → 微调”循环工作，请使用此工作流。

CLI 工作流（运行 Vite，然后用小提示迭代）​

  1. 启动 Codex：

    codex

  2. 在单独的终端窗口中启动开发服务器：

    npm run dev

  3. 提示 Codex 进行修改：

    Propose 2-3 styling improvements for the landing page.

  4. 选定一个方向，并用小而具体的提示迭代：

    Go with option 2.

    Change only the header:
    - make the typography more editorial
    - increase whitespace
    - ensure it still looks good on mobile

  5. 使用聚焦的请求重复进行：

    Next iteration: reduce visual noise.
    Keep the layout, but simplify colors and remove any redundant borders.

验证：

  • 在浏览器中“实时”查看代码更新后的变更。
  • 提交你喜欢的更改，回退你不喜欢的更改。
  • 如果你回退或修改了某项更改，请告诉 Codex，这样它在处理下一条提示时就不会覆盖该更改。

将重构委托给 cloud​

当你希望先仔细设计（本地上下文、快速检查），再将耗时较长的实现交给可并行运行的 cloud 任务时，请使用此工作流。

本地规划（IDE）​

  1. 确保你当前的工作已经提交，或至少已 stash，这样你就可以清晰地比较更改。

  2. 让 Codex 生成一个重构计划。如果你可以使用 $plan skill，请显式调用它：

    $plan

    We need to refactor the auth subsystem to:
    - split responsibilities (token parsing vs session loading vs permissions)
    - reduce circular imports
    - improve testability

    Constraints:
    - No user-visible behavior changes
    - Keep public APIs stable
    - Include a step-by-step migration plan

  3. 审查计划并协商修改：

    Revise the plan to:
    - specify exactly which files move in each milestone
    - include a rollback strategy

上下文说明：

  • 当 Codex 可以在本地扫描当前代码时（入口点、模块边界、依赖图线索），规划效果最佳。

cloud 委托（IDE → Cloud）​

  1. 如果你还没有这样做，请设置一个 Codex cloud environment。

  2. 点击提示编辑器下方的 cloud 图标并选择你的 cloud environment。

  3. 当你输入下一条提示时，Codex 会在 cloud 中创建一个新线程，并继承现有线程的上下文（包括计划以及任何本地源代码更改）。

    Implement Milestone 1 from the plan.

  4. 审查 cloud diff，如有需要继续迭代。

  5. 直接从 cloud 创建 PR，或将更改拉取到本地进行测试和收尾。

  6. 继续迭代计划中的后续里程碑。

进行本地代码审查​

当你希望在提交或创建 PR 之前，有另一双眼睛帮你检查时，请使用此工作流。

CLI 工作流（审查你的工作树）​

  1. 启动 Codex：

    codex

  2. 运行审查命令：

    /review

  3. 可选：提供自定义关注点说明：

    /review Focus on edge cases and security issues

验证：

  • 根据审查反馈应用修复，然后重新运行 /review 以确认问题已解决。

审查 GitHub pull request​

当你希望在不将分支拉取到本地的情况下获得审查反馈时，使用此方法。

在你可以使用此功能之前，请在你的仓库上启用 Codex Code review。参见 Code review。

GitHub 工作流（由评论驱动）​

  1. 在 GitHub 上打开 pull request。

  2. 留下评论，用明确的关注领域提及 Codex：

    @codex review

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

    @codex review for security vulnerabilities and security concerns

更新文档​

当你需要进行准确且清晰的文档修改时，使用此方法。

IDE 或 CLI 工作流（本地编辑 + 本地验证）​

  1. 确定要修改的文档文件，并打开它们（IDE），或使用 @ 提及它们（IDE 或 CLI）。

  2. 向 Codex 提示修改范围和验证要求：

    Update the "advanced features" documentation to provide authentication troubleshooting guidance. Verify that all links are valid.

  3. 在 Codex 起草修改后，审查文档并根据需要迭代。

验证：

  • 阅读渲染后的页面。