# 真正的 artifact 是 spec，而不是 prompt

当 agent 的行为通过 spec PR 而不是 prompt 改动落地时，团队会像推理代码一样去推理 agent。本文讲它在实践中长什么样，以及为什么行得通。

- **Author:** Fedor Chishchin
- **Published:** 2026-05-17
- **Tags:** agents, methodology, specs
- **Source:** https://fedorthinks.com/zh/blog/specs-are-the-artifact

---

我第一次尝试交付一个有点分量的 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 时，它就把自己的成本赚回来了。