需求描述实战模板

需求描述实战模板

本节摘要:前面三节讲了原则和模式,本节把它们固化为一套可直接套用的模板。核心是「四要素模板」:功能(做什么)+ 约束(用什么/不用什么)+ 示例(输入输出长什么样)+ 边界(不做什么/异常怎么处理)。通过三个真实案例——一个 REST API 接口、一个 React 组件、一个数据处理脚本——演示从模糊需求到精准 Prompt 的完整转化过程,最后附上最常见的翻车场景与应对策略。

一、四要素模板

任何编程需求,都可以用这四个要素描述清楚:

【功能】做什么:一句话描述核心功能
【约束】用什么/不用什么:技术栈、风格、版本、禁止事项
【示例】输入输出:给一个具体的使用示例或期望的代码结构
【边界】不做什么/异常:排除项、错误处理、性能要求
​

💡 技巧:不是每次都需要四要素全写。简单任务(改个变量名)一句话就够;复杂任务(新增功能模块)四要素缺一不可。判断标准:如果 AI 有可能「猜错」某个方面,就把那个方面写清楚。

二、案例一:REST API 接口

模糊需求:「帮我写一个用户搜索接口」

转化过程:

• 功能:搜索什么?按什么字段?分页吗?→ 「按用户名或邮箱模糊搜索,支持分页」
• 约束:什么框架?什么风格?→ 「FastAPI + SQLAlchemy 异步,项目现有的分页用 paginate() 工具函数」
• 示例:返回什么格式?→ 「返回 {items: [...], total: int, page: int}」
• 边界:搜索词为空怎么办?→ 「搜索词为空时返回全部;长度限制 2~50 字符」

最终 Prompt:

在 src/api/user.py 中添加 GET /users/search 接口:

功能:按 username 或 email 模糊搜索用户,支持分页。

约束:
- 用 SQLAlchemy 2.0 异步查询(async session)
- 分页用项目现有的 paginate() 函数(@file:src/utils/pagination.py)
- 返回格式:{"items": [UserSchema], "total": int, "page": int, "size": int}

示例:GET /users/search?q=john&page=1&size=20

边界:
- q 为空或不存在时返回全部用户(仍分页)
- q 长度 < 2 或 > 50 时返回 422
- 无结果时 items 为空数组,total 为 0
​

三、案例二:React 组件

模糊需求:「做一个搜索框组件」

最终 Prompt:

在 src/components/SearchBar.tsx 中创建搜索框组件:

功能:
- 输入框 + 搜索按钮 + 清除按钮
- 输入时防抖 300ms 后触发 onSearch 回调
- 支持键盘 Enter 触发搜索

约束:
- 函数式组件 + TypeScript
- 样式用 Tailwind CSS(不写自定义 CSS)
- 不引入新依赖(不用 lodash,自己实现防抖)
- Props: { onSearch: (query: string) => void; placeholder?: string }

示例:
<SearchBar onSearch={handleSearch} placeholder="搜索用户..." />

边界:
- 输入为纯空格时不触发搜索
- 组件卸载时清除防抖定时器
- 支持受控模式(可选 value + onChange props)
​

四、案例三:数据处理脚本

模糊需求:「写个脚本处理 CSV」

最终 Prompt:

写一个 Python 脚本 scripts/clean_orders.py:

功能:
- 读取 data/raw_orders.csv(约 10 万行)
- 删除 status 列为 "cancelled" 的行
- 将 amount 列从字符串转为 float,无法转换的设为 0.0
- 按 created_at 列排序(降序)
- 输出到 data/clean_orders.csv

约束:
- 只用 pandas(项目已有依赖)
- 内存友好:用 chunksize 分块读取(10万行不大,但养成习惯)
- 脚本可直接 `python scripts/clean_orders.py` 运行
- 打印处理统计:原始行数、删除行数、转换失败数、最终行数

边界:
- 文件不存在时打印错误信息并 exit(1)
- CSV 编码为 utf-8-sig(有 BOM)
- amount 列可能有 "N/A"、""、"$123.45" 等脏数据
​

五、常见翻车场景与应对

⚠️ 注意:如果你发现 AI 反复犯同一类错误(比如总是用 class 组件而非函数式),不要每次都在 Prompt 里重复纠正——把这条写进 .cursorrules(第 4 章),一劳永逸。

六、模板的灵活运用

四要素不是死板格式,而是检查清单。写 Prompt 时快速过一遍:

• 功能说清楚了吗?(AI 知道做什么)
• 约束够了吗?(AI 知道用什么/不用什么)
• 需要示例吗?(AI 知道输出长什么样)
• 边界明确吗?(AI 知道不做什么)

对于简单任务,可能只需要功能 + 一两条约束:

把 src/utils/date.ts 中的 formatDate 函数改成支持时区参数,
默认 UTC,用 Intl.DateTimeFormat 实现。
​

对于复杂任务,四要素全上,甚至可以加「参考」:

参考 @file:src/api/order.ts 的写法,给 product 模块也写一套 CRUD。
​

本节要点回顾

1. 四要素模板:功能 + 约束 + 示例 + 边界,覆盖 AI 可能「猜错」的所有方面
2. 核心原则:如果 AI 有可能猜错,就写清楚;确定不会猜错的,不用啰嗦
3. 约束最关键:技术栈、版本、禁止事项——这是减少返工的第一要素
4. 示例最直观:贴一段现有代码比描述三段话更有效
5. 边界防溢出:「不做什么」跟「做什么」一样重要
6. 重复错误写进规则:如果同一类纠正出现三次以上,写进 .cursorrules

至此,第 2 章的「对话艺术」四节全部完成。你已经掌握了从原则到模板的完整 Prompt 方法论。下一章,我们深入 AI 编程的第一个核心机制——MCP 协议:它决定了 AI 能「看到」和「触达」多大的世界。