11 · 从理解到实战场景

理解模型、上下文、沙箱和审批之后，真正影响质量的是任务定义。用户给的经常不是工程任务，而是一句模糊话。

核心动作

flowchart LR
    Fuzzy["模糊需求"] --> Triage["分诊"]
    Triage --> Evidence["收证据"]
    Evidence --> Scope["拆范围"]
    Scope --> Brief["写任务说明"]
    Brief --> Execute["执行"]
    Execute --> Verify["验证交付"]

模糊需求不要直接交给 Codex 修改代码。正确顺序是：

1. 分诊：这句话可能是什么意思。
2. 收证据：先看现场，不猜。
3. 拆任务：把大问题拆成可验证的小任务。
4. 写任务说明：明确目标、范围、边界、验证。
5. 再执行：让 Codex 开始改。

前四步通常不改代码。这个成本看起来慢，但比改错方向后回滚便宜。

案例一：网站做快一点

“网站做快一点”不是一个可执行任务。它可能指：

• 首屏慢。
• 图片太大。
• API 慢。
• 路由切换卡。
• 第三方脚本拖慢。
• SEO 抓取慢。

先让 Codex 分诊，而不是直接优化：

请分诊“网站做快一点”这个需求，不要改文件。
列出可能含义、需要查看的证据、推荐先验证哪一项。

等证据指向首屏 LCP，再写成正式任务：

• 目标：首屏 LCP 从当前基线降到明确阈值。
• 范围：只改 Hero 组件和首屏图片。
• 边界：不新增依赖，不改路由，不动全局配置。
• 验证：Lighthouse、截图对比、核心页面手动检查。

这才是 Codex 能执行的任务。

案例二：这个 bug 你看下

“你看下”最大的问题是没有复现路径。没有复现路径，Codex 只能猜。

先补齐信息：

• 哪个页面。
• 哪个按钮或操作。
• 控制台报错全文。
• 最近改过什么。
• 能稳定复现还是偶发。
• 期望行为和实际行为分别是什么。

拿到信息后，再让 Codex 给假设排序。比如“点击保存没反应”可能是 API 返回结构变了、状态初始值缺失、异步竞态，或者按钮被 disabled。不要让它直接改第一个猜测。

案例三：读懂一个新代码库

“读懂项目”也不是一个可执行任务。更好的目标是“建立项目地图”。

可以让 Codex 只读这些内容：

• README、CONTRIBUTING、AGENTS.md 或 CLAUDE.md。
• package.json、pyproject.toml、Cargo.toml 等项目清单。
• 主要源码目录。
• 路由和入口文件。
• 测试目录。

输出要求应该是：

• 项目一句话用途。
• 技术栈。
• 主要目录职责。
• 启动、测试、构建命令。
• 最重要的文件和原因。
• 新人下一步该读什么。
• 不确定的地方明确标出。

这类任务的关键是“不改文件”。读懂项目阶段不要让 Codex 顺手优化。

一份好任务说明

给 Codex 的任务说明至少包含五项：

• 目标：用户层面的结果是什么。
• 范围：只允许动哪些目录或文件。
• 边界：明确不做什么。
• 验证：用什么命令或人工步骤验收。
• 交付：最后要汇报什么。

如果你说不清验证方式，说明任务还没准备好执行。

常用模板

修 bug：

任务：修复 {现象}
目标：{用户可见问题消失}
范围：只改 {文件/目录}
边界：不新增依赖，不改数据库，不改无关文件
验证：运行 {测试命令}，并手动检查 {步骤}
请先给计划，确认后再改。

补测试：

任务：给 {组件/函数} 补测试
覆盖：正常路径、空值、错误状态、边界输入
边界：不改生产逻辑，除非发现真实 bug 并先说明
验证：运行对应测试文件

代码审查：

请审查当前 diff，不要改文件。
优先看 bug、回归风险、安全问题、缺失测试。
按严重程度排序，并给出文件位置和建议验证方式。

判断任务是否写对

看四点：

• Codex 是否知道先读什么。
• Codex 是否知道不能动什么。
• Codex 是否知道完成后怎么验证。
• 任务是否能拆成一次可 review 的改动。

如果 Codex 开始问大量澄清问题，说明任务还不够具体。如果 Codex 上来就改很多无关文件，通常是范围和边界没写清楚。

新手常见坑

• 把模糊愿望当成工程任务。
• 让 Codex 在没有证据时直接修。
• 没写“不改文件”，结果分析任务变成修改任务。
• 没有验收标准，最后只能凭感觉判断好坏。
• 一次塞太多目标，导致 diff 无法 review。

这一篇的核心不是模板，而是工程顺序：先把需求变成可验证任务，再让 Codex 执行。

下一步

把这里的任务说明方式带回官方场景页：Web、原生应用、数据清洗、PR review、Slack 派发、Computer Use QA 都是同一套逻辑。入口不同，底层标准一样：目标清楚、上下文足够、边界明确、验证可复现。