第 01 模块 · 2 节

配置业务级自定义 Agent

《Codex 生产级工程》01 自定义 Agent 构建 · 本节时长 40 分钟

把「业务规则」配进去,Agent 才懂规矩

上一节设计了 Agent 的架构。这一节把架构落地成配置——把业务规则、步骤、规范写进 Agent 的配置,它才能按团队的方式干活。

配置不是「写代码」,而是把规则说清楚

贯穿项目这一节把 deploy-bot 从「设计稿」变成「可配置的 Agent」:把上一节的职责、规范、流程写进它的系统指令和配置里。deploy-bot 真正「学会部署规矩」,就在这一步。

配置包含什么

一个业务级 Agent 的配置,核心是这几部分:

部分 内容 例子
系统指令 它的角色、职责、行为准则 「你是工单处理助手」
业务规则 具体怎么处理 「工单按优先级分派」
步骤流程 处理的先后顺序 「先识别→再分派→再回复」
边界约束 能做什么、不能做什么 「只读,不修改状态」

把规则写清楚,Agent 才按团队的方式干活。

对 deploy-bot 来说,这四部分正好对应它「怎么部署」的全部细节:它是谁、部署守哪些规矩、按什么顺序来、哪些绝不碰。


一个「工单 Agent」配置示例

# 工单处理 Agent

## 职责
识别工单类型,按优先级分派并回复。

## 业务规则
- 紧急工单(含「故障/停机」)优先分派
- 普通咨询走常规队列
- 回复要简洁,附工单号

## 流程
1. 读取工单内容,判断类型
2. 按规则分派到对应队列
3. 生成回复草稿

## 边界
- 只读工单,不修改工单状态
- 不访问客户隐私字段
- 不确定时转人工

这样的配置,就是「业务规则」的可执行化。

换成我们的 deploy-bot,配置会长成这样:

# deploy-bot:自动化部署机器人

## 职责
把仓库 main 分支代码自动部署到 staging,通过门禁后部署 production。

## 业务规则
- 只部署「已通过测试与门禁」的提交,否则不部署
- 部署顺序:测试 → 构建 → staging → 验收 → production
- 每次部署必须上报:版本、环境、成功/失败、耗时

## 流程
1. 拉取目标分支最新代码,确认版本
2. 跑测试与构建,任一步失败即停
3. 部署到 staging,做冒烟验收
4. 验收通过才允许 production,否则报给负责人
5. 全流程写日志并上报结果

## 边界
- 只读代码;只部署 staging/production
- 不碰生产数据库,不删线上数据
- 不确定或门禁没过时,绝不自行部署生产

配置怎么「喂」给 Agent

业务规则通常通过系统指令/角色设定注入给 Agent,写在配置里。核心是:

  • 具体:规则要能执行,别「认真负责」这种空话
  • 结构化:分职责/规则/流程/边界,清楚好读
  • 可验证:每条规则能判断「做没做到」

deploy-bot 的规则为什么每条都要「可验证」?因为部署是高权限动作,判断标准必须明确。比如「门禁过了才部署」——就得说清「门禁=测试通过 + 无必须改未处理」,不然它无法判断。


配置的常见错误

  • 规则太虚:写「要专业高效」,Agent 不知道具体怎么算专业
  • 规则太多:塞一堆,Agent 记不住、抓不住重点
  • 没写边界:没说不能做什么,容易越界

规则要具体、精简、带边界。

对 deploy-bot 更要警惕「规则太多」:部署流程本来就长,如果规则塞了几十条互相矛盾的细则,它反而会在关键时刻抓不住重点,甚至把生产环境搞乱。


配置完先小范围试

别一次铺开。配置好先在小范围真实任务里试:

  1. 拿一个真实工单跑一遍
  2. 看它是否按规则处理
  3. 不符合就调配置

小范围试 → 观察 → 调整,比直接全量上线稳。

deploy-bot 的「小范围」尤其讲究:先在 staging 环境试,绝不要一上来就配置成能直接部署 production。等它在 staging 上把流程跑顺了,再放生产权限。


常见坑:规则写「应该」却不给「判断依据」

最常见的配置坑,是写了一大堆「应该 / 必须」,但没给 Agent 判断「做到了没有」的依据。

真实场景:你在 deploy-bot 配置里写「部署前必须确保代码质量」。deploy-bot 会问:什么叫质量好?测试跑过吗?覆盖率多少算达标?「必须改」的问题算处理了吗?你不写清楚,它就靠猜——而部署这种事,靠猜就是事故。

为什么:Agent 是执行者,不是读心者。「必须 / 应该」是态度词,不是可执行规则。没有量化判断依据,它就退化成「尽力而为」。

怎么破:给每个「必须」配一个「判据」。改成「测试全部通过(npm test 退出码 0)、覆盖率 ≥ 80%、无未处理的『必须改』评论,才允许部署 production」。判据可验证,规则才可执行。


小结

  1. 配置 = 把业务规则说清楚,不是写代码
  2. 核心:系统指令、业务规则、步骤流程、边界约束
  3. 规则要具体、精简、带边界
  4. 配置完先小范围真实任务试,再铺开
练习把 deploy-bot 的配置写成一份 markdown 配置。①三步走:a. 写上「职责」一句话;b. 写 3 条「业务规则」,每条都带可验证判据;c. 写「流程」4-5 步 + 一句边界。②怎么判断做对了:每条规则都能用「是/否」判断,读不出来也没关系、不能含糊;流程步骤顺序清晰、失败即停;边界里明确「不碰生产数据库」。③卡住了怎么办:规则不知道怎么给判据,就反问「我怎么知道它做到了」——把答案写进去;流程写不齐,就只写「拉代码 → 部署 → 上报」三步,后面再补。

下一节,讲工具集成与权限设计。