# 需求里到底要交代哪些信息，AI 才不会自己乱猜

把一句模糊的需求拆成五个槽位：完成标准、输入输出与边界、环境约束、出错表现和措辞，让模型少替你拍板

> 需求描述 · 提示词写作 · AI 编程协作 · 约 7 分钟 · 09 月 26 日

## 本篇要点

1. 模糊的需求之所以出问题，不在于描述得不够长，而在于代码必须给出答案的地方你没有指定——这些“分叉点”会被模型直接代填，且不通知你。
2. 写需求的实际动作是：把分叉点找出来、自己决定、写下来，目标是收回决定权，而不是增加字数。
3. 需求里值得交代四类内容：可观察的完成标准、输入输出与边界情况、这个项目里允许用什么和不许动什么、出错时的具体表现；措辞本身是第五类信息。
4. 措辞上，对必须做到的事用“必须”而非“应该”，并避免“否则”“按需”“合适的”这类把决定推回给模型的说法。
5. 在这些改法里，写清输入输出格式出现在 44% 的改进中，后置条件 23%，依赖用途 19%，异常与错误信息 12%；算法细节出现最多（57%）。
6. 这些百分比说明的是人们最容易漏掉什么，不代表单条改动的收益大小，而且多来自单函数级别的基准任务。
7. 约束并非越多越好：规则太多会互相淹没，删掉无关约束往往比再加一条更能让重要规则被遵守。
8. 项目里一贯的约定（构建测试命令、风格、禁改目录、已知坑）适合放进每次自动读取的约定文件，与“这次要做什么”的一次性需求分开维护。
9. 让 AI 先给计划、暂时不写代码，能把它准备自行拍板的地方暴露出来，这是在写代码前代价最低的确认方式。

---

上一篇里我们拆开了一个现象：让 AI 补全几行代码很顺，让它做完一整个任务却常常翻车。原因是程序越长，你没说清的地方越多，而每一个没说清的地方，模型都会替你填一个答案——不通知你，直接写进代码。

那么问题就落到最实际的一步：**我到底该说清哪些东西？**

答案不是“把需求写得更长”。这一篇把它变成一份可以照着填的清单。

## 一、模糊的不是想法，是那些没被决定的岔路

先纠正一个常见的误解。你说“帮我写个脚本压缩一下图片”，这句话并不算模糊——你自己心里其实有画面。问题在于这个画面只存在于你脑子里，而代码里每一个必须给出答案的地方，都没得到答案。

这类地方我叫它**分叉点**：代码必须在这里选一条路，而你的需求没有指定是哪条。分叉点不会报错，模型照常给你一份跑得起来的代码，只是它替你选了。等你看见结果才发现“这不是我要的”，返工就开始了。

所以写需求不是描述，而是**把分叉点一条条找出来，自己决定，然后写下来**。

## 二、一句话需求里，藏着六个待定的答案

拿一个具体的例子。你原本想说的只有一句：

> 帮我写个 Python 脚本，把 `photos/` 里的图片压缩一下。

这句话里至少藏着六个模型必须自己决定的地方：

1. 结果写到哪？覆盖原图，还是另存一个目录？
2. 目标是什么？固定输出质量，还是把文件压到某个大小以内？要不要限制宽高？
3. 只处理 `.jpg` 吗？文件夹里混着 `.gif`、`.heic`、`.pdf` 怎么办？
4. 某张图打不开的时候，是报错停下，还是跳过继续？
5. 能用哪些库？Python 3.8 还是 3.11？
6. 跑完怎么知道它做对了？打印什么，还是不打印？

这六条里，任何一条你不在乎，都可以交给模型去选。但你得先意识到它在替你选——**没被意识到的默认选择，就是你后来返工的来源。**

## 三、要交代的五类信息

把上面的岔路归一下类，就五个槽位。前四类是内容，最后一条在措辞里。

**第一，做完的样子。** 用一句能观察的话说清“什么叫做完了”。不是“跑通就行”，而是“`output/` 里每张图都不超过 500 KB，宽高不超过 1920 像素，随便打开一张看不出明显色块”。有了这句，你事后不用逐行读代码，跑一遍就知道对不对。官方指南也把它列为核心习惯：提前说清验收标准，比来回改三轮更省事 [1]。

**第二，输入、输出和边界。** 说清数据从哪来、长什么样、到哪去、格式是什么，以及那些“不常见但一定会遇到”的情况：文件夹是空的、多了一层子目录、某一列缺失。研究者记录过对一批代码生成提示词的改进过程，其中“把输入输出格式写清楚”出现在 44% 的改进里，“补上执行后结果必须满足什么”出现在 23% 里，“明确要用哪些库、各自干什么”出现在 19% 里，“写清该抛什么异常或打印什么错误”出现在 12% 里 [2]。

**第三，环境与约束。** 这一类最容易被忽略，因为它不在需求里，而在你的项目里：能用哪些依赖、不许引入新库、必须复用已有的哪个函数、哪些目录不许动、跑测试用哪条命令。模型看不到这些，就会按训练里见过的常见形状去写——这正是上一篇说的 API 误用和“把已有函数又抄一遍”的来源。约束要写成它读代码看不出来的那种；它能自己看明白的，写进去只是占地方。

**第四，出错时的表现。** 别写“优雅地处理错误”，这种话等于没写。要么说“打不开的文件记下名字继续处理下一个”，要么说“参数少于两个就抛 `ValueError`”。具体怎么出错，是需求的一部分，不是实现细节。

