规则、工作流与子智能体:拆分用于dbt的AI智能体插件
为何一个庞大的指令文件会失败,以及如何通过AGENTS.md这种基于规范的技能、子智能体、钩子函数和Jira MCP在dbt工作流中各承担一项任务。
来源: Rules, Workflow, Sub-Agents: The Three Layers We Split Our AI Agent Into
单个指令文件无法同时承载规则集、处理流程以及日常任务,否则这三者中的某一项就会受到影响。最初的dbt agent工作流就是如此运行的,而将其拆分的原因恰恰说明了如何合理组织AI智能体的指令。
背景说明:当要求人工智能代理编写dbt模型时,它生成的代码虽然能够通过编译和所有测试,但计算出的结果仍可能是错误的。为了避免依赖代理的记忆,该流程被转化为存储在代码仓库中的七个严格检查点,这些检查点成功发现了仅靠测试无法发现的真实缺陷。此处重点介绍维持这些检查点正常运行的机制:规则、工作流、子代理、钩子以及与Jira的集成。该插件具有三层结构,即始终生效的规则、由用户启动的工作流、以及用于处理复杂步骤的独立子代理;此外还有确保会话一致性的钩子,以及用于访问代码仓库外资源的MCP功能。各部分职责互不重复。
先了解术语
- 智能体。一种能够打开文件、执行命令并独立完成多道步骤的AI系统,因此它的功能不止于回答问题。
- 规则文件(
AGENTS.md)。智能体在会话开始时会自动加载的固定规则。这是一种开放标准,可在不同工具间使用,不依赖特定供应商。可将其视为每个人都应已了解的员工手册。 - 技能(工作流)。仅在出现特定类型任务时才会加载的指令,就像点特定菜肴时会拿出的食谱一样。
- 子智能体。为某项任务单独启动的智能体副本,它在独立的上下文中工作,完成后会返回总结结果。
最初出现的问题
最早的基于规范的工作流缺少了这些功能。整个项目在仓库根目录下只有一个Markdown文件,其中包含了规则和流程,并试图按顺序引导智能体完成每一步操作。当时没有子智能体、钩子功能或强制性关卡,仅有建议性的操作顺序。
有一段时间这种情况还能维持。然而一旦会话时间变长,文件顶部的规则大约在第三个执行步骤时就会脱离当前上下文,代理便开始在不告知的情况下即兴应对。发现、规范与执行共享同一个界面,而最旧的指令首先受到影响。
其他仓库的团队也遇到了同样的问题。有一个更先进的团队采用了将规则、工作流程与执行分开的处理方式,并使用会话钩子来防止上下文压缩在任务进行中悄悄删除指令。其核心结论是不要再将“代理的指令”视为一个整体——实际上它包含三个部分,各自有不同的生命周期和功能。
三层结构,各有所属
- 第一层:永久性规则:
AGENTS.md,始终存在
规范驱动型技能规则
规则文件中包含了必须遵守的阻塞工程规则,同时还包含项目配置文件,用于记录每个团队的设置:命名规范、实现方式、基础分支、CI系统等信息。每次会话开始时都会加载该文件,这样就无需依赖代理主动去查找规则,这些规则会在第一条消息发送前就已准备好。由于配置文件是独立的,其他团队无需进行分支复制即可使用该插件。
工作流程
该流程被编码为一种技能,由智能体在用户请求时调用。当出现“修复错误X”或“开发功能Y”之类的表述时,或者通过 Cortex Code 中的 /dbt-spec-driven:spec-driven 命令明确触发时,该流程便会启动。它会根据意图(功能、错误、代码重构、独立审查或独立文档)进行路由,并协调各个阶段的工作。
有一个设计决策尤为重要:该技能从不重复阐述规则,而是指向 AGENTS.md 文件。这一选择解决了大部分原有的上下文问题,因为规则不会在两个地方出现不一致的重复版本。
子智能体
有五项任务所需的上下文量极大,若在主线程中执行,将会挤占真正需要处理的工作:discovery、test-author、output-validator、peer-reviewer以及ci-interpreter。每项任务都在独立的上下文中启动,完成一项具体任务后,仅返回包含关键信息的结构化报告。
其核心理念在于:上下文是一种有限的资源,而非无穷尽的存储空间。以discovery为例,它可能需要读取数十个模型文件并追踪其来源关系。若在主线程中处理,意味着在实现代码之前,一半的上下文资源就已经被用于处理那些后续并不需要的文件。对于体积小、计算成本低的模型而言,discovery更为合适,因为读取和总结信息所需的计算能力相对较低。
钩子
文件 hooks/hooks.json 会自动触发三个钩子,无需任何代理程序的配合。其中一个在会话开始时加载 AGENTS.md;另一个在上下文压缩前发出警告,避免重要内容被悄悄删除,而这正是第一个版本存在的缺陷;还有一个会在会话结束时添加会话记录。
每个钩子都提供对应的 bash 和 PowerShell 版本。Cortex 会自动运行与操作系统匹配的版本,另一个版本则不会被执行且不会产生任何异常。使用不同操作系统的团队无需进行针对用户的配置。
MCP 与 Jira 的连接
如果“将规格重新发布到工单”意味着要手动在终端和 Jira 之间复制文本,那么所有这些设计都将失效。此时需要通过两个 MCP 服务器来连接工作流程。
Atlassian MCP是不可或缺的工具。会话启动时,discovery子代理会使用它来读取工单,而在指定需求阶段则用它将编号后的需求重新发布到该工单上。这样一来,需求规格就会与实际工作内容一同保存,而不会消失在聊天记录中。
目前:Notion MCP的作用相对较小。当某些内容需要比PR描述或代码仓库更持久的存储方式来记录时,比如端到端流程,就会使用它。总体而言,MCP使得规则、工作流程及子代理能够与代码仓库之外的各种对象进行交互。今天可能是工单,明天则可能是BI平台或Teams频道。
整体概览
用户提问称,技能路径和工作者会跑到后台运行。每个工作者都会返回报告,而不会将其文件放入主线程中。Hooks和MCP会封装处理流程而不嵌入其中:它们负责加载规则,在压缩前发出警告,最后将结果传递给Jira。
改进之处
- 主线程能够专注于决策制定,不会被大量文件产生的处理结果所拖累。
- 由于只存在一个副本,规则不会丢失。
- 在会话期间进行压缩时,必须先发出警告,否则不会丢失任何内容。
这一经验不仅适用于dbt。任何使用AI代理处理真实代码库的人,很可能都会采用“一个文件处理所有事务”的模式,而这种模式往往会出现同样的问题:会话时间越长,最初的指令就越容易被挤掉。