为智能体编写任务说明

描述审查者能够评估的修改

“添加客户导出”留下了多个未决问题。谁能导出记录？包含哪些记录和字段？请求失败时会怎样？智能体可以用看似合理的选择填补空白，但这些选择仍可能不符合业务需要。

先说明用户和问题，再描述所需行为。写明用什么证据判断结果是否可接受。

任务说明应减少不确定性，不必固定每个内部设计选择。指定必须遵守的数据边界。除非有理由改变，否则让实现沿用代码仓库中的现有模式。

使用具体示例

下面的任务说明针对一个虚构的客户支持应用。它是教学示例，不是完整的生产规范。

结果：客户支持经理可以下载客户列表。
操作者：当前组织中的经理。
数据：仅包含该组织的活跃客户。
字段：客户 ID、公司名称和账户状态。
格式：带标题行的 UTF-8 CSV。
被拒绝的请求：返回现有授权错误。
空结果：返回仅含标题行的有效 CSV。
范围：使用现有导出路由和审计模式。
排除项：不新增角色或依赖，不部署。
证据：针对允许、拒绝、空结果和跨组织请求的测试。

这份说明明确了有用的行为和边界，也暴露出更多问题。系统是否应限制导出大小？字段能否包含电子表格公式？谁可以访问审计记录？实现前解决影响重大的问题。不要把示例当作通用清单。

区分要求与假设

要求规定修改必须满足的行为。假设则是尚未验证的事实。应将二者分开。

例如，“使用现有审计模式”假设已经有合适的模式。要求智能体找到它。如果代码仓库中没有，智能体应先报告缺失的前提，而不是自行创造新的审计系统。

约束也可能与目标结果冲突。现有路由可能按设计返回所有组织的数据。智能体应指出冲突，并提出有限的修正。不能悄悄移除数据边界，也不能把任务扩展成架构重写。

把证据纳入完成条件

要求交付摘要说明最终行为、修改范围和已执行的检查。在必要之处提供准确命令和结果。区分检查通过与检查无法运行。

Pull request 应保留修改原因。后续维护者可能只能看到代码，无法看到原始对话。提供足够上下文，解释为什么导出排除了特定字段，以及访问控制如何落实。

Google 的修改说明指南可作为编写这类记录的参考。说明应解释修改内容及其目的。审查后如果修改了实现，也要更新记录，使其与最终实现一致。

让说明详略与任务相称

小型文本修正可以使用简短说明。数据导出需要更多细节，因为失败可能泄露信息。新的付款工作流则需要更多分析和审查。

不要用篇幅衡量任务说明的质量。应问：有能力的审查者能否区分正确与错误结果？如果两个合理实现会在重要行为上产生分歧，就先澄清该行为。