**第五，措辞。** 有两个小习惯很值钱。一是对必须做到的事用“必须”，而不是“应该”“可以”；在这份研究里，把含糊的“应该”改成明确的“必须”就是常见的一类改进 [2]。二是少用“否则”“按需”“相关文件”“合适的”这类词——它们把决定又推回给了模型。要用“否则”，就把两个分支都讲明白：“当 A 成立时做 X；当 A 不成立时做 Y” [2]。

把这些填进去，同一个例子会长成这样：

> 写一个 `compress.py`，处理 `photos/` 下所有 `.jpg` 和 `.png`。
> 输出写到 `output/`，文件名不变，后缀统一为 `.jpg`；`photos/` 里的原文件不动。
> 每张图宽高不超过 1920 像素，文件不超过 500 KB；先按宽高缩，再降质量，直到满足。
> 如果降到质量 60 还是不满足，就保留这一张并记入失败。
> 环境：Python 3.11，只允许用 `Pillow`，不要调用 ImageMagick 这类外部命令。
> 遇到 `.gif`、`.heic` 或非图片文件，跳过并计数；某个文件读不出来时记录文件名继续下一个，不要中断。
> 结束时打印一行：`done: 成功 N，跳过 M，失败 K`。

它并不算长，但每一句都消掉了一个原本由模型代填的答案。

有一点要说清楚：那几个百分比统计的是“改进提示词时，各类修改出现的次数”，说明的是大家最容易漏掉什么，不是每条改动带来多少收益。而且这些任务大多是单函数级别的基准题，里面出现最多的一类修改其实是“把算法本身讲清楚”（57%）[2]——你在真实项目里未必需要这么多，反而“项目里能用什么”这类约束更容易漏。

## 四、约束不是越多越好，同时分清两件事

约束太多会互相淹没。Claude Code 的官方文档给出的经验是：如果一个规则明明写在了项目说明文件里、它却反复违反，通常不是它“不听话”，而是文件太长，重要规则被噪音盖住了，删掉一半往往比再补一条更有效 [3]。

所以每条约束都问一句：**它消掉了哪个具体的猜测？** 没有明确答案的，删掉。

这里顺便分清两层东西。**一次性的需求**回答“这次要做成什么样”；**项目里一贯的约定**回答“这个项目里通常怎么做”。后者值得单独放进一个文件，让工具每次开工时自动读到，比如 Claude Code 的 `CLAUDE.md`，或者通用的 `AGENTS.md` [4]。里面只放读代码看不出来的东西：构建和测试命令、必须遵守的风格、不许改的目录、踩过的坑 [3]。这样你就不必在每条需求里重复交代同一件事。

## 五、漏掉的分叉点，让它先替你列出来

你不必靠自己想全。一个很省力的做法是：**先要计划，先别要代码。**

> 先别改代码。告诉我你打算怎么做，特别是你打算自己决定的地方，以及理由。

它列出的计划里，每一个准备自行拍板的地方，都是你该确认的分叉点 [1]。这比凭空想清单容易得多，而且确认发生在写代码之前，代价最低——改一份几行的计划，远比改一份已经写好的脚本便宜。这也正是下一步要做的事：让 AI 先规划，再动手。

## 收尾：三句话的自检

需求发出去之前，问自己三件事：

1. 别人（或者一周后的你）拿着这段话，能不能判断它做完了没有？
2. 里面有没有“合适的”“按需”“相关文件”这类把决定让出去的词？
3. 每条约束各自消掉了哪个猜测？没有的话，删掉。

写需求的目标从来不是把话写多，而是把**原本会由模型默默替你做的那些决定，收回到自己手上**。

## 术语表

- 分叉点：代码必须给出答案、而需求没有说明的地方；你不决定，模型就替你决定，且不告诉你。
- 验收标准：一句能观察的话，说明做完之后应该看到什么，让你不读代码也知道对不对。
- 前置条件与后置条件：执行前必须成立的输入状况，以及执行后结果必须满足的约束。
- 项目约定文件：放在项目里、每次开工自动被读取的说明文件（如 `CLAUDE.md`、`AGENTS.md`），用来装读代码看不出来的长期规则。
- 约束过载：规则写得太多导致重要规则被淹没，模型反而更容易忽略它们。

## 来源

1. [Anthropic 官方指南：给 Claude 提供上下文、说清完成标准与使用计划模式](https://support.claude.com/en/articles/14553240-give-claude-context-claude-md-and-better-prompts)
2. [Guidelines to Prompt Large Language Models for Code Generation — 代码生成提示词改进准则及各类改动出现比例](https://arxiv.org/html/2601.13118v1)
3. [Claude Code 最佳实践：项目说明文件该写什么、为什么规则太多会失效](https://code.claude.com/docs/en/best-practices)
4. [AGENTS.md — 给编码智能体的通用约定文件格式与典型内容](https://agents.md/)

---

原文：https://pangzhengboyin.com/articles/writing-requirements-ai-can-execute-de6b4129

> **庞征博引** · 想学的，慢慢都会
>
> 庞征博引是把想学的东西写成连载的 AI 学习工具。说出想学什么，它会先了解你的基础，再把主题写成一篇篇 5–10 分钟能读完的文章；边读边问，接下来学什么跟着你走。这篇就是这样写出来的。
>
> 开始你自己的连载 → https://pangzhengboyin.com