为AI编程代理编写规范说明书

随着AI编程代理从单纯的问答工具演变为能够直接编辑仓库、运行命令、创建分支并请求人工审查的主动执行者，编写规范说明书的重要性空前提升。这要求我们重新思考提示词的设计——当代理操作共享代码库时，提示词不再是私人笔记，而是一份公开的任务分配书。

一份良好的编程代理规范不应冗长，但必须清晰传达五个核心要素：任务背景（为何要做）、需要改变的行为、必须保留的约束、定义正确性的示例或场景，以及审查者应检查的验证证据。这五个要素构成了规范驱动开发、行为场景、问题模板、轻量设计文档等各种方法论的基础。无论采用何种框架，关键在于规范能为代理提供足够的上下文来行动，同时为团队提供足够的结构来审查结果。

规范与提示词的本质区别在于：提示词擅长启动工作，但容易消失在会话历史中；规范则承载任务，成为团队持续可见的审查对象。私人提示可能包含缩写、缺失上下文和未言明的假设，这在小范围解释或一次性脚本中尚可接受，但对于团队工程而言，它们难以与拉取请求对比，也无法帮助后来者理解变更原因。规范则让任务分配具有可见的形状，可以在实现前、中、后持续被团队检视。

最强有力的规范如同小型行为契约。需求说明系统应做什么，场景提供具体示例（通常采用Given/When/Then格式），设计说明和任务清单描述技术方案。这种分离是AI辅助工程中最有用的纪律之一。如果意图与实现过早混合，代理可能误优化实现细节而忽略真正需要的行为。分配层将三个问题清晰区分：何种行为应改变？哪些约束或示例定义正确性？当前合适的实现路径是什么？实现可随代理阅读代码库而演进，但需求应保持稳定以供审查。

以修复测试为例，一个私人提示“修复不稳定的登录测试并更新需要修改的地方”过于模糊。更好的规范会缩小范围：明确观察到的问题（回调请求到达时会话记录尚不可见）、期望行为（创建单个会话并重定向）、约束（不削弱认证检查、不添加sleep）、验证方式（运行受影响的测试）。这并非去除判断，而是为代理设定边界，为审查者提供对照依据。

规范驱动的开发不必然等同于瀑布模型——只要团队保持规范轻量、可迭代、优先用于已有代码。规范应随着实现学习而调整：如果探索发现初始方案错误，设计应改变；如果需求过宽，范围应缩小；如果场景暴露了新边缘情况，规范应纳入该场景。纪律不在于“编码前写出完美计划”，而在于“保持可见的意图与实现的现实同步演进”。

有了可见的任务分配，审查者的关注点从“这个差异看起来对吗？”转变为“这个差异是否满足我们约定的行为变更，在指定的约束下，并附有可检查的证据？”这是一个更好的问题。规范不仅帮助代理开始工作，更帮助团队保持对齐。

AI编程会话是临时的，但代码仓库是永久的。将规范存入仓库，按功能或变更组织，并随代码更新，使其成为对人和代理都有用的持久上下文。代理的上下文容易丢失——聊天记录被清除、上下文窗口填满、执行者可能不同——而规范为意图提供了持久家园。它们不替代代码、测试或文档，而是将它们连接起来。

规范最适用于有明确边界的工作：行为变更、错误修复、兼容性更新、小功能、迁移步骤、CI修复或具有清晰约束的窄重构。在这些场景下，团队可以描述期望的变更并检查结果是否匹配。随着AI编程代理能力持续增强，保留代理人应满足的任务分配变得愈发重要。这一原则超越了任何特定工具：如果代理作用于共享代码，其规范与结果都应能被团队审查。