真正的 artifact 是 spec，而不是 prompt

我第一次尝试交付一个有点分量的 agent 时，摆在 review 桌上的 artifact 是一份巨大 的 system prompt——六段文字、一份 tool 清单、几段示例对话，外加一份每次出岔子 就会变长的「不要做什么」列表。reviewer 会对这些行文挑毛病。新行为以 prompt 改动 的形式落地，有时走 PR，有时直接粘到 Slack 里。对于 这个 agent 到底应该做什么？ 这个问题，并不存在一个单一的答案。

那种做法过不了一个 agent 的门槛。

一份 spec 长什么样

spec 是每个 agent 一份、纳入版本控制的单一 artifact。它写明：

• 身份：名字、角色，用一句话说清它负责什么。
• System prompt：实际的 prompt，按渲染后的样子呈现。包含对其他 spec 共享的 规范化指令的引用。
• Tool 清单：agent 能调用的每一个 tool，连同 MCP server 强制执行的契约。没有 魔法 tool。
• Guardrails：agent 必须拒绝的事情。要具体、可测试。
• 输出 schema：结构化输出的形态，在边界处校验。只有当消费者是用户本人时才用 自由文本。
• Evaluations：这个 agent 必须通过哪些场景。公开 benchmark 加上 holdout suite。

reviewer 批准的是 spec。运行时是从它生成的。

什么变了

三件事，每一件都是承重的。

Review 谈的是行为，而不是措辞。「让 agent 更有用一点」不再是一条有用的 PR 评论。对话变成了「这条 guardrail 缺了」，或者「这个 tool 不在清单里——它该在 吗？」，又或者「输出 schema 没覆盖空的情况」。你终于可以围绕某个具体的东西产生 分歧了。

改进会叠加。 上个季度某人粘在 Slack 里发出去的每一处 prompt 调整，如今要么 在 spec 里，要么不在。如果不在，它要么从头被重新推导出来、要么被悄悄丢掉—— 两种都是好结果。

Onboarding 变成了一个目录。 一位新工程师读四份 spec 就知道系统在做什么。他们 不用再去读散落在十二个文件里的 prompt 碎片。

哪里比听上去更难

spec 不是免费的。三项诚实的成本：

1. 你需要一个 tool 层。 如果你的 agent 是内联调用 httpx.get(...)，那就没有 spec 纪律可以强制执行。spec 假设 tool 是有类型的、有版本的、可被发现的。MCP 正合适。
2. 你需要一套真正的 eval suite。 没有它，spec 不过是一厢情愿的文字。eval 才是 让 spec 成为契约的那个东西。
3. 你需要把 spec 写出来。 这部分会让人觉得像官僚主义——直到第二个 agent 进了 production。

第一次当你不得不靠读除了聊天记录以外的东西来 debug 一个 production 上的 regression 时，它就把自己的成本赚回来了。