撰写清晰的任务描述

任务的「输入质量」，决定「输出质量」

Codex 的核心输入是自然语言需求。它做得怎么样，很大程度取决于你说得多清楚。模糊的需求 → 跑偏的结果；清晰的需求 → 靠谱的结果。

这一节，学会写一份「Codex 一眼就懂」的任务描述。

---

任务描述的三要素

一份好描述，包含三部分：

1. 目标：你要什么结果
2. 输入/输出：输入是什么、输出长什么样
3. 约束：用什么、别碰什么、格式要求

三样都说清，Codex 就不用猜。

---

对比：模糊 vs 清晰

❌ 模糊：「写个工具处理 CSV 文件」

✅ 清晰：「写一个 Python 函数 read_csv(path)：输入一个 CSV 文件路径，返回所有行的列表，每行是 dict（列名→值）。不要用第三方库，只用标准库。如果文件不存在，抛异常。」

	模糊	清晰
目标	有个概念	明确的结果
输入输出	没提	定义了
约束	没有	说清了

清晰的描述，让 Codex 一次做对，少返工。

一个同样清晰的 text-tools 例子，可直接照抄：

【目标】给文本工具加一个「查找替换」功能
【输入】原始文本 + 要找的词 + 替换成什么
【输出】替换后的文本，所有匹配全部替换
【约束】大小写敏感；用 Python 标准库，不用第三方库
【验收】输入 "abc abc"，找 "abc" 替换成 "x"，输出 "x x"

对照「模糊版」——「帮我加个替换功能」——你就能体会清晰描述带来的一次做对。

---

一个可复用的描述模板

写任务时，套这个模板：

【目标】……
【输入】……
【输出】……
【约束】……
【验收】……

例如：

【目标】实现一个计算器 CLI
【输入】命令行两个数字和一个运算符
【输出】计算结果，格式：x op y = result
【约束】只支持 + - * /，除零时报错并提示
【验收】运行 node calc.js 5 + 3，输出 5 + 3 = 8

给 text-tools 加功能时，每次都用这个五段模板。这就是让 Codex「不用猜」的秘诀。

---

描述里常犯的三个错

• 只说概念：「优化一下」→ 太虚，Codex 不知道什么叫「好」
• 漏掉约束：没说「别用第三方库」，它可能引入你没要的依赖
• 没有验收：没说「怎么算对」，它做完你也不清楚对不对

三个错，每一个都导致返工。

尤其「验收」最容易被忽略——它是你和 Codex 共同认定的「什么叫做完」。没有验收，它说「做完了」你也没法确认，只能自己摸索。

---

写完之后，自己读一遍

写完描述，站在 Codex 的角度读一遍：如果我是 Codex，知道目标、输入、输出、约束、验收了吗？

如果还有含糊，就先补齐再发给它。

一个自查用的小技巧：把你的描述只发给一个同学看（不发别的），看他能不能直接动手。能，说明够清晰；要追问，说明还差东西。

---

落地练习：给 text-tools 写第一份五段式描述

用五段模板，完整写一个 text-tools 功能描述，然后真正发给 Codex：

1. 选一个功能，比如「把输入文本中的多个连续空格压缩成一个空格」
2. 按模板写完整描述：

【目标】压缩连续空格
【输入】一段含连续空格的文本
【输出】所有连续多个空格都变成一个空格，其余不变
【约束】只改空格，不动其他字符；用 Python 标准库
【验收】输入 "a   b  c"，输出 "a b c"

3. 把这段描述发给 Codex，看它是否一次做到验收标准

怎么判断做对了？——Codex 按描述直接做对了，没有追问「空格是多个还是几个」「要不要保留单个空格」。你输入样例，输出和你写好的验收一致。

卡住了怎么办？ 它追问细节？说明描述还有含糊，回看五段补全。它做出来的和你想要的不一样？多半是「输出/约束」没写到位，补上再让它改。不知道怎么写验收？就从「输入什么、该得到什么」倒推一个最简单的例子。

---

常见坑：只写「目标」，漏掉「验收」

新手最常见的描述问题：目标写得很清楚，但没有验收——不说「输入什么该得到什么」，Codex 做完，你也说不清对不对，只能反复试。

验收的价值在于：它给「做完」下了一个你和 Codex 都能执行、都能确认的定义。所以写描述时，验收不是可有可无的补充，而是必须有的收尾。哪怕只是一个最简单的输入→输出样例，也要写。没有验收的任务，是最容易返工的任务。

---

小结

1. 输入质量决定输出质量
2. 三要素：目标 + 输入输出 + 约束
3. 用模板：目标/输入/输出/约束/验收
4. 写后自查：我如果是 Codex，够清楚了吗？
5. 给 text-tools 每个功能都用五段式描述，验收必须写

下一节，讲和 Codex 的高效交互。