提示词工程：把导出需求说清楚

提示词工程解决的不是“怎么把话写得更漂亮”，而是如何把一个模糊任务变成可以执行、可以验收、可以追责的任务规格。

订单导出的需求常常从一句话开始：“后台加一个导出功能。”这句话看似简单，实际包含许多分支：导出哪个页面的数据，支持哪些筛选条件，谁可以导出，导出哪些字段，文件格式是什么，导出失败怎么办，数据量大时是否异步生成。

如果这些问题没有写清楚，模型会按照常见经验补齐细节。补出来的结果可能能运行，但不一定符合业务边界。

模糊提示词的问题

给订单列表加一个导出功能。

这类提示词容易产生多个“都说得过去”的实现：

被模型补全的细节	可能结果
导出入口	放在列表右上角、批量操作栏或更多菜单里
导出范围	当前页、当前筛选结果、全部订单
文件格式	CSV、Excel、JSON
字段选择	只导出列表字段，或导出数据库里的更多字段
权限	沿用页面访问权限，或新增导出权限
失败处理	弹窗提示、静默失败、后台任务重试

这些差异不是实现细节，而是业务行为。提示词没有给出规格时，后续 review 很容易陷入“我以为”和“你以为”的争论。

可执行的任务规格

更适合交给模型执行的说明应该像这样：

任务：为后台订单列表增加 CSV 导出能力。

目标：
运营人员可以按当前筛选条件导出订单明细，用于每日对账。

范围：
- 在订单列表页增加导出入口。
- 导出范围与当前筛选条件一致，包括时间范围、订单状态、支付状态。
- 文件格式为 CSV，编码使用 UTF-8。
- 导出字段只包含：订单号、支付时间、订单状态、支付金额、支付渠道、优惠金额、收货省份。
- 导出文件名格式：orders-YYYYMMDD-HHmmss.csv。

不做：
- 不导出手机号、详细地址、用户备注和内部风控备注。
- 不新增 Excel 格式。
- 不修改订单查询接口的现有响应结构。
- 不调整权限体系，只接入现有的 order:export 权限点。

验收：
- 有权限用户可以导出当前筛选结果。
- 无权限用户看不到导出入口，直接请求接口返回 403。
- 空结果导出时生成只有表头的 CSV。
- 导出失败时页面显示错误提示并允许重试。
- 运行 npm run test -- order-export 和 npm run docs:build 通过。

这段提示词不只是“要求模型做什么”，也说明了“不做什么”和“怎样算完成”。它把订单导出的业务边界、数据边界和验证入口都放进了同一个任务输入。

五个必须写清楚的部分

目标

目标要说明业务结果，而不是只描述代码动作。增加导出接口 是代码动作，运营可以按筛选条件导出订单明细用于对账 才是业务目标。目标清楚后，模型才能判断哪些细节重要，比如字段顺序、金额格式和筛选条件是否一致。

范围

范围负责控制改动面。订单导出通常会碰到页面、接口、权限、数据查询和文件生成，如果没有边界，模型可能顺手重构订单列表、调整查询结构或新增不必要依赖。范围应该明确哪些文件、模块、接口可以改，哪些不能改。

上下文入口

提示词不需要塞进所有代码，但要告诉模型先读什么。例如：

先读：
- docs/ai/vibe-coding/context-engineering.md 中的上下文组织方式。
- src/pages/orders/OrderList.vue，理解列表筛选条件。
- src/api/order.ts，理解订单查询接口。
- src/auth/permissions.ts，确认 order:export 权限点。
- tests/order/order-list.test.ts，参考现有测试风格。

真实执行时，具体路径应来自当前项目。提示词只负责把阅读顺序和关注点说清楚。

验收标准

验收标准要能被运行、观察或 review。体验好 不可验证，导出中按钮禁用并显示进度文案 可以验证；性能不错 不可验证，1 万行以内同步导出接口响应小于 3 秒，超过 1 万行进入异步任务 可以验证。

禁区和风险

订单导出最容易出问题的是越权和敏感字段泄露。禁区要写得直接：不能导出手机号、详细地址、身份证号、用户备注；不能绕过权限；不能把导出文件永久公开在无鉴权地址；不能为了方便把生产配置写进代码。

提示词层级

层级	适用情况	订单导出中的写法
轻量规格	原型和低风险实验	说明入口、字段、格式和原型限制
标准规格	要进入真实后台	补充权限、失败状态、测试命令和不导出字段
关键路径规格	涉及大批量、隐私、审计	补充异步任务、审计日志、回滚、监控和人工确认

层级越高，提示词越接近正式规格。不是每次都要写长文档，但任务风险越高，越不能只写一句自然语言愿望。

对比：感觉式说明和规格式说明

写法	问题	改写方向
导出要快一点	没有性能目标	1 万行以内 3 秒内返回，超过进入异步任务
字段按常规来	字段边界不清	列出字段白名单，并列出禁止导出的字段
权限沿用原来的	不知道哪个权限	明确使用 order:export，无权限返回 403
失败时提示一下	不知道提示位置和恢复方式	页面保留筛选条件，显示错误原因和重试按钮
不要影响别的功能	无法验证	运行订单列表、权限和导出相关测试

写给模型，也写给人

好的提示词会同时服务三类读者。

模型需要它来减少猜测，知道该读哪些文件、改哪些模块、跑哪些命令。Review 者需要它来判断实现是否越界，而不是只凭个人偏好。后续维护者需要它理解为什么当初只导出这些字段、为什么没有直接支持 Excel、为什么超过一定数据量要异步处理。

因此，提示词不应该只存在于一次对话里。稳定的任务规格应进入 issue、设计文档、PR 描述或规格库，成为项目事实的一部分。

总结

提示词工程的核心是把模糊需求压缩成明确边界。订单导出不是“加个按钮”，而是一组关于数据、权限、格式、失败和验证的约定。

当提示词写清楚目标、范围、上下文、验收和禁区时，后续的上下文工程才有方向，Agent 执行才有标准，Harness 才知道要守住哪些边界。

→ 下一步：上下文工程