随便问和认真交代，不是一回事

来想象一下这个场景：你脑子里有个明确的需求，打开常用的 AI 编程助手噼里啪啦敲完需求回车，看着它自信地把你的代码库改了个底朝天。一小时后再看 PR，问题是解决了，但不是你想要解决的问题，顺便还把本来没打算动的功能搞挂了。

这种事是不是很眼熟？

随着 AI 编程助手从"回答问题"进化到"直接改代码"，很多开发者开始意识到：当初对付聊天机器人的那套随性提问法，放到真实项目里根本不够用。

问题不在于把提示词写得更详细。而是要从根本上改变我们给 AI 工具发指令的方式。

随口问和正式交代，是两码事

提示词（prompt）的强项是开启对话。用来解释需求、临时脚本、头脑风暴都挺顺手。提示词存在于聊天窗口里，可以用缩写，可以默认别人都懂你的意思。

这样玩完全没问题——前提是你只是在问问题。

但如果 AI 助手要改共享代码、执行命令、提交分支让同事 review？那你随手打的字就变成了任务书。

任务书可不是把话说漂亮就完了。它需要正确的上下文、清晰的边界、具体的例子，还有怎么才算完成的判断标准。

这就是"规格文档"（Spec）的价值所在。

规格文档不是提示词的豪华升级版。它是一份结构化的说明，清楚记录：你解决的是什么问题、什么行为要改、什么必须保持不变、怎么才算干得好。

不像提示词——AI 一开工提示词就消失了。规格文档会一直陪着你：指导 AI、帮助 reviewer 审核、让以后的维护者明白当时为什么这么决定。

好的规格文档要包含什么

不需要写成长篇小说。核心就五样东西：

1. 背景： 为什么要做这件事？用户遇到了什么问题？代码库里有什么约束 AI 应该知道？

2. 要改什么行为： 什么具体功能要改、要加、要删？说清楚，别含糊。"当 X 发生时用户应该收到邮件通知"比"优化通知系统"有用多了。

3. 不能动的部分： 什么必须保持原样？已有的 API 接口、性能指标、依赖关系，这些都不能乱改。

4. 正确的样子是什么： 用具体场景告诉 AI 什么算"做对了"。Given/When/Then 格式挺好用，或者直接列几个测试用例也行。

5. 验收标准： reviewer 怎么判断这活儿干完了？应该检查什么？应该问什么问题？

这个框架听起来应该不陌生——做 BDD（行为驱动开发）的、写过带验收标准的 issue 模板的、写过设计文档的都见过类似的。格式本身不重要，重要的是把该说的信息放进去，而且要让别人能分享、能 review。

规格文档放在哪

规格文档的好处之一就是灵活。它不一定是单独的庞然大物，放哪都行：

• GitHub issue 里写清楚验收标准
• PR 描述里说明这次改的是什么行为
• 特性文件里的 BDD 场景
• 开始动手前的一份轻量设计笔记
• OpenSpec 或 GitHub Spec Kit 这样的工具

关键是让上下文和审核标准可见、持久。你的规格文档不应该随着聊天窗口关闭就消失。它应该跟着代码走，给同事提供实实在在的评判依据。

把"想要什么"和"怎么做"分开

重头戏来了。

好的规格文档本质上是一份小小的行为契约。它把三个问题分得清清楚楚：

1. 什么行为要变？（需求）
2. 什么标准算对了？（验收条件）
3. 现在好像适合怎么做？（技术方案）

这三个问题有关联，但不能搅成一团。

为什么要这么分？因为 AI 编程助手有个毛病：一旦把意图和实现混在一起，它就可能优化错方向。它可能老老实实照着你说的实现细节跑，却漏掉了你真正想要的行为；也可能写出技术上挺酷炫的代码，偏偏没解决你提的问题。

有了这个"任务层"，需求保持稳定，实现方式可以灵活调整。AI 读代码、遇到坑、调整方案，整个过程中规格文档就是定海神针："这活儿到底满不满足要求？"

这招对老代码库特别有用。大部分工程工作不是从零开始，而是在已有基础上改行为。好的规格文档说清楚：现在的行为是什么、要改成什么样。reviewer 不用从代码实现里猜你的意图。

迈出这一步

如果你习惯把 AI 编程助手当超级搜索引擎用，可能会觉得这太小题大做了。但想想相反的情况：共享代码被乱改、PR 难 review、最后交出来的东西跟想的不太一样。

从"提示词驱动"变成"规格文档驱动"，不是为了搞官僚主义。是为了让人类和机器都有足够的清晰度，能真正高效配合。

从小处开始。下次准备派 AI 进代码库之前，花五分钟写下来：背景是什么、要改什么行为、怎么算成功。找个显眼的地方放着——哪怕就塞在 PR 描述里也行。

你未来的自己，还有你的同事，会感谢现在的你。

说到底： AI 编程助手是挺能干的协作者。把它当协作者对待，给它一份正经的需求说明，它才能交出值得 review 的活儿。