工作流与实战示例

前面的页面讲了 Codex 的每个功能，这一页把它们串起来，用十个真实开发中常见的场景演示「一件事从头到尾怎么做」。每个场景都按同样的结构写：

• 场景：要解决什么问题；
• 推荐设置：沙箱、模型和推理强度；
• 提示词原文：可以直接改改就用；
• 过程要点：Codex 工作时你该注意什么、什么时候插话；
• 验收方式：怎样确认它真的做对了。

示例默认用 HiveGPT 提供的 gpt-5.5（其他可选模型以 /model 里列出的为准）。还没接好的话，先看 接入 HiveGPT。

先记住一个通用循环

所有场景都是同一个循环的变体：

步骤	你做什么	常用工具
1. 交代	说清目标、范围、约束、怎么算完成	提示词、@文件、AGENTS.md
2. 规划	复杂任务先让它出计划，你确认	/plan、只读沙箱
3. 执行	让它改代码、跑命令	workspace-write 沙箱
4. 验证	跑测试、看 diff、亲手点一下	/diff、/review、测试命令
5. 收尾	提交、记录经验	git commit、更新 AGENTS.md

几个设置的含义，后面会反复用到：

设置	怎么开
只读	启动时 codex -s read-only，或会话里 /permissions 选 Read Only
可写工作区	codex -s workspace-write，或 /permissions 选 Default
推理强度	/model 里选，或 -c model_reasoning_effort="high"；会话中也可用 Alt+, / Alt+. 调低调高
计划模式	/plan，或 /plan 你的任务 直接带上任务

场景 1：读懂一个陌生仓库

场景：你刚接手一个 Go 后端项目，没有文档，原作者已离职。下周就要在上面加功能，需要尽快搞清楚结构。

推荐设置：只读沙箱；gpt-5.5，推理强度 medium。只读最重要，这个阶段不应该改任何东西。

提示词原文：

我刚接手这个仓库，需要在一周内能独立加功能。请只阅读代码，不要修改任何文件。

按下面的顺序给我一份中文说明：
1. 这个项目是做什么的，技术栈和主要依赖（看 go.mod、Dockerfile、配置文件）。
2. 怎么在本地跑起来：需要哪些外部服务（数据库、Redis 等），启动命令是什么。
3. 目录结构：每个顶层目录负责什么，用一张表列出来。
4. 一个 HTTP 请求从进入到返回经过哪些层，用「POST /api/orders」举例，列出每一层对应的文件和函数。
5. 你认为最容易踩坑的 3 个地方（全局状态、隐式约定、奇怪的写法），附文件位置。

不确定的地方请标注「推测」，不要编造。

过程要点：

• 它会大量执行 ls、rg、cat 之类的命令，这在只读沙箱里都不需要审批。
• 第一轮回答之后追问具体的点比一次问太多更有效，比如：「第 4 点里的 middleware.Auth 是怎么拿到用户 ID 的？把相关代码片段贴出来」。
• 觉得说明有价值，就让它整理成文件。这时需要写权限：/permissions 切到 Default，再说「把以上内容整理成 docs/ARCHITECTURE.md」。

验收方式：照着第 2 点的步骤，自己在本地把项目跑起来；挑第 4 点里的两三个文件，打开核对函数名和调用关系。能跑起来、对得上，说明它读懂了；对不上的地方让它重新查。最后运行 /init 生成一份 AGENTS.md，把运行和测试命令固定下来，后面的任务都会受益。

场景 2：带复现步骤修一个 bug

场景：用户反馈「购物车里同一个商品加两次，数量显示 2，但结算金额只算了 1 件」。

推荐设置：可写工作区；推理强度 high（定位隐蔽的 bug 值得多想一会儿）。

提示词原文：

bug：同一商品加入购物车两次，购物车显示数量 2，但结算页金额只按 1 件计算。

复现步骤：
1. npm run dev 启动，打开 /products/42
2. 点两次「加入购物车」
3. 进入 /checkout，金额是单价的 1 倍，应该是 2 倍

请按这个顺序做：
1. 先写一个能复现这个问题的自动化测试（放在 src/cart/__tests__/），运行它，确认它失败。
2. 找到根本原因，用两三句话解释给我听，再动手修。
3. 修复后运行这个测试和 npm test 全量测试。

约束：不要改结算页的 UI；不要改已有测试的断言。

过程要点：

