AI Agent 工程化实战 #01：先定边界，再写产品契约

很多 Agent 项目会先写提示词、接工具，再在行为失控后补充限制，但这些实现细节无法替代统一的验收标准。要让产品、开发和测试对“什么算做对”形成一致认识，需要先把职责边界、异常语义与副作用写成可验证的产品契约，再据此约束提示词、工具和回归用例。

AI Agent 工程化实战 #01：边界先行——Agent 的产品契约（本文） | 承接 #00 的交付物 D1；下一篇讲分层

没有一页能验收的契约，后面的分层、工具、门禁都没有共同尺子。Prompt 写得再长，也只是实现，不是标准。

本篇把 Agent 当成对外服务，写清：什么算成功、什么必须拒答、什么算失败、哪些动作不许做。读完应能交出两样东西：一份空白 Contract 模板，以及一份填好的示例页。

---

1. 先把词钉死

产品契约（Contract）：一页可测试的约定。写明这个 Agent 为谁服务、做什么、不做什么、输入输出长什么样、成功 / 拒答 / 失败如何判定、副作用停在哪里。

它不是下面任何一种：

常被拿来顶替契约的东西	实际管什么	为什么不够
系统提示词	模型当下怎么说、怎么选工具	改一个字行为就漂；无法当验收标准
需求口号	「帮用户提效」	无法写出失败用例
HTTP 接口文档	请求体字段、状态码	不管模型会不会编造、会不会越权
演示脚本	一条顺利路径	换种问法就失效

一句话区分：

契约规定「必须怎样才算对」；提示词只是当前一种实现。冲突时以契约为准。测试对照契约，不对照提示词原文。

---

2. 没有契约时，现场长什么样

用一个常见能力做贯穿例子：变更说明 Agent。输入是 diff 或提交说明，输出给评审人看的变更说明。不部署、不改仓库。例子是通用场景，不绑定任何具体项目。

契约缺失时，通常会出现四类事故。它们看起来像「模型不稳定」，实质是边界没写死。

用户实际说了什么	没有契约时的常见表现	契约本该怎么判
「顺便帮我合并并发布」	调用写接口，或口头答应「已经安排」	拒答。超出职责
「这个人写得真烂，评价一下」	输出人身评价	拒答。非目标
diff 为空，仍要求出说明	编一段「优化了性能与稳定性」	失败。输入不足，禁止编造
拉取 diff 超时	用上一轮记忆或空话填满四小节	失败。工具不可用，禁止补全
diff 里夹着密钥	原样写进说明	失败。禁止回显敏感字段

注意三分，不要混成一个「出错了」：

• 成功：在边界内做完，且输出符合结构与依据要求
• 拒答：请求本身不该做。不是能力不够，是不许做
• 失败：请求在边界内，但当前做不到（缺输入、超时、下游错误、命中安全红线）

三分的价值是：产品文案、重试策略、评估用例可以分开写。拒答不应重试；失败里「补输入」可以重试，「下游超时」可以有限重试；成功不应再套一层道歉。

---

3. 契约最少写清的八块

一页纸。写不下就说明职责还没切干净，应拆成两个 Agent，而不是把契约写成说明书。

3.1 职责与读者

• 名称
• 一句话职责（一个动词 + 一个对象 + 一个读者）
• 谁在调用（人、上游服务、另一个 Agent）

一句话职责写不好，后面全是空话。

合格：根据 diff 生成给评审人看的变更说明。
不合格：智能分析代码并提供专业建议，全面提升研发效能。

3.2 适用场景与非目标

适用场景写触发条件，不写愿景。非目标至少三条，而且要是用户真的会提出来的请求，不是「不违法」这种正确的废话。

非目标的写法：

不做：合并、发布、改文件、给人打分、在输入为空时编造变更点

非目标一旦漏掉，模型会用「尽力帮忙」把边界吃掉。这是契约里最容易被写虚、也最值钱的一块。

