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在执行时自行判断是否需要加载,而不是由一个中心节点预先分类。
# skill 元数据示例:让能力自己声明边界name: campaign-config-validatedescription: 校验运营活动配置的字段完整性与时间冲突triggers:- 运营活动配置- 活动排期冲突inputs: [config_yaml, calendar]outputs: [validation_report]requires: [schema_loader, calendar_query]
经验教训很直接: 不要在需求尚未收敛时建设抽象层 。路由的价值只有在场景数量足够多、且边界足够清晰时才成立。
三层结构的职责边界
| 层级 | 职责 | 变更频率 | 典型内容 |
|---|---|---|---|
| Agent | 角色定位、决策边界、可用能力清单 | 低 | 代码审查者、配置生成者、发布把关者 |
| Skill | 单一可复用能力,输入输出明确 | 中 | 静态扫描、日志聚合、Schema校验 |
| Command | 面向人的操作入口,参数化触发 | 高 | /review、/gen-campaign、/rollback |
判断标准很简单: 一段逻辑被两个以上Agent需要,就该沉淀为Skill;一个动作需要人反复手动触发,就该封装为Command。 27个Skill对应28个Command,说明这套体系里”能力”和”入口”几乎是一对一映射的——这是健康信号,意味着没有大量死代码。
agent-">多Agent协同代码审查的实战结构
代码审查是多Agent协同最容易见效的场景,因为它天然可拆分且结果可验证。落地时采用”并行发散 + 串行收敛”:
变更 PR├── Agent: 安全审查 ─┐├── Agent: 规范审查 ─┤├── Agent: 测试覆盖审查 ─┼─→ 收敛Agent(去重/定级/合并建议)─→ 报告└── Agent: 兼容性审查 ─┘
关键设计点有三个:
- 共享状态而非共享对话 。各Agent通过文件系统交换中间结果(如统一的
findings.json),避免上下文互相污染,也解决了长程任务下的上下文长度瓶颈。 - 收敛Agent必须做去重与定级 。多个Agent会对同一处代码重复报警,不定级的话报告噪声会淹没真问题。
- 保留人工终审 。Agent负责发现问题和给出修改建议,合并动作留给人。这一步不能省,否则错误建议会直接进主干。
运营活动配置的端到端落地
这类任务的价值在于验证”Agent能否闭环交付一个可上线的产物”,而不只是生成一段文本。完整链路是:
需求描述 → 配置Schema生成 → 字段与业务规则校验 → 时间冲突检测 → 生成变更文件 → 输出回滚方案
其中最容易失败的是 跨系统一致性 :活动配置往往涉及时间、库存、渠道多个维度,单点校验通过不代表整体可用。解决办法是把校验拆成多个独立Skill,每个Skill只对一个维度负责,最后由一个汇总Agent做交叉检查。
从一个人用到一个团队用
个人使用时,AGENTS.md是私人笔记;团队使用时,它是 需要版本管理和评审的工程资产 。这一步要补四件事:
- 纳入Git版本控制 ,规则变更走PR评审,可回溯、可回滚;
- 建立评测集 ,把典型输入与期望输出固化下来,改规则后跑回归,避免”修好一个坏三个”;
- 权限与密钥分离 ,Agent能调用的工具和凭证按角色授权,不共用高权限账号;
- 文档与命令清单自动生成 ,28个命令靠人记忆必然失控。
Token成本:Agent体系的隐性账单
多Agent架构的代价是调用次数成倍增长。一次代码审查任务,四个审查Agent加一个收敛Agent,输入侧还要带上代码上下文,Token消耗远高于单次对话。成本优化的三个抓手:
- 分级模型路由 。分类、格式转换、字段抽取这类确定性任务交给轻量模型;架构判断、缺陷定级、复杂推理交给能力更强的模型。这一层做对,成本差异非常明显。
- 上下文裁剪 。只投喂与当前任务相关的文件片段,而不是整个仓库。检索置信度阈值、Top-N片段数这些参数值得逐项调优。
- 调用可观测 。按Agent、按Skill维度统计Token消耗,才能定位真正的成本黑洞。
模型分级路由的前提是清楚各模型的定价与能力差异。在词元所大模型API服务平台上可以横向对比不同模型的调用成本与性能表现,并通过统一API接入方式完成多模型集成,省去为每个模型单独适配SDK的工程开销;配套的模型调用管理能力,也便于按业务维度拆解用量、核算单个Agent的调用成本。
落地建议:不要从22个开始
这套体系的正确起点是一个AGENTS.md,而不是一张22个Agent的架构图。可执行的推进顺序:
- 先把规则写进一个AGENTS.md,用满一个月,记录哪些规则反复被引用;
- 把高频复用的规则抽成Skill,明确输入输出;
- 只在场景边界清晰后再引入路由,且优先用规则前置而非分类模型;
- 选一个可验证的闭环场景(代码审查或配置生成)打通端到端;
- 最后补评测集、权限和成本观测,再推向团队。
Agentic Engineering的核心不是Agent数量,而是 上下文供给的工程化程度 。22个Agent是需求挤压的结果,不是设计的目标——顺序搞反了,就会得到一堆没人调用的Skill。
如果你正在为这套体系挑选底层模型,可以先在百度智能云词元所完成模型能力比对与成本测算,再确定分级路由的具体分工。

登录后可评论,请前往 登录 或 注册