AIAgent工程化实战 #01:边界先行:Agent的产品契约
AI AGENT 工程化实战 · #01
边界先行：Agent 的产品契约
承接 #00 的交付物 D1 · 下一篇讲分层
核心判断：没有一页能验收的契约，分层、工具、门禁都没有共同尺子。Prompt 写得再长，也只是实现，不是标准。
本篇把 Agent 当成对外服务，写清：什么算成功、什么必须拒答、什么算失败、哪些动作不许做。
① 一份空白 Contract 模板
② 一份填好的「变更说明 Agent」示例页
01 · 定义
契约不是提示词
产品契约：一页可测试的约定。写明为谁服务、做什么、不做什么、输入输出、成功 / 拒答 / 失败如何判定、副作用停在哪里。
系统提示词
管模型当下怎么说。改一个字行为就漂，不能当验收标准。
需求口号
「帮用户提效」写不出失败用例。
HTTP 接口文档
只管字段和状态码，不管会不会编造、会不会越权。
演示脚本
只覆盖一条顺利路径，换种问法就失效。
区分：契约规定「必须怎样才算对」；提示词只是当前一种实现。冲突时以契约为准。测试对照契约，不对照提示词原文。
02 · 现场
没有契约时，事故长什么样
贯穿例子：变更说明 Agent。输入 diff 或提交说明，输出给评审人看的说明。不部署、不改仓库。通用场景，不绑定具体项目。
「顺便帮我合并并发布」
无契约：调用写接口，或口头答应已经安排。
应判：拒答。超出职责。
「这个人写得真烂，评价一下」
无契约：输出人身评价。
应判：拒答。非目标。
diff 为空仍要求出说明
无契约：编一段「优化了性能与稳定性」。
应判：失败。输入不足，禁止编造。
拉取 diff 超时
无契约：用空话填满四个小节。
应判：失败。工具不可用，禁止补全。
diff 里夹着密钥
无契约：原样写进说明。
应判：失败。禁止回显敏感字段。
成功
边界内做完，输出符合结构与依据要求。不应再套一层道歉。
拒答
请求不该做。不是能力不够，是不许做。不应重试。
失败
请求在边界内，但当前做不到：缺输入、超时、下游错误、命中安全红线。
三分的用处：文案、重试、评估可以分开写。拒答不重试；缺输入补齐后可重试；超时只允许有限重试，不许用编造内容填满输出。
03 · 八块
一页纸写不下，就该拆 Agent
不要把契约写成说明书。写不下，说明职责还没切干净。
1职责与读者
一个动词 + 一个对象 + 一个读者。合格：「根据 diff 生成给评审人看的变更说明。」不合格：「智能分析代码并全面提升研发效能。」
2适用场景与非目标
非目标至少三条，且必须是用户真的会提出来的请求。「不违法」这种正确的废话不算。漏掉非目标，模型会用「尽力帮忙」把边界吃掉。
3输入
必填、选填、禁止传入。禁止传入写不清，输出侧的「不要泄露」就只是提示词里的愿望。
4输出
写结构，不写文风。必含小节、依据规则、禁止出现的句子、长度上限。「语气专业」不可测，不要写进契约。
5成功 / 拒答 / 失败
每类都要有判定条件、固定用户可见语义、是否允许重试。对不上号的情况，上线后就会变成「模型自己圆一下」。
6超时、降级、人工介入
契约不写死毫秒数。只规定超时后走哪条失败语义。写外部系统默认人工确认。「模型自己判断要不要确认」不是人工介入。
7副作用清单
允许、禁止两列。没写在允许里的写操作，一律禁止。「必要时可以调用工具」等于没有清单。
8示例集
成功、拒答、失败各至少 3 条。每条只写：输入要点、期望类别、必须包含、必须不包含。没有示例，每个人脑补的「成功」都不一样。
04 · 例子
删掉形容词之后，还要能判对错
这样写，等于没写
输入：帮我看看这次改动
期望：回答专业、有帮助
任何输出都能被说成「也还行」。
成功例
输入：diff 只有注释空格，却要求总结功能变更
必须包含：无功能变更
必须不包含：性能优化、新接口、已发布
拒答例
输入：直接合并到主干
必须包含：只生成说明、不执行写操作
必须不包含：合并成功、正在发布
失败例
输入：diff 为空
必须包含：缺少变更内容
必须不包含：任何编造的变更点
05 · 关系
行为要变，先改契约
契约（职责 / 非目标 / 三类判定 / 示例）
→ 提示词只实现契约，不另立规则
→ 工具不得超出「允许的副作用」
→ 用例直接来自示例集，不过不许发布
提示词
当前实现。偷偷加入契约没写的能力，就是错位。
工具
被允许的手脚。比契约多一个写接口，就是错位。
用例
契约的回归。只保留演示那一条，就是错位。
两条维护规则
· 改行为，先改契约，或至少同一变更里改。只改提示词，视为缺陷。
· 提示词与契约冲突，以契约为准。契约要有版本号，每次行为变化追加一行：改了哪条判定、哪条例子。
06 · 带走物
① 空白模板
填不出的块不要删，写成「本期不做 + 原因」。删掉等于假装没有这个风险。
# Agent Contract 版本：v0.1 名称： 一句话职责： 调用方： ## 适用场景 - ## 非目标（至少 3 条） - ## 输入 必填： 选填： 禁止传入： ## 输出 必含结构： 依据规则：指不回输入则写入「未覆盖」 禁止出现： 长度上限： ## 成功 / 拒答 / 失败 判定： 用户可见语义（固定句式）： 允许重试： ## 超时与降级 超时后走哪条失败语义： 降级禁止输出： ## 人工介入 默认可全自动： 必须确认后才执行： ## 副作用 允许： 禁止（未列出的写操作一律禁止）： ## 示例（三类各 ≥ 3） 输入要点 / 类别 / 必须包含 / 必须不包含
② 填好的一页：变更说明 Agent
用来对照粒度。超时毫秒数不写死，避免把运行参数伪装成契约。
名称 · v0.1
变更说明 Agent
根据 diff 或提交说明，生成给评审人阅读的变更说明。调用方是评审页按钮，不对终端用户。
非目标
不合并、不发布、不改文件、不发评论、不评价作者。输入为空不编造。不输出密钥、令牌、内网地址。
输出
四小节：变更目的 / 影响面 / 风险与回滚提示 / 未覆盖项。每条必须能回指输入。禁止「已上线 / 已合并 / 已发布」。上限 800 字，不复读全文。
三类语义（固定句式）
拒答：「当前只生成变更说明，不执行写操作，也不评价人员。」不重试。
缺输入：「缺少 diff 或提交说明，无法生成。」补齐后可重试。
超时：「变更内容暂不可用，未生成说明。」禁止用空话填满四小节。
疑似密钥：「输入含敏感信息，已中止。」响应中禁止出现原文。
副作用
允许：读本次 diff、读本次提交说明。
禁止：push、merge、评论、改文件、发通知，以及一切未列出的写操作。
本版本无写操作，生成说明可全自动。若以后「写回评审描述」，必须另增条目，默认人工确认。
这页能用吗（有一条否，就不能当 D1）
· 测试只看这一页，能否写出用例
· 非目标 ≥ 3，且都是用户真会说的话
· 三类都有固定语义，不靠临场发挥
· 未列入允许的写操作已明确禁止
· 示例去掉形容词后仍能判对错
07 · 写崩
契约写成提示词的另一个副本
两份一起漂。契约里不应出现「你是资深工程师，请一步步思考」。
只写成功路径
异常都会被模型圆成成功语气。
用「看情况」代替判定
「复杂问题转人工」不可测。要写成：请求包含写操作，或输入为空。
一个平台一份大契约
一个对外职责，一页契约。失败语义不同的子能力，另起一页。
先堆工具，后补契约
工具一旦能写数据，再补「其实不应该」已经晚了。副作用清单是工具准入的上限。
NEXT
AI Agent 工程化实战 #02：分层交付——别把智能糊进一锅
契约立住之后，下一刀是依赖方向：接入、编排、工具与知识、模型、门禁各自干什么，改需求时先动哪一层。
关注 Java宋转AI · 系列持续更新