3.3 输入

分三列就够：必填、选填、禁止传入。

禁止传入不是道德宣言，是工程约束。例如：要求执行写操作的指令、密钥原文、与本次变更无关的人事评价。输入侧写不清，输出侧的「不要泄露」就会变成提示词里的一句愿望。

3.4 输出

写结构，不写文风。

• 必含小节或字段
• 每条结论的依据规则（必须能指回输入；指不回就进「未覆盖」）
• 禁止出现的句子或字段（「已上线」「已合并」、密钥、内网地址）
• 长度或条数上限（防止把整份 diff 复读一遍冒充摘要）

「语气专业、逻辑清晰」不要写进契约。不可测。

3.5 成功 / 拒答 / 失败

每一类都要有：

1. 判定条件（观察得到，不依赖「感觉还行」）
2. 用户可见语义（固定句式或固定错误码，禁止模型临场发挥）
3. 是否允许重试

工具超时、空输入、越权请求，必须在这一节对上号。对不上号的情况，上线后就会变成「模型自己圆一下」。

3.6 超时、降级、人工介入

契约不负责规定具体毫秒数（那是运行配置）。契约只规定超时之后必须走哪条失败语义，以及降级时允许输出什么、禁止输出什么。

人工介入（HITL）写触发点，不写口号：

• 只读、无副作用：默认可全自动
• 写外部系统（评论、改文件、发通知、下单）：默认人工确认后才执行
• 「模型自己判断要不要确认」不算 HITL，那是把闸门交还给不确定性

3.7 副作用清单

两列：允许、禁止。

没有写在「允许」里的写操作，一律视为禁止。不要写「必要时可以调用工具」——这句等于没有清单。

3.8 示例集

最少：3 个成功、3 个拒答、3 个失败。每个示例四行就够：

输入要点：
期望类别：成功 | 拒答 | 失败
必须包含：
必须不包含：

示例是契约的可执行部分。没有示例的契约，评审时每个人脑补的「成功」都不一样。

---

4. 示例怎么写，才真能当用例

坏示例：

用户：帮我看看这次改动
期望：回答专业、有帮助

这种句子无法失败。任何输出都能被说成「也还行」。

好示例：

输入要点：diff 仅有注释空格变化；用户要求「总结功能变更」
期望类别：成功
必须包含：明确写出「无功能变更」或同等含义；影响面为无
必须不包含：编造的性能优化、新接口、已发布

输入要点：用户说「直接合并到主干」
期望类别：拒答
必须包含：只生成说明、不执行写操作
必须不包含：合并成功、正在发布

输入要点：diff 为空
期望类别：失败
必须包含：缺少变更内容、无法生成
必须不包含：任何编造的变更点

规则就一条：删掉「专业、全面、智能」之后，例子仍然能判对错。 判不了，就重写例子，不要加形容词。

---

5. 契约、提示词、工具、用例怎么挂

行为要变
    │
    ▼
先改契约（职责 / 非目标 / 三类判定 / 示例）
    │
    ├──► 提示词：只实现契约，不另立规则
    ├──► 工具清单：不得超出「允许的副作用」
    └──► 用例：直接来自示例集，不过不许发布

工件	角色	常见错位
契约	验收标准	写成营销文案
提示词	当前实现	偷偷加入契约没写的能力
工具	被允许的手脚	比契约多一个写接口
用例	契约的回归	只保留演示那一条

两条维护规则：

1. 改行为，先改契约，或至少同一变更里改。 只改提示词、契约不动，视为缺陷，不是「灵活」。
2. 提示词与契约冲突，以契约为准。 先改实现去对齐契约，而不是事后把契约改成迁就线上事故。

契约本身要有版本号。每次行为变化追加一行变更说明：改了哪条判定、哪条例子。没有版本的契约，两周后没人知道线上跑的是哪一版。

---

6. 带走物一：空白模板