• 「先写失败的测试」是这个提示词的核心。它逼 Codex 先证明自己理解了问题，也给了修复一个客观的完成标准。
• 它解释根因时认真读一下。如果解释是「金额计算用了 items.length 而不是数量之和」这类具体的东西，可信；如果含糊，让它继续查，不要急着让它改。
• 有日志或报错截图就直接给它：粘贴文本，或把截图拖进终端 / 用 Ctrl+V 粘贴图片。

验收方式：按复现步骤手动点一遍；git diff 确认改动集中在计算逻辑，没有顺手改别的；新测试在修复前失败、修复后通过（可以 git stash 掉修复代码再跑一次验证）。

场景 3：给老代码补测试

场景：src/pricing/discount.ts 是计算优惠的核心逻辑，四百多行，没有任何测试。下个月要改它，想先把现有行为固定下来。

推荐设置：可写工作区；推理强度 medium。

提示词原文：

为 @src/pricing/discount.ts 补单元测试，目的是把「当前行为」固定下来，为后续重构做保护。

要求：
- 使用项目已有的测试框架和风格（参考 src/pricing/__tests__/ 下已有的文件）。
- 覆盖每个导出函数的：正常输入、边界值（0、负数、最大值、空数组）、优惠叠加的组合情况。
- 如果你发现当前代码的行为看起来像 bug，不要修，照现状写断言，并在测试里加 // NOTE: 疑似 bug 的注释，最后汇总给我。
- 完成后运行测试并给出覆盖率（npx vitest run --coverage src/pricing），目标是这个文件的行覆盖率达到 90% 以上。

过程要点：

• 「照现状写断言、疑似 bug 只标注」很关键。补测试阶段改行为，会让你分不清是测试错了还是代码错了。
• 覆盖率没达标时，它通常会自己补；如果它为了凑覆盖率去测私有实现细节，提醒它「只通过导出函数测试」。

验收方式：测试全部通过、覆盖率达标；随手改坏一处逻辑（比如把 >= 改成 >），看有没有测试失败，没有失败说明测试不够严，让它补。最后看一下它汇总的「疑似 bug」清单，这往往是这一步最有价值的产出。

场景 4：分步重构

场景：UserService 有 1200 行，混着注册、登录、资料、通知几块逻辑，想拆开但不能改变对外行为。

推荐设置：先只读 + 计划模式，确认方案后切到可写工作区；推理强度 high。最好在独立的 worktree 里做，见 Worktree 与并行任务。

提示词原文（第一步，规划）：

/plan 我想拆分 src/services/UserService.ts（约 1200 行）。请先阅读它和它的所有调用方，然后给出重构计划：
- 拆成哪几个类或模块，每个负责什么，各自包含哪些现有方法
- 对外接口如何保持不变（调用方是否需要改）
- 分成几步，每一步都能单独编译、单独通过测试
- 哪些地方现有测试覆盖不到，需要先补测试
先不要修改任何文件。

确认计划后（第二步，执行）：

计划可以，但第 3 步的通知模块先不拆。现在只执行第 1 步，完成后运行 npm run typecheck 和 npm test，然后停下来等我确认。

过程要点：

• 一次只做一步，每步之后你看 diff、提交一次。出了问题能精确回退到上一步。
• 对话很长时上下文会变满，可以 /compact 压缩；或者每完成一步就 /new 开新会话，把计划文本贴进去继续，这样更干净。
• 它想「顺便」改命名、改格式时要拦住，重构的提交里混进无关改动，审查起来很痛苦。

验收方式：每一步类型检查和测试都通过；最终对比重构前后的公开接口（导出的类型和函数签名）没有变化；用 /review 审一遍整个分支相对 main 的改动。

场景 5：给前端加一个功能

场景：Vue 3 管理后台的订单列表页要加「按日期范围筛选」，后端接口已经支持 start_date、end_date 参数。

推荐设置：可写工作区；推理强度 medium。

提示词原文：

在订单列表页 @src/views/admin/OrdersView.vue 加「按日期范围筛选」：

- 放在现有「状态」下拉框的右边，用项目里已有的日期选择组件（先在 src/components 里找，没有就告诉我，不要新装依赖）。
- 选择后调用 @src/api/orders.ts 的列表接口，带上 start_date 和 end_date（格式 YYYY-MM-DD），并重置到第一页。
- 筛选条件同步到 URL query，刷新页面后保持；清空时从 URL 去掉。
- 界面文字走 i18n，中英文都加（src/i18n/locales/ 下）。
- 完成后运行 pnpm run typecheck 和 pnpm run lint:check。

过程要点：

