很多人用 AI 编程翻车，不是因为 Cursor、Claude Code 或 Codex 不够强，而是任务一开始就写得太模糊。你说“帮我做一个客户管理页面”，AI 只能猜：字段有哪些、谁能看、数据从哪里来、什么算做完。猜对了像效率提升，猜错了就是返工。
所以，AI编程需求文档的重点不是写得像正式 PRD，而是把想法翻译成 AI 能执行、你能验收、别人能接手的任务说明。你可以把它和 AI编程工具专题、老达AI实践专题 里的工作流文章配合使用，先把需求说清楚，再交给工具实现。
先写目标，不要直接写功能
需求文档第一段不要急着列按钮、表格和接口。先说这次任务要解决什么问题，目标用户是谁，完成后用户能多做什么。
例如“做一个客户管理页面”太宽泛，可以改成：
- 目标：让销售在后台快速查看客户状态、最近跟进记录和下一步动作。
- 用户：内部销售和运营人员，不面向外部客户。
- 价值：减少 Excel 手动汇总，避免客户跟进遗漏。
- 本次范围：只做列表、筛选、详情和备注新增，不做复杂权限和自动提醒。
目标写清楚以后，AI 才知道哪些细节重要，哪些可以先不做。它也更容易在实现中做取舍，而不是把所有想象出来的功能都塞进来。
范围要写“做什么”和“不做什么”
AI 编程最怕需求无限外扩。你让它做一个页面，它可能顺手改路由、改状态管理、补一套新的样式组件，最后改动范围比需求本身还大。
需求文档里建议固定写两栏：
| 本次要做 | 本次不做 |
|---|---|
| 客户列表、搜索、状态筛选 | 客户导入导出 |
| 客户详情、跟进记录展示 | 复杂角色权限 |
| 新增一条跟进备注 | 自动发短信或邮件 |
这个写法对 AI 很有用。它既能减少跑偏，也能帮你在验收时判断：没有做导出，不是遗漏，而是明确不在本次范围内。
页面需求要写到状态，而不是只写界面
如果需求只写“做一个好看的列表页”，AI 很容易做出一张静态表格。实际可用的页面至少要覆盖空状态、加载状态、错误状态和移动端表现。
页面部分可以按这个结构写：
- 入口：从哪个菜单、哪个路由或哪个按钮进入。
- 主要区域：表格、筛选栏、操作按钮、详情抽屉或弹窗。
- 字段：展示哪些字段，字段顺序、格式、是否可为空。
- 交互：搜索、筛选、分页、点击详情、新增备注。
- 状态：加载中、无数据、接口报错、保存成功、保存失败。
- 响应式：移动端是否隐藏列、是否改成卡片布局。
这一步可以和 AI编程前端页面怎么验收 一起看。写需求时把状态列出来，验收页面时就不会只看“首屏能不能打开”。
接口和数据要给出真实边界
AI 可以帮你写接口调用和数据处理，但它不知道你的业务数据哪些字段一定有、哪些字段可能为空、哪些字段不能暴露给前端。需求文档里最好给一份简化数据结构。
{
"id": "cus_1024",
"name": "某某科技有限公司",
"status": "following",
"owner": "张三",
"last_contacted_at": "2026-07-20",
"next_action": "下周确认报价",
"notes_count": 3
}然后补上边界说明：客户名称可能为空吗？状态有哪些枚举？日期用什么格式？备注能不能超过 500 字？接口失败时是否允许重试？这些小问题不写清楚，AI 就会按自己的习惯补。
如果项目涉及数据库或数据迁移，建议参考 AI编程数据库迁移怎么做，不要让 AI 在不了解约束的情况下直接改表结构。
验收标准要写成可检查清单
“页面正常”“体验顺滑”“代码质量高”这些话对 AI 帮助不大。更好的验收标准应该能被人或命令检查。
- 客户列表能展示接口返回的姓名、状态、负责人和最近跟进时间。
- 搜索客户名称后，列表只展示匹配结果，并保留当前筛选条件。
- 接口返回空数组时，页面展示空状态，不显示报错。
- 新增备注成功后，详情区刷新备注数量和最新记录。
- 保存失败时给出明确提示，不清空用户已经输入的内容。
- 运行项目现有 lint、test 或 build 命令，结果需要在交付回复中说明。
如果你已经在用 Claude Code 或 Codex，验收标准可以直接写进任务提示里。关于工具改完以后如何验收，可以顺着 Claude Code 测试验收怎么做 和 AI编程上线检查怎么做 继续补齐。
把需求文档拆成 AI 可执行任务
一份需求文档不要一次性丢给 AI 做完所有事，尤其是旧项目。更稳的做法是拆成 3 到 5 个任务，每个任务都有输入、输出和验收。
- 任务 1：读取项目结构，找到客户相关页面、接口和类型定义，不做修改。
- 任务 2：补齐数据类型和接口调用，保留现有风格。
- 任务 3：实现列表、筛选和空状态。
- 任务 4：实现详情与新增备注，并处理失败提示。
- 任务 5：运行验收命令，输出改动摘要和剩余风险。
这样拆任务有两个好处：第一，AI 每一步的上下文更清楚；第二，你可以在中途发现方向不对时及时停下来，不必等它改完一大堆文件再返工。
一份可复用的需求文档模板
项目背景：
本次要解决什么问题，目标用户是谁，为什么现在要做。
本次范围：
要做：
- ...
不做：
- ...
页面与交互：
- 入口：
- 主要区域：
- 字段：
- 状态：
- 移动端：
数据与接口：
- 数据结构：
- 字段边界：
- 错误处理：
验收标准：
- ...
- ...
交付要求：
- 遵守现有项目结构和代码风格。
- 修改前先说明将读取哪些文件。
- 修改后说明改了哪些文件、运行了哪些检查、还有哪些风险。
如果你想把任务说明写得更短，可以参考 AI编程任务说明怎么写。本文这份模板更适合从零开始梳理一个功能需求。
老达点评
AI编程需求文档不是为了显得专业，而是为了减少猜测。你把目标、范围、页面状态、数据边界和验收标准写清楚，Cursor、Claude Code、Codex 才能把“我想做个功能”变成可执行任务。需求越具体，AI 越像开发助手；需求越模糊，AI 越像在替你赌运气。