复制到文档首页，按块填。填不出的块不要删，写成「本期不做 + 原因」。删掉等于假装没有这个风险。

# Agent Contract
版本：v0.1
名称：
一句话职责：
调用方：

## 适用场景
-

## 非目标（至少 3 条，写用户真的会提的请求）
-

## 输入
必填：
选填：
禁止传入：

## 输出
必含结构：
依据规则：结论必须能指回输入；不能则写入「未覆盖」
禁止出现：
长度上限：

## 成功
判定：
用户可见语义：
允许重试：否

## 拒答（超出边界）
判定：
用户可见语义（固定句式）：
允许重试：否

## 失败（边界内做不到）
- 缺输入：
  语义：
  重试：补齐输入后可重试
- 下游超时 / 错误：
  语义：
  重试：有限次；禁止用编造内容填满输出
- 命中敏感信息：
  语义：
  重试：剔除后可重试；禁止回显原文

## 超时与降级
超时后走哪条失败语义：
降级允许输出：
降级禁止输出：

## 人工介入
默认可全自动的动作：
必须确认后才执行的动作：

## 副作用
允许：
禁止（未列出的写操作一律禁止）：

## 示例（成功 / 拒答 / 失败 各 ≥ 3）
1. 输入要点：
   类别：
   必须包含：
   必须不包含：

---

7. 带走物二：填好的一页（变更说明 Agent）

下面是同一模板的填写示例，用来对照粒度。数值型超时不写死，避免把运行参数伪装成契约。

# Agent Contract
版本：v0.1
名称：变更说明 Agent
一句话职责：根据 diff 或提交说明，生成给评审人阅读的变更说明。
调用方：评审页的「生成说明」按钮；不直接对终端用户。

## 适用场景
- 已提供非空 diff，或非空提交说明
- 读者是评审人，需要知道改了什么、影响哪里、还有什么没覆盖

## 非目标
- 不合并、不发布、不改文件、不发评论
- 不评价作者或团队
- 不在输入为空时编造功能变更
- 不输出密钥、令牌、口令、内网地址

## 输入
必填：diff 与提交说明至少一项，且去空白后非空
选填：需求编号、读者类型（评审 / 发布说明）
禁止传入：执行写操作的指令；要求对作者做评价

## 输出
必含结构：变更目的 / 影响面 / 风险与回滚提示 / 未覆盖项
依据规则：每条变更点必须能在输入中找到对应；找不到则只出现在「未覆盖项」
禁止出现：「已上线」「已合并」「已发布」；任何密钥样式字符串
长度上限：800 字；超长 diff 先说明范围，再列要点，不复读全文

## 成功
判定：四小节齐全；变更点均可回指输入；无编造功能；无禁止字段
用户可见语义：直接给出四小节，不加「已为您完成发布」类承诺
允许重试：否

## 拒答
判定：请求合并、发布、改文件、发评论，或要求评价作者
用户可见语义：「当前只生成变更说明，不执行写操作，也不评价人员。」
允许重试：否

## 失败
- 缺输入：
  语义：「缺少 diff 或提交说明，无法生成。」
  重试：补齐后可重试
- 下游超时或错误：
  语义：「变更内容暂不可用，未生成说明。」
  重试：有限次；禁止用空话填满四小节
- 输入含疑似密钥：
  语义：「输入含敏感信息，已中止。请剔除后重试。」
  重试：剔除后可重试；响应中禁止出现密钥原文

## 超时与降级
超时后走「下游超时」失败语义
降级允许输出：上述失败句式
降级禁止输出：编造的变更点、成功语气的四小节

## 人工介入
默认可全自动：生成说明文本
必须确认后才执行：无。本版本不提供任何写操作
（若以后增加「写回评审描述」，该动作另增契约条目，默认人工确认）

## 副作用
允许：读取本次 diff、读取本次提交说明
禁止：push、merge、评论、改文件、发通知，以及一切未列出的写操作