• 指出「参照哪个已有文件」「用哪个已有组件」，能让新代码和项目风格一致，这比描述风格有效得多。
• 「不要新装依赖」这类约束要明说，否则它可能为了一个日期选择器引入一个新库。
• 前端改动最终要在浏览器里看。可以让它启动开发服务器（pnpm dev），你自己打开页面点一点。

验收方式：类型检查、lint 通过；浏览器里验证：选日期后列表变化、翻页后条件仍在、刷新后条件仍在、清空后 URL 干净、切换语言文字正确。把发现的问题一条条反馈给它，比一次说「有点问题」高效得多。

场景 6：写一个处理数据的脚本

场景：运营给了一个 3 万行的 CSV（用户导出数据），要按省份统计付费用户数和客单价，并且把手机号格式不对的行挑出来。

推荐设置：可写工作区；推理强度 medium。数据文件可能含个人信息，放在项目目录里处理，不要让它上传到任何地方。

提示词原文：

写一个 Python 脚本 scripts/region_report.py 处理 data/users_export.csv。

先只读文件的前 20 行了解结构，不要把整个文件内容输出到对话里。

脚本要求：
- 只用标准库和 pandas（项目已安装）。
- 输出 out/region_summary.csv：省份、付费用户数、总金额、客单价（保留两位小数），按付费用户数降序。
- 输出 out/bad_phones.csv：手机号不是 11 位数字或不以 1 开头的行，保留原始所有列。
- 金额列可能有空值和「¥1,234.00」这样的格式，要能正确解析；解析失败的行计入 bad_rows 并在最后打印数量。
- 命令行参数：输入文件路径、输出目录，带 --help。

写完运行一次，告诉我各输出文件的行数，并抽 3 行 region_summary 的结果让我核对。

过程要点：

• 「只看前 20 行、不要输出整个文件」既省 token，也避免把整份数据发给模型。
• 它会根据实际数据调整解析逻辑（比如发现日期格式有两种），这正是让它真正运行脚本的价值。
• 以后经常要跑的话，可以让它补一个小的测试数据文件和测试，避免下次改脚本时改坏。

验收方式：自己用表格软件对其中一个省份手算一遍；检查 bad_phones.csv 的行数加上正常行数是否等于总行数；用一个空文件、一个只有表头的文件试试脚本会不会崩。

场景 7：提交前做一次代码审查

场景：你在 feat/coupon 分支上写了两天，准备开 PR。想先自查一遍，别把明显的问题留给同事。

推荐设置：只读即可；审查使用 review_model（HiveGPT 生成的配置里也是 gpt-5.5）。

操作：在 TUI 里输入 /review，会出现四个选项：

选项	审查范围
Review against a base branch	当前分支相对某个分支（选 main）的全部改动
Review uncommitted changes	暂存、未暂存和未跟踪的改动
Review a commit	某一个提交
Custom review instructions	你自己写审查要求

也可以直接带上指令：

/review 审查当前分支相对 main 的改动。重点：1）优惠券叠加时金额会不会变成负数；2）并发领取同一张券时是否可能超发；3）新增的 SQL 有没有注入风险。风格问题不用提。用中文输出。

过程要点：

• 审查结果是「问题清单」，不会自动修改代码。逐条判断，确实是问题的，再说「修复第 1、3 条」。
• 给出重点能显著提高审查质量。泛泛地「帮我审查」往往得到一堆命名、注释之类的意见。
• 想在 CI 里自动做这件事，见 非交互模式与 CI/CD 的 codex exec review。

验收方式：对每条指出的问题，能找到对应代码并理解为什么有问题，才算有效；修复后再跑一次 /review，确认问题消失且没有引入新问题。

场景 8：升级一个有破坏性变更的依赖

场景：项目还在用 axios 0.x，要升到 1.x；或者把 vue-router 从 3 升到 4。这类升级会有 API 变化，改动散落在很多文件里。

推荐设置：可写工作区，安装依赖时需要联网（Codex 会请求审批，或启动时加 -c sandbox_workspace_write.network_access=true）；推理强度 high；在独立分支或 worktree 里做。

提示词原文：

把 axios 从 0.27 升级到最新的 1.x。

步骤：
1. 先查看 node_modules/axios 里新版本的 CHANGELOG 或类型定义（升级后），列出会影响本项目的破坏性变更，以及项目里受影响的位置（用 rg 搜索），先给我看清单。
2. 我确认后再修改代码。
3. 用 pnpm 安装（本项目只用 pnpm，不要用 npm），提交 pnpm-lock.yaml 的变化。
4. 运行 pnpm run typecheck、pnpm test、pnpm build，全部通过才算完成。

不要顺便升级其他依赖。

过程要点：

