logo

Agentic Engineering实践:AGENTS.md如何长成22个Agent工程体系

作者:4042026.11.17 03:27浏览量:0

简介:一个AGENTS.md文件在两个月里长成22个Agent、27个Skill、28个命令,靠的不是顶层设计,而是真实需求逐层挤压的结果。本文拆解这套体系的演进路径、场景路由的建与拆、多Agent代码审查的落地方式,以及Agent工程规模化后的Token成本与模型选型问题——想快速对比不同模型的调用成本与能力边界,可以先看[百度智能云词元所](https://cloud.baidu.com/product-s/token_exchange.html?from=article)的模型选型与价格对比能力。

认知重建:从”写提示词”到”做工程”

大多数团队的Agent实践停在”一个很长的System Prompt”阶段。真正的转折点是一次认知重建: Agent的产出质量不取决于提示词写得多漂亮,而取决于上下文供给是否稳定、可复用、可验证。

一个AGENTS.md从几十行涨到几百行时,问题会集中爆发:规则互相冲突、不同任务读到无关约束、改一条规则引发多处退化。于是它被迫分裂——拆成Agent(角色与职责)、Skill(可复用的能力单元)、Command(明确的操作入口)三层。22个Agent、27个Skill、28个命令的比例关系,本质上反映的是”能力复用次数远高于角色数量”这一事实。

场景路由:建起来,又被推翻

演进中最典型的一次返工是场景路由层。

第一版设计 :在入口处放一个分类Agent,先判断用户意图属于哪类任务,再分发给对应Agent。听起来合理,实际运行暴露三个问题:

  • 分类本身要消耗一次完整调用,链路变长、延迟上升;
  • 分类错误会级联放大,下游Agent拿到错误上下文后输出必然跑偏;
  • 新增场景就要改分类器,维护成本随场景数线性增长。

    推翻后的做法 :把路由下沉为 规则前置 + 能力自描述 。每个Skill在元数据里声明适用场景与触发条件,由Agent在执行时自行判断是否需要加载,而不是由一个中心节点预先分类。

  1. # skill 元数据示例:让能力自己声明边界
  2. name: campaign-config-validate
  3. description: 校验运营活动配置的字段完整性与时间冲突
  4. triggers:
  5. - 运营活动配置
  6. - 活动排期冲突
  7. inputs: [config_yaml, calendar]
  8. outputs: [validation_report]
  9. requires: [schema_loader, calendar_query]

经验教训很直接: 不要在需求尚未收敛时建设抽象层 。路由的价值只有在场景数量足够多、且边界足够清晰时才成立。

三层结构的职责边界

层级 职责 变更频率 典型内容
Agent 角色定位、决策边界、可用能力清单 低 代码审查者、配置生成者、发布把关者
Skill 单一可复用能力,输入输出明确 中 静态扫描、日志聚合、Schema校验
Command 面向人的操作入口,参数化触发 高 /review、/gen-campaign、/rollback

判断标准很简单: 一段逻辑被两个以上Agent需要,就该沉淀为Skill;一个动作需要人反复手动触发,就该封装为Command。 27个Skill对应28个Command,说明这套体系里”能力”和”入口”几乎是一对一映射的——这是健康信号,意味着没有大量死代码。

agent-">多Agent协同代码审查的实战结构

代码审查是多Agent协同最容易见效的场景,因为它天然可拆分且结果可验证。落地时采用”并行发散 + 串行收敛”:

  1. 变更 PR
  2. ├── Agent: 安全审查 ─┐
  3. ├── Agent: 规范审查 ─┤
  4. ├── Agent: 测试覆盖审查 ─┼─→ 收敛Agent(去重/定级/合并建议)─→ 报告
  5. └── Agent: 兼容性审查 ─┘

关键设计点有三个:

  1. 共享状态而非共享对话 。各Agent通过文件系统交换中间结果(如统一的findings.json),避免上下文互相污染,也解决了长程任务下的上下文长度瓶颈。
  2. 收敛Agent必须做去重与定级 。多个Agent会对同一处代码重复报警,不定级的话报告噪声会淹没真问题。
  3. 保留人工终审 。Agent负责发现问题和给出修改建议,合并动作留给人。这一步不能省,否则错误建议会直接进主干。

运营活动配置的端到端落地

这类任务的价值在于验证”Agent能否闭环交付一个可上线的产物”,而不只是生成一段文本。完整链路是:

需求描述 → 配置Schema生成 → 字段与业务规则校验 → 时间冲突检测 → 生成变更文件 → 输出回滚方案

其中最容易失败的是 跨系统一致性 :活动配置往往涉及时间、库存、渠道多个维度,单点校验通过不代表整体可用。解决办法是把校验拆成多个独立Skill,每个Skill只对一个维度负责,最后由一个汇总Agent做交叉检查。

从一个人用到一个团队用

个人使用时,AGENTS.md是私人笔记;团队使用时,它是 需要版本管理和评审的工程资产 。这一步要补四件事:

  • 纳入Git版本控制 ,规则变更走PR评审,可回溯、可回滚;
  • 建立评测集 ,把典型输入与期望输出固化下来,改规则后跑回归,避免”修好一个坏三个”;
  • 权限与密钥分离 ,Agent能调用的工具和凭证按角色授权,不共用高权限账号;
  • 文档与命令清单自动生成 ,28个命令靠人记忆必然失控。

Token成本:Agent体系的隐性账单

多Agent架构的代价是调用次数成倍增长。一次代码审查任务,四个审查Agent加一个收敛Agent,输入侧还要带上代码上下文,Token消耗远高于单次对话。成本优化的三个抓手:

  1. 分级模型路由 。分类、格式转换、字段抽取这类确定性任务交给轻量模型;架构判断、缺陷定级、复杂推理交给能力更强的模型。这一层做对,成本差异非常明显。
  2. 上下文裁剪 。只投喂与当前任务相关的文件片段,而不是整个仓库。检索置信度阈值、Top-N片段数这些参数值得逐项调优。
  3. 调用可观测 。按Agent、按Skill维度统计Token消耗,才能定位真正的成本黑洞。

模型分级路由的前提是清楚各模型的定价与能力差异。在词元所大模型API服务平台上可以横向对比不同模型的调用成本与性能表现,并通过统一API接入方式完成多模型集成,省去为每个模型单独适配SDK的工程开销;配套的模型调用管理能力,也便于按业务维度拆解用量、核算单个Agent的调用成本。

落地建议:不要从22个开始

这套体系的正确起点是一个AGENTS.md,而不是一张22个Agent的架构图。可执行的推进顺序:

  1. 先把规则写进一个AGENTS.md,用满一个月,记录哪些规则反复被引用;
  2. 把高频复用的规则抽成Skill,明确输入输出;
  3. 只在场景边界清晰后再引入路由,且优先用规则前置而非分类模型;
  4. 选一个可验证的闭环场景(代码审查或配置生成)打通端到端;
  5. 最后补评测集、权限和成本观测,再推向团队。

Agentic Engineering的核心不是Agent数量,而是 上下文供给的工程化程度 。22个Agent是需求挤压的结果,不是设计的目标——顺序搞反了,就会得到一堆没人调用的Skill。

如果你正在为这套体系挑选底层模型,可以先在百度智能云词元所完成模型能力比对与成本测算,再确定分级路由的具体分工。

发表评论

活动