## 示例（节选；落地时补满各 3 条）
1. 输入：diff 只有注释空格
   类别：成功
   必须包含：无功能变更
   必须不包含：性能优化、新接口、已发布

2. 输入：「直接合并到主干」
   类别：拒答
   必须包含：只生成说明、不执行写操作
   必须不包含：合并成功、正在发布

3. 输入：diff 为空
   类别：失败
   必须包含：缺少变更内容
   必须不包含：任何编造的变更点

节选只有 3 条，是为了展示写法。真正放进仓库的契约，成功 / 拒答 / 失败仍要各满 3 条，否则覆盖不住最常见的钻空子问法。

---

8. 怎样算这页契约能用

评审时只问下面几句。有一句答「否」，就还不能当 D1 交付物。

检查	否的含义
测试只看这一页，能否写出用例？	还是提示词，不是契约
非目标是否 ≥ 3，且都是用户真会说的话？	边界仍会被「顺便帮个忙」吃掉
成功 / 拒答 / 失败是否都有固定语义？	线上文案仍靠模型临场发挥
未列入「允许」的写操作是否明确禁止？	工具比契约多一只手
示例删掉形容词后还能判对错？	用例无法回归
行为变更是否要求先改契约版本？	两周后无人知道线上标准

允许长期把契约停在「只读、无写操作」。这是清楚的边界，不是寒酸。不清楚的是：文档写只读，工具列表里却挂着写接口。

---

9. 常见写崩的方式

把契约写成提示词的另一个副本。
两份一起漂，没有尺子。契约里不应出现「你是一个资深工程师，请一步步思考」。

只写成功路径。
拒答和失败不写，评估集就只剩演示问题。上线后所有异常都被模型圆成成功语气。

用「看情况」代替判定。
「复杂问题转人工」不可测。要写成可观察条件：例如「请求包含写操作动词」或「输入为空」。

一个平台一份大契约。
多个职责不同的 Agent 共用一页，非目标和失败语义一定会互相污染。一个对外职责，一页契约。子能力若失败语义不同，另起一页，不要在同一页里用「如果是另一种 Agent 则……」打补丁。

先堆工具，后补契约。
工具一旦能写数据，再补「其实不应该」已经晚了。顺序反过来：契约里的副作用清单，是工具准入的上限。下一篇之前就可以先做这一步，不必等分层文。

---

10. 和上一篇、下一篇的关系

#00 把 D1 定义为：成功 / 失败 / 拒答可测，测试能只凭契约写用例。本篇给出这页纸的结构和一份填写样例。

还没写的部分，故意留到后面，避免一篇里什么都浅：

• 这页契约在系统里放哪一层、改需求时动不动它 → #02 分层
• 副作用清单如何变成工具准入 → #03
• 示例集如何变成发布门禁 → #05

没有本篇这一页，那些篇都会缺少验收对象。

---

下一篇

AI Agent 工程化实战 #02：分层交付——别把智能糊进一锅

契约立住之后，下一刀是依赖方向：接入、编排、工具与知识、模型、门禁各自干什么，改需求时先动哪一层。

---

系列导航

编号	完整标题	状态
#00	AI Agent 工程化实战 #00：工程化到底在工程什么	上一篇
#01	AI Agent 工程化实战 #01：边界先行——Agent 的产品契约	本文
#02	AI Agent 工程化实战 #02：分层交付——别把智能糊进一锅	下一篇
#03	AI Agent 工程化实战 #03：工具与外部能力——接口化	待更
#04	AI Agent 工程化实战 #04：状态与记忆——工程视角	待更
#05	AI Agent 工程化实战 #05：质量门禁——嵌进流水线	待更
#06	AI Agent 工程化实战 #06：可观测与运行手册	待更
#07	AI Agent 工程化实战 #07：发布与演进——版本、灰度、回滚	待更
#08	AI Agent 工程化实战 #08：协作与所有权	待更