Agent 的规范与示例

我做过很多次这样的尝试：把一份团队规范原封不动贴进 prompt，然后期待模型严格遵守。

大部分时候结果是令人失望的。不是因为规范写错了，而是因为规范是为人类的认知习惯写的，而模型的执行方式是另一套。

规范和示例的差别

人类读到一条规范，会自动在脑子里补全它没有说出的部分。一份写着「按钮要有明确的可点性反馈」的规范，人类会理解为：hover 要有变化、点击要有反馈、禁用状态要看起来不同。

模型不会补全。它读到的字面意思就是「按钮要有反馈」，然后它可能给你一个 120ms 的淡入。

问题出在这两个数量级之间：

三行字，每一行都有巨大的解释空间。所以规范写得再精确，交给模型执行的结果仍然不稳定。

例子比规范可靠得多

这是我最大的一个转变。现在我给模型的第一样东西不是规范，是几个我认为对的参照实现。

具体做法很朴素：

1. 找到三到五个已经做对的地方
2. 把它们的结构保留，剥掉业务内容
3. 告诉模型：新功能要长得像这些，而不是「像某个规范描述的样子」

举一个实际的例子。写一个文章卡片之前，我不会再描述「卡片要有纸感、有层次、交互要明确」。我会直接把三张已经存在的卡片给它，说「照这个结构做，颜色换成新的强调色」。

模型对具体结构的模仿能力，远强于对抽象描述的理解能力。这不是模型的缺陷，这是所有描述性沟通的通病。

规范用来约束方向，示例用来传达形状。少给描述，多给形状。

约束也要写成判据

规范不能完全丢掉，但它的角色应该改变：从「怎么做」变成「什么时候算做完了」。

原来的写法：

动画应该快速、克制，并使用弹性缓动。

改写之后：

悬停反馈必须在 200ms 内开始，在 600ms 内结束。缓动只允许用这两条曲线。正文区域的任何祖先元素都不允许有 transform。

第二种写法之所以有用，是因为它是可验证的。它不描述品味，它描述边界。模型可以在写完之后自己检查有没有违反。

这也是我认为判断一份规范是否值得写下来的标准：它能不能被转成检查项。转不了的，通常是讨论，不是规范。

什么时候该给精确规范

有一种情况精确规范是必要的：破坏性操作和不可逆边界。

比如删除操作必须二次确认，支付提交必须有幂等键，上传失败必须能恢复。这些不能靠模仿示例，因为模仿的是形状，而这里是硬约束。

这类规范我会写成显式的检查清单，放在 prompt 末尾，并且明确标注「这些不是建议，是必须满足的条件」。

除此之外的绝大多数事情，示例比规范有效。

一个实践顺序

我现在做新功能时的顺序是固定的：

1. 先找到或做出一个我认为对的具体版本
2. 把它作为参照实现
3. 补充边界条件（哪些不能变、哪些必须可验证）
4. 最后才写说明文字，而且尽量短

顺序反过来的话，我会在后面花更多时间纠正一个结构已经错了的结果。结构一旦形成，描述很难扭转它。