• 「先列清单再改」让你能在动手前判断升级的工作量，必要时放弃。
• 让它以本地 node_modules 里的实际代码和类型为准，而不是凭记忆，因为它对新版本的了解可能过时。也可以开启网页搜索（启动时加 --search）让它查官方迁移指南。
• 包管理器写明白。项目规定用 pnpm 却被它用 npm 装了一遍，会产生两份锁文件。

验收方式：三条命令全部通过；git diff --stat 里只有预期的文件和锁文件；手动走一遍受影响最大的功能（比如所有发请求的页面）。

场景 9：写文档和注释

场景：内部 SDK 的公共 API 没有文档，新同事每次都要来问。

推荐设置：可写工作区；推理强度 low 或 medium（文档类任务不需要深度推理，速度更重要）。

提示词原文：

为 packages/sdk 写使用文档，输出到 packages/sdk/README.md（覆盖现有的空文件）。

内容：
1. 一段话说明这个 SDK 做什么。
2. 安装和初始化（看 package.json 的包名和 src/index.ts 的导出）。
3. 每个公开方法一节：签名、参数表（名称、类型、是否必填、说明）、返回值、一个可运行的最小示例、可能抛出的错误。
4. 常见问题：根据代码里的错误处理和 TODO 注释推断 3–5 条。

要求：
- 只写代码里真实存在的东西，示例代码必须能通过类型检查（写一个临时文件用 npx tsc --noEmit 验证后删除）。
- 不要修改 src 下的任何文件。

过程要点：

• 「只写真实存在的东西」「示例要能通过类型检查」是防止文档编造 API 的两道保险。
• 文档写完后，可以把「公共 API 改动时同步更新 README」写进 AGENTS.md，以后改代码时 Codex 会顺手维护。

验收方式：随机挑两个示例复制到新文件里运行；让一个没看过代码的同事只看文档完成一个小任务，记下卡住的地方，再让 Codex 补充。

场景 10：从截图还原页面

场景：设计师给了一张活动页的设计稿截图，没有设计文件，要用项目现有的 Vue + Tailwind 实现出来。

推荐设置：可写工作区；推理强度 medium。启动时附带图片，或在会话里粘贴图片。

codex -s workspace-write -i ~/Downloads/campaign.png

提示词原文：

按附带的截图实现一个活动页 src/views/CampaignView.vue，并在 router 里注册 /campaign 路由。

- 使用 Tailwind，颜色和圆角尽量用 tailwind.config.js 里已有的主题值，没有接近的再用任意值。
- 布局要响应式：截图是桌面宽度，手机宽度下改为单列。
- 图片先用 public/placeholder.png 占位，文字照截图写。
- 拆出可复用的组件（比如奖品卡片），放在 src/components/campaign/。
- 完成后运行 pnpm run typecheck，并启动 pnpm dev 告诉我访问地址。

过程要点：

• 截图越清晰越好；一个页面很长时，分成几张截图分段实现，比一张缩得很小的长图效果好。
• 第一版出来后，自己打开页面截个图，再把两张图都给它：「左边是设计稿，右边是现在的效果，请对齐标题字号、卡片间距和按钮颜色」。用截图反馈比用文字描述差异准确得多。

验收方式：在桌面和手机宽度下与设计稿并排对比；检查是否引入了新依赖、是否有写死的像素宽度导致手机端溢出；跑一遍类型检查。

把经验沉淀下来

做过几次之后，你会发现每次都在提示词里重复同样的话：「用 pnpm」「不要改测试断言」「完成后跑 typecheck」。把它们写进项目的 AGENTS.md，以后的任务都会自动遵守，提示词只需要写这次任务独有的部分。

## 约定
- 包管理器只用 pnpm。
- 修 bug 先写能复现的失败测试。
- 不修改已有测试的断言，除非任务明确要求。
- 完成前必须通过：pnpm run typecheck && pnpm test。

反复用到的整套流程（比如「升级依赖」的四个步骤）可以做成 Skill，用一句话触发，见 Skills 和 AGENTS.md。

小结

• 所有场景都是「交代 → 规划 → 执行 → 验证 → 收尾」的循环；只读阶段和可写阶段要分开。
• 好提示词的共同点：目标具体、指明参照的已有文件、写明不能做什么、给出可执行的完成标准。
• 修 bug 先写失败的测试，重构一次一步，升级依赖先列清单，文档要求示例可验证。
• 验收永远靠你自己运行和查看：测试、diff、浏览器，不靠 Codex 的自述。
• 重复的要求写进 AGENTS.md，重复的流程做成 Skill。

下一步：安全与团队管理