数据研发Multi-Agent架构的Harness工程实践

一个让人尴尬的常见场景

不知道你有没有过这种体验：花了两周搭了一个数据研发Agentdemo，给老板演示的时候那叫一个丝滑，用户提个需求，Agent自己分析、写代码、跑测试，五分钟搞定。老板看完一拍大腿说"上！下个月就让团队用起来！"。

然后你信心满满地把这个东西交给团队，第一天就出事了。同事甲说："我让它做个简单需求，结果它跳过了关键确认步骤直接写代码，写出来的东西完全跑偏。"同事乙说："它把上一个需求的字段名带到这个需求里来了。"同事丙更绝："我让它修一个小bug，它把整个表重新设计了一遍。"还有同事追着说各种问题："产出表PK不唯一、表命名不符合规范、线上代码注释和参数被清空了、线上代码改出了bug、产出代码语法不通过"等。

你一查日志，发现Agent确实"理解"了需求，"完成"了任务，代码看起来"很美"，每一步看起来都"合理"，但合在一起就是不对。最要命的是，下次同样的场景，它可能又是另一种错法，你连复现都复现不了。

这种感受，我相信做过Agent的人都不陌生。

真正的核心问题

所以问题到底在哪？我们慢慢琢磨明白一件事：Agent能跑，不代表能用；能用，不代表可信。

"能跑"是说在理想路径上，输入A能给出输出B，demo阶段都能做到。"能用"是说面对各种乱七八糟的真实输入，Agent不会跑偏、不会偷懒。"可信"是说出了问题不会崩、你能查、能改、能避免下次再犯，团队敢把它放在关键流程里。从能跑到能用，再到可信，中间隔的不是模型能力的差距，而是工程能力的差距，把同一个模型给两个不同的团队用，做出来的东西仍可能天差地别。

这就是数仓场景里AI提效最难的地方。「能写出大致正确的SQL」和「能交付一张生产级数仓表」之间，差着一整个工程体系。前者是模型能力问题，后者是Harness问题。

这个问题的本质，是LLM的context压缩机制天然不擅长保持长程约束。临时口头说的口径、规范、约束，会随着token接近上限被压缩进摘要里失真甚至消失。而数仓场景对长程约束的依赖远比一般领域大——一条「金额字段统一用DECIMAL(22,6)」的规约，可能要在30轮对话之后还能被严格遵守；一个「ds分区必须按yyyyMMdd字符串」的约定，可能要跨越「需求解析→模型设计→SQL编写→测试→上线」5个阶段都不能漂移。

既然LLM自己抗不住，那就只能把「抗」这件事从模型里挪出来：用一套确定性的工程框架托住。这就是Harness的核心命题——LLM负责理解和创意，Harness负责约束和验证。

要理解Harness的位置，得先看清楚我们这几年是怎么一步步走过来的。

第一代：Prompt Engineering——把话说清楚

最早大家研究的就是prompt怎么写。各种技巧层出不穷：扮演专家、思维链、few-shotexample、把任务拆成步骤，一时间"prompt工程师"成了热门职业。

这一代解决的核心问题是：怎么让模型理解我想要什么。

在那个阶段，模型本身的指令遵循能力还不够强，你不字斟句酌地写prompt，它就会跑偏。所以prompt engineering是必要的。

但prompt engineering有个天然的天花板：它假设你只跟模型聊一次，问完即走。一旦任务复杂、需要多步、需要外部信息，光靠prompt就不够了。你prompt写得再好，模型脑子里没有相关知识，它还是只能瞎编。

第二代：Context Engineering——喂对信息

于是大家开始研究怎么给模型"喂料"。RAG火了起来，向量检索、文档切片、重排序，这一套组合拳成了标配。再往后发展，工具调用、functioncalling、MCP协议，让Agent能主动去拉数据、调API。

这一代解决的核心问题是：怎么让模型在做决策时，看到该看的、不被无关信息干扰。

Context engineering比prompt engineering高了一个维度：它不只是优化"怎么问"，而是优化"问的时候手里有什么牌"。这一阶段我们也确实看到了Agent能力的飞跃——以前不能做的现在能做了，以前要人工查的现在Agent自己能查。但是，仅靠这两代还是不够。你会发现：

• Context给得再好，Agent依然会在某些路径上犯低级错误。

• 同一个需求跑十次，可能有八次都对，剩下两次错得离谱。

• 出了问题之后，你不知道是哪一步出的，更不知道怎么防止再犯。

这些问题，都不是再调一调prompt、再多塞点context能解决的。它们是系统性问题，需要系统性方案。

第三代：Harness Engineering——让Agent可控制、可预测、可信任

Harness这个词原本是马具的意思——你让一匹烈马拉车，光有马是不够的，还得有缰绳、笼头、车辕、车架，把马的力量约束在你想要的方向上。Harness Engineering要解决的核心问题是：怎么让Agent的能力以可控制、可预测、可信任的方式发挥出来。这里有几个关键点：

• 可控制：你能在关键节点介入，而不是Agent自顾自一路狂奔

• 可预测：同样的输入，行为模式应该是一致的，不会今天这样明天那样

• 可信任：输出结果必须合理；出错之后能从某个中间点继续，而不是整个流程作废

如果说Prompt Engineering是问"怎么把话说清楚"，Context Engineering是问"给Agent看什么资料"，那Harness Engineering问的是更进一步的问题：Agent到底应该怎么工作。

核心公式

Harness工程实践相关文章一直在强调一个公式：Agent=Model+Harness

Model是能力的来源，Harness是能力的释放方式，可以理解为Agent中除了基础模型，其余皆为Harness。模型决定了上限，Harness决定了下限。模型能力具有“天花板效应”，长时任务更具备“裸模型陷阱”和“累积误差”。

这两年模型能力的进步太快，让很多人产生了一种错觉，觉得"等模型再强一点，所有问题都能解决"。这是不对的。模型再强，没有Harness兜底，你照样不敢把它放进生产系统，Anthropic在实测中发现即使顶尖模型Opus系列在跨上下文任务中仍会出现看到部分进展就宣告完成不验证的情况。反过来，Harness做得好，哪怕模型差一点，你也能跑出靠谱的产品。

其实小到Claude.md或Agent.md文件，大到Qoder、Claude Code、Codex等企业生产级Agent系统，我们都可以说有Harness工程理念的存在。作为一种工程范式，Harness概念非常广泛，我们难以概括其全貌，这里我们只分享下自己的实践经验。

整体架构图

Harness工程应该怎么设计，才能保障Agent的能力可控制、可预测、可信任呢？下面我们结合业界公开理念和自己的数据研发Multi-Agent实践，将其中应用到的Harness工程理念拆分成核心三大分层和六大支柱来详细讲解，整体架构图如下：

核心分层

我们按照Multi-Agent执行生命周期将围绕它的Harness工程拆分为身份层（Agent执行前的静态身份与约束定义）、执行层（Agent执行时动态决策的执行路径、加载上下文、门禁检查、状态追踪、故障恢复等）和进化层（Agent执行后的经验沉淀与进化），层级关系如下：

• 身份层→执行层：身份层圈定Agent"能力边界"，执行层在这个围栏内运转，身份层告诉执行层"谁干什么，哪些路能走，哪些路不能走"。

• 执行层→进化层：执行层产出执行过程中间产物并进行质量门禁检查，当执行出故障或暂停时，依赖状态信息决定"退到哪重来"；每次故障恢复，都是一条"错误样本"，进化层吃进这些信号，通过经验升级沉淀为知识。

• 进化层→身份层：知识进化的产出最终落地为：更精确的身份定义、更严格的行为约束体系，下一轮执行，身份更明确、边界更清。

一句话总结递进逻辑：身份定形→可靠执行→进化增强→身份增强（螺旋上升）。去掉身份层，系统不知道该怎么工作；去掉执行层，过程不可控、产出不可信；去掉进化层，系统永远停在原地。

核心支柱

我们根据MECE原则拆分出Harness的核心六大支柱，依托三大分层，它们形成了一条闭环反馈链路。我们总结了六类可能导致系统不可预测、不可控、不可信的问题，每类问题对应一个支柱，缺失任何一个支柱都会导致一类不可接受的系统性故障。如果去掉Identity，Agent不知道自己负责什么；去掉Orchestration，Agent不知道自己该干什么；去掉Context，Agent不知道关注什么；去掉Gate，过程产出不知道是否可信；去掉Recovery，错误不会被系统化地恢复；去掉Evolution，错误只是被处理了但没留下痕迹。

借助核心六大支柱，我们是如何保障Agent运行可控制、可预测、可信任的：

• 可控制=能力边界+门禁检查：Identity出厂就焊死了"能做什么，不能做什么"，Gate在关键节点设卡——"进得去也出得来，人随时能拉闸"。

• 可预测=确定路径+确定输入：Identity确保"同一个角色永远做同一类事"；Orchestration确保"给相同需求走相同步骤"；Recovery确保"任何时候都能回答做到哪了"；Context确保"每步决策看到的信息是确定的、可复现的"。

• 可信任=质量兜底+持续改善：Gate保证"出不了大错"；Recovery保证"错了也不会崩"；Evolution保证"犯过的错不再犯，越用越好"——信任=当下靠谱+未来更靠谱。

本章我们详细介绍下六大核心支柱，每个支柱我们单独会讲两件事：这个支柱是什么→我们具体怎么做的。

理论概念

是什么：清楚定义Agent"是谁，负责什么"，"能做什么"和"绝对不能做什么"的边界，做的时候按什么流程。主要包括角色定义和行为约束体系两部分，角色定义就是Agent的身份说明，行为约束则是Agent执行时的规则或限制。

举个例子，你让一个新员工做事，最怕的是什么？最怕他什么都没做过，你给他一张白纸他无从下手；也最怕他什么边界都不知道，可能闯出大祸。最好的状态是什么？是他清楚知道："这件事我必须做，那件事我绝不能做，中间这一大块我可以自由发挥。"边界清楚之后，他反而能放开手脚。同理，给Agent的约束越含糊，它的输出越不稳定。一旦把"必须做什么、不能做什么、可以怎么做"写清楚了，Agent的表现立刻就上来了。这背后的机制其实不难理解。模型本质上是在概率空间里采样，约束越清楚，采样空间越聚焦，输出的方差就越小。约束含糊，采样空间巨大，今天采到这边明天采到那边，结果当然不稳定。所以约束不是为了限制能力，而是为了让能力稳定地释放出来。

为什么重要：这是所有Harness的基础。Agent的"能力"不是它脑子里的，而是你定义出来的。你定义得清楚，它就发挥得清楚；你定义得含糊，它就乱发挥。

怎么落地：每个Agent要有明确的"能力说明书"和"行为约束体系"，里面至少包含：

• 身份定义：这个Agent的角色定位

• IO定义：输入输出的格式

• 能力说明：可以使用哪些MCP&Skill工具

• 行为约束：处理任务的标准流程、哪些事情绝对不能做、约束如何划分层级

写这部分内容的过程，本身就是一次梳理。你会发现很多原以为"理所当然"的事情，写下来才发现根本没想清楚。

我们具体怎么做

第一件事：架构选型——Orchestrator+Specialist

我们采用了Orchestrator+Specialist（协调者+子专家）的Multi-Agent架构。为什么不让一个Agent干所有事？一个全能Agent，从头到尾把活干完。结果是全程上下文挤在单个会话中，越来越乱，模型注意力被高度稀释、Agent能力边界越来越模糊、出问题不知道是哪一步出的，就好比几年前你输入一段提示词让大模型返回输出，它中间做了太多杂七杂八的事情，即使有深度推理，最后的结果也可能与思考过程无法匹配，这导致结果难以追溯与解释。我们的数据研发"协调者Agent+子专家Agent"架构如下：

• 协调者Agent：不写代码、不出方案、不做深度推理工作，只负责调度、把关、评审、汇报

• 多个子专家Agent：有明确职责，例如需求拆解、方案设计、SQL开发、测试验证

第二件事：职责划分——角色定义与能力边界

协调者身上叠了6个显式定义的角色身份——调度员（决定派谁去干活）、澄清员（跟用户对齐需求细节）、审查员（评审每个Agent的产出）、门禁员（决定能不能进下一阶段）、汇报员（向用户同步进度）、重试员（出错时的回退处理）。这6个身份的职责边界、触发条件、不可越界的事项都必须明确声明。

四个专家Agent各自只暴露自己领域的能力——需求拆解Agent不写方案只出需求拆解文档、方案生成Agent不出SQL只出方案、代码生成Agent不擅自改方案只生码、测试Agent不越权修复bug，每个Agent只分配对应的MCP和Skills。这种"严格分工"带来的好处是：每个Agent的能力定义都很薄，反而稳，因为屏蔽了协调者的上下文，做事情更加专精化，只需要被协调者调用，在独立运行窗口中关注自己的输入内容、流程规范、约束体系等。

协调者的角色定位特别重要：它不是"老板"，而是"项目经理+质检员"。它不能下场写代码，否则它就退化成了一个全能Agent，整个分工就崩了。

第三件事：行为约束——把"什么绝对不能错"和"什么最好别错"分开说

关于如何通过行为约束体系保障Agent可控执行，我们设计了一个三层金字塔结构：

最顶层：超级红线。数量很少，每一条都是"违反了就是严重事故"。比如不得跳过用户审查、不得编造数据、不得越界访问其他Agent的私有空间等。没有红线时，Agent经常"好心办坏事"。约束系统必须有相对"硬性"的部分。全是软约束的系统，Agent会用"我觉得"绕过去，这是用户难以接受的。硬性红线要写在最显眼的位置。举几个常见例子：

• Human in the loop：阶段切换必须有用户确认（不能Agent自己觉得OK就跳过）

• 禁止编造数据：知识库未检索到知识必须如实回答（不能Agent根据通用知识编造）

• 禁止违背职责划分：协调者禁止直接产出方案或SQL代码（必须调用子专家Agent）

• Sub Agent隔离：子Agent在独立会话运行（防止各环节上下文污染）

• 避免认知污染：信息分舱，物理文件隔离（Agent只管自己的约束，不能用别人的教训约束自己）

• 禁止跳过重要步骤：我们希望数据方案可以通过中心化平台管理，但是Agent经常跳过方案上传的步骤，后来我们引入红线，把那些"绝对不能跳过、绝对不能擅自决定"的事情明确写出来，跳过次数明显减少

中间层：错误记录。历史教训总结。这是系统进化的燃料，每次有人指出"这里你做错了"，就记一笔。错误记录是需要引起重视的，告诉Agent"以前在这个地方栽过跟头，注意一下"。

最底层：操作规则。比如知识库检索流程、产出文档模板、错误处理的标准流程等。规则太多，Agent会"选择性遵守"。如果把各种规则、各种规范、各种最佳实践，洋洋洒洒上万字塞给Agent，结果是Agent对规则的遵守度反而下降了，因为Agent的注意力被稀释了。它没办法对每一条都同样重视，于是开始"选择性关注"——某些条目它当回事，某些条目它就忽略了。信息密度不能太高。重要的事情必须脱颖而出，不能淹没在大量"也很重要"的信息里。

为什么要分层？如果什么都是红线，Agent什么都不敢做；如果什么都是规则，Agent又会"选择性遵守"。分层的本质是信号强度的分级。把所有规则都喊得震天响，结果就是Agent对所有规则都麻木——这跟人是一样的。这就引出了我们后来的分层设计：把频繁踩坑的少量红线单独拎出来，放在最显眼的位置；中等重要的错误记录引起重视；建议性的规则作为补充信息。这种"红线少而精、错误实时记录、规则持续沉淀"的结构，是我们反复调整后稳定下来的形态。

约束体系还有一个重要机制：升级机制。一条规则如果被违背，就记录为错误；一类错误如果反复出现，就升级为红线。反过来，红线如果证明过严了，也可以降级。整个体系是动态演进的。

理论概念

是什么：定义任务按什么方式、什么顺序执行。

为什么重要：如果说Identity定义了"谁有什么能力"，那Orchestration就是定义"怎么把这些能力由点到面地串起来"。核心原则是：既要可控，也不能慢。可控不是用慢来换的——慢得不像话的Agent系统，再可控也没人愿意用，所以流程调度一定需要精细化的设计。

怎么落地：流程编排尽量考虑从优化用户体验、提高执行效率入手：

• 机器静默执行：埋点、版本检查、MCP依赖配置、输入识别全部定义为启动时自动执行，不问用户不等确认

• 路径按需加载：长程任务应该支持按需自动路由，根据用户的需求复杂度自动选择起始点和执行路径

• 无依赖就并行：任务显式声明输入输出，充分利用输入输出无依赖关系的多子专家Agent的并行能力

• 修改匹配重量：流程执行应该提前定义好分级修改标准，轻量、中等、重大改需要区别处理，禁止一刀切

我们具体怎么做

第一件事：前置依赖自动完成——机器orAgentor人工

为什么要做这么多流程自动化工作？这个主要是考虑用户体验优化，自动帮助用户检查MCP依赖、记录日志、检查版本、判断需求信息、执行路径路由等，都是为了把所有"机械的、有确定规则的、非高度依赖Agent智商参与的"环节，全部下沉为自动流程。Agent只在"需要判断"的地方介入，"不需要判断"的地方一律机器自动化，机器脚本自动化不占上下文、不消耗token（不死脑细胞）、执行效率更高。这个原则我们叫做："机器干机器的事，Agent干Agent的事，人干人的事"。用户进来的第一秒，下面这些事全部自动完成，不打扰用户：

• 自动记录调用埋点：每次Skill执行时触发自动埋点，记录Skill调用情况

• 自动检查依赖配置：确保当前MCP连接正常，避免过程中报错打断核心流程

• 自动钉钉交互提醒：在关键Checkpoint（方案评审、SQL评审、上线发布）前自动发钉钉到用户，避免用户长时间等待时错过确认节点

• 自动版本检查更新：每次执行先通过脚本比对本地与SKILL市场中SKILL对应版本，若开发者发布最新版本，发现差异立即覆盖更新，避免用户拿着旧版本跑今天的需求，还一直反馈上个版本存在的问题

• 更新后自动初始化：版本更新后自动重建项目符号链接指向用户本地历史产出文件（对Qoder来说每个人产出文件是存储在个人PC的，中心化管理平台可忽略，初始化可以避免用户每次迭代都手动迁移历史产出文件）、刷新MCP配置（新版本新MCP自动添加）等，让"更新"对用户完全透明

• 自动判断输入类型：用户贴进来的可能是需求链接、钉钉文档、纯文本需求、甚至是一句话自然语言，我们不让用户选"输入类型"，而是用规则匹配自动识别

• 自动判断需求信息：根据需求关键词自动确认需求类型（新增or迭代）、业务域（自营or行业）、项目空间、数据域（交易or供应链or客服等）、维度摘要、核心指标、需要检索的资产知识库等，用户一次性批量确认修改，减少交互次数

这层的设计原则是："用户不应该为流程本身花一秒钟"，通过机器执行（自动埋点、依赖检查、钉钉提醒、版本更新、初始化）、Agent判断（输入类型判断、需求信息判断）与人工批量审查把关三级协同，最大化流程执行效率。

第二件事：多执行路径分支——链路模式or单点模式

很多Multi-Agent系统有个通病——只有"全流程"一种入口。你哪怕只想做一件很小的事（比如已经有方案了，只需要写个SQL），也得从头走完整个链路。

如果每次都得从头走流程，用户会觉得"这玩意儿真墨迹"，用着用着就不想用了。核心原则是：链路调度保证质量，单点调度保证效率。两者不是对立的，而是同一套能力的两种使用姿态。

我们的做法是：每个专家Agent既能被协调者统一编排（链路模式），也能被用户直接调用（单点模式）。

• 链路模式：适合明确知道"我需要走多步"的场景。我们做了三档自定义执行路径，用户可以通过触发词自定义路径，也可以让协调者Agent自动判断（PRD链接默认FULL、口头需求默认快码）：

• 全链路模式：新需求来了，从需求拆解→方案设计→SQL开发→测试验证→发布部署，完整走一遍

• 快案模式：需求已经很清晰了，跳过需求拆解直接出方案写代码做测试

• 快码模式：用户口头描述就很清楚，直接开始写代码做测试，无需任何方案设计

• 单点模式：适合明确知道"我就需要这一步"的场景。用户直接调用某个Agent，快进快出，例如：

• 单独调用SQL开发专家写段代码，适合人工简单审核下就能交付的需求，或已有详细数据方案的需求

• 单独调用方案设计专家撰写数据方案，适合用户扒别人复杂代码逻辑的场景，转为数据方案更容易理解

这两种模式能并存，关键在于一个设计原则：每个Agent的输入输出必须自包含。就是说每个Agent不能依赖"前面有人帮我准备好了上下文"才能工作。它的输入必须是明确的、可以独立提供的。这样它既能从协调者那里接收标准化的任务指令（链路模式），也能直接从用户手里接收原始需求（单点模式）。

如果你的Agent设计成了"必须拿到上游Agent的特定格式产出才能干活"，那它就没法单独使用——这是过度耦合的信号。如何设计还有一个好处：单点模式天然是最好的"单元测试"环境。你想调试某个Agent的行为，直接单点调就行，不用每次都走全链路。开发阶段这一点特别重要。

两种模式底层共用同一套Skill定义和经验库，所以单点模式下Agent积累的经验也会反哺到链路模式——不存在"两套系统分裂演进"的问题。

第二件事：多专家并行调度——无依赖并行or有依赖串行

Multi-Agent协作不能纯串行，那样太慢，但也不能瞎并行，会出依赖问题。我们的原则是：有依赖关系的串行，没依赖关系的并行。这话好说，难做的是怎么判断"有没有依赖"。我们的做法是每个任务声明自己的输入和输出，决策依据是显式的，不是凭感觉。

举个例子，一个需求可能涉及三张数据表的开发，这三张表之间没有依赖关系，那它们可以并行开发，我们做了多码专家并行：当一个需求涉及多张表且表与表之间不存在依赖关系时，协调者会把任务拆成N个子任务，并行启动N个代码生成专家同时写代码——比如需要3张ADS表，3个代码专家并行出代码，比串行快3倍。

第四件事：修改流程自适应——小题大做or对症下药

我们最早所有的产出文件修改都走重流程：哪怕只是改一个字段名、调一个注释，也要重新调用SQL开发专家。流程是规范了，但效率低得让人抓狂。后来我们想明白了：流程不是越规范越好，要根据修改的影响范围来匹配流程的重量。一刀切最容易实现，也最不实用。于是修改被分成三级：

• 轻量改（命名、注释、格式）：无需任何专家特有知识，主Agent直接动手不调用子专家，几十秒搞定

• 中等改（逻辑调整、字段变更）：涉及专家领域知识，需调用子专家Agent，附上一份精确的修改点清单

• 重大改（架构变更、表重设计）：涉及上游多环节变更，需要重新走完整流程

三级匹配三种节奏，效率立刻就上来了。原来要几分钟的小修改，现在几十秒就完事。

理论概念

是什么：在Agent的每一步工作中，给它看什么、不给它看什么。

为什么重要：上下文窗口是有限的，无关信息会干扰Agent的判断。给得太少，它信息不够；给得太多，它会被淹没甚至误导。

怎么落地：

• 流程阶段切分：不同阶段需要的信息不同，不要一锅端

• 用摘要替代全文：长文档不要直接喂，先压缩成要点

• 渐进式加载：通过路由调用主动获取，而不是一次性给所有

• Spec文件驱动：Agent之间的信息传递通过结构化文件，而不是"对话历史"

很多人不重视上下文管理，结果就是"上下文污染"——前面阶段的临时讨论、被推翻的方案、调试中的中间结果，全都混在历史里，Agent做下游决策时就被这些噪声带偏。

我们具体怎么做

第一件事：流程阶段切分——只有跑到那一步，才读那一步的东西

整个数仓研发链路被切成了多个phase文件，协调者根据用户输入判断走哪条路径（全链路/快案/快码），然后只加载对应阶段的phase文件。比如用户说"快码模式"，系统就只加载后面的内容，前面需求分析、方案设计那些东西根本不会出现在上下文里，另外每个阶段的文件只在加载到该阶段时才被读取，时刻保持最深刻的记忆。

第二件事：阶段内容摘要——每个阶段结束时强制压缩成CP检查点摘要

我们设计了一套叫"CP检查点（Checkpoint）"的机制。比如需求澄清完成后，不是把整段对话记录传给下游，而是强制压缩成一段固定格式的摘要追加到状态机文件中："结论：需求澄清完成，共澄清N项；传递给下游的关键信息：需求类型=新增、统计粒度=商品、业务线；待关注事项：无"。就这么几行核心决策内容，下游的专家读到这个检查点摘要就明白需求澄清做了啥，不需要回溯几十轮对话历史即可保持最新记忆。

这个限制看起来"信息更少"了，但实际带来三个好处：上下文窗口干净（不会被前面阶段的废话淹没）、信息密度高（摘要都是精华）、强迫每个阶段的产出必须自包含（不能留一堆"前面说过了"的隐含前提）。这种做法逼迫每个阶段的产出质量都要高——因为后续阶段不会回头看你的草稿，只会看你的成稿。

第三件事：渐进式加载——涉及到哪类规范才读哪个文件

渐进式加载，Skill的标准设计规范不必多说。举个例子，我们将SQL开发专家拆成了"核心层+详情层"两级结构。核心层是必读的，里面只放超级红线的一句话摘要和文件路由链接。详情层按类别拆分，例如SQL代码格式化规范、DDL建表规范、GROUPING SETS规范、JOIN子查询规范等。加载规则写得很明确——"涉及JOIN/子查询/多表关联→读JOIN子查询规范"、"涉及GROUPING SETS/多维度聚合→读GROUPINGSETS规范"、"涉及新建表/DDL→读DDL建表规范"。只有实在判断不了任务类型时，才加载全部详情。

为什么这么做？因为完整规范加起来内容太多，一个只做简单单表查询的任务根本不需要知道GROUPING SETS怎么写，硬塞给它反而会干扰核心逻辑的生成质量。同理，这个理念可以类推到所有规范设计中。

第四件事：Spec文件驱动——Agent之间靠文件传活儿，不靠对话历史

Multi-Agent协作有个绕不开的问题：Agent之间怎么交流？最直觉的方式是消息传递——AgentA说一段话，AgentB接收，再回一段话。这种方式做demo的时候没问题，一上规模就出事：

• 上下文太长：Agent之间的对话历史把窗口塞满

• 不可追溯：事后想知道"当时为什么这么决策"，无归档文件

• 不可审计：一段对话过去了就过去了，没办法review

改成Spec文件驱动后Agent之间不直接对话，而是通过预定义Schema的结构化文件交换信息，协调者将状态追踪文件、任务指令文件、需求澄清文件和上游产出文件路径等传给下游子专家执行。每个Agent单独写文件，下游Agent要用的时候去读文件，协调者只传递文件路径。

这个改动带来的好处出乎意料地大：

• 可追溯：任何决策都能回溯到具体文件的具体段落

• 可审计：所有核心产出都在文件中，事后review一目了然

• 可恢复：Agent挂了或流程中断了，文件还在，从断点继续就行

• 可解耦：上游Agent的实现细节下游不关心，只关心文件内容

• 可隔离：每个Agent只读自己该读的文件，不会被无关信息污染

这个设计其实和Unix/Linux哲学一脉相承——"一切皆文件"、"小工具组合"。Agent作为新型的"小工具"，组合方式依然可以借鉴这套老智慧。

理论概念

是什么：Agent的输出到底好不好，要有衡量标准，而且最好能自动衡量。

为什么重要：没有检查度量就没有改进。你说"Agent最近变好了"，凭什么？凭感觉吗？感觉是不可靠的。

检查评估和上面的Identity行为约束有什么区别？Identity行为约束是说"如何做、什么不能做"（前置约束），Gate是说"做出来的东西达标吗"（事后验证）。一个管准入，一个管验收。两者结合，构成完整的防御体系。

光有前置约束（红线、规则、流程）是不够的，因为再严的规则，Agent也可能因为某些边缘情况绕过去。所以你还需要事后验证——做完了之后再看一遍，确认结果符合预期。光有事后验证也不够，因为有些错误一旦犯下就很难挽回，比如把生产数据删了，所以前置约束必不可少。这种"两层防御"的思路在传统软件工程里其实早就有了——编译期检查+运行时检查、accesscontrol+auditlog，本质都是一回事。

怎么落地：

• 定义通过标准：每个关键节点有明确的"通过标准"，只有达成才视为通过

• 标准需要分层：硬性标准（必须达到）、软性标准（最好达到）

• 自动检查优先：能自动检查的就不要靠人眼

• 人工评估标准：评估的人不一样，结果也应该尽量一致，有规范的评估事项

我们具体怎么做

第一件事：门禁检查点——在关键路口设卡，过不了就不许往下走

我们让协调者Agent在每个阶段结束后都要进行回顾，确保达成通过标准，常见门禁检查点：

• MCP前置可用性检查（工具能不能用？别到了要用的时候才发现连不上）

• 需求类型与项目空间确认（确认需求分类对不对、该去哪个项目空间）

• Agent调用前的ask确认（协调者准备派活之前，先跟用户确认一下理解对不对）

• Agent产出后review（Agent交活后，协调者逐项检查产出质量）

• 上游产出存在性验证（要进下一阶段了，上游该做的事情是否都做了）

• 阶段切换前的用户确认（要进下一阶段了，必须用户点头）

• SQL语法校验（代码写完了，先跑一遍语法检查）

• 发布前最终确认（要上线了，最后过一遍）

第二件事：强制检查项——取消AI"我觉得不需要检查"的权力

强制检查项意思是"哪怕Agent觉得没必要也必须执行"。为什么要这么强硬？因为我们发现Agent有一个"坏习惯"——当它觉得"这次情况很简单"的时候，会主动跳过某些检查步骤。但"简单"是它自己的判断，而它的判断经常是错的。所以我们干脆取消了它"决定要不要检查"的权力——必须检查，没有"我觉得不需要"的余地。

这里还有个配套做法：每个阶段产出之后，先由Agent进行自动化的格式检查（必填项、引用是否合法、结构是否规范），过了之后再进入人工评审。人工评审也有checklist，不是"看着差不多就行"。

核心理念：可控，比聪明更重要。一个不可预测的AI，能力再强也没法用，因为你不敢把任何重要的事情交给它。一个可预测的AI，哪怕能力一般，你也敢慢慢把更多事情交给它，慢慢扩展它的边界。所以Harness不是给AI戴枷锁，而是给AI建立信用。可预测了才有信用，有信用了才有更大的舞台。

第三件事：生成评估分离——自己不能既当运动员又当裁判

写东西的人和判断"写得行不行"的人，必须是两个角色。为什么？因为不管是Anthropic还是OpenAI等业界内顶尖厂商都达成Generator+Evaluator分离的共识，与人考试一样，Agent几乎都觉得自己生成的内容质量"挺好的"，如果不好它肯定也不会生成。这不是态度问题，而是认知盲区：生成者对自己的产出天然有合理化倾向，会下意识为自己的选择找理由，而不是找问题。

所以我们把职责拆开了：子Agent专家负责埋头干活、交付产出；协调者Agent负责拿着checklist逐项验收。协调者没参与生成过程，没有"护犊子"的动机，看到问题就是问题，该打回就打回。

一个既生成又自评的Agent，等于考试时自己出题自己判卷，分数好看但没有参考价值。把裁判权交给独立角色，产出质量才有真实度量，信任才能建立起来。

理论概念

是什么：Agent正在做什么、做到哪一步了、之前的决策是什么、出问题了从哪儿恢复、怎么恢复。

为什么重要：复杂的数仓需求必然是多步的，多步就会有中间状态。没有状态追踪，你就只能"一步到底"，中间出任何问题就只能从头开始，在足够长的运行时间里，错误一定会发生。区别在于错误发生时，系统是优雅降级还是灰飞烟灭。

怎么落地：

• 任务有明确的状态机：及时存储当前状态、状态合理划分、状态流转记录（时间、原因、决策依据）

• 中间产物要持久化：类似于Spec文件驱动，不能只放在会话和内存里

• 故障合理分级：可重试的、需要回退的、必须中止的，处理方式不同

• 断点续接、异常回滚：任务异常停止或失败之后，能从最近的检查点恢复

我们具体怎么做

第一件事：执行状态存储——干到哪儿记到哪儿，断了不用从头来

我们定义了12个明确的状态枚举值，对应任务在链路模式中从"需求接收"到"完成"的全流程节点：

→REQUIREMENT_RECEIVED（需求接收）→REQUIREMENT_ANALYZING（需求分析中）→REQUIREMENT_ANALYSIS_REVIEW_PASSED（需求分析评审通过）→SOLUTION_GENERATING（方案生成中）→SOLUTION_REVIEW_PASSED（方案评审通过）→SQL_DEVELOPING（SQL开发中）→SQL_REVIEW_PASSED（SQL评审通过）→TESTING（测试中）→TEST_PASSED/TEST_SKIPPED（测试通过/跳过）→DEPLOYING（发布中）→COMPLETED（已完成）

每个任务在专属的需求目录里维护一份状态追踪文件，状态变更都被显式追踪和记录。任意时刻终止流程，下次恢复时先读这份文件以及上游产出的Spec文件，几秒钟就能回到上次的断点。不需要重跑任何已完成的步骤。状态追踪文件除了状态变更记录，还有CP检查点摘要，核心文件路径等，是一份完整详细的日记本。

第二件事：故障分级——重试、回退、中止，三条路各走各的

我们针对不同复杂情况设置三档故障分级标准：

• 可重试：例如知识库未检索到增加TopK值加大检索范围、多个MCP工具重试调用、血缘分析工具超时自动降级为代码静态扫描分析等，保证自动重试一两次，可以实现异常自愈

• 需回退：例如数据方案设计不通过、代码测试验证不通过等，需要退回上一个稳定存档点重新调用子专家Agent，不是从头来

• 必须中止：例如需求理解根本性偏差、MCP依赖安装失败、知识库多轮检索失败，停下来坦诚告知用户"我搞不定，需要你帮忙"

第三件事：故障恢复——断点续接、异常回滚

协调者Agent身上挂着一个"重试员"角色，专职处理数据研发主流程异常恢复，不需要每个Agent都知道"出了问题怎么办"，而协调者保障流程可恢复最重要的便是状态追踪文件和上游产出Spec文件：

• 状态追踪文件：当协调者知道流程中断、上游产出异常、用户评审不通过时，就可以根据状态追踪文件判断当前流程在哪儿，需要调用哪个专家Agent重新干活

• 上游产出Spec文件：协调者重新调用专家Agent时知道有什么内容可看，给他看什么内容

理论概念

是什么：Agent犯过的错、踩过的坑，要有机制留下来，下次能用上。

为什么重要：人会成长是因为有记忆，Agent能力的可持续提升也得靠这个。模型本身没有跨会话的记忆，所有"经验"都得靠系统层面来沉淀。

核心理念：每犯一个错，就工程化一个解。

工程团队里大家都有这个习惯：出了bug，复盘，写到知识库里，下次注意。但人这玩意儿就是会重复犯错，靠"注意"是没用的。Agent也一样，你光在文档里写"Agent你下次别再这样做了"，它根本不看，看了也不一定记住，记住了下次不一定触发。

正确的做法是把这个错误工程化。什么意思？就是把它变成一个具体的机制——一条红线、一个检查、一个流程门禁、一个示例。让"避免再犯"这件事不依赖于Agent的"记忆"，而是依赖于系统的结构。

举个例子。我们一开始遇到过Agent擅自跳过数据方案归档的问题。最早的处理方式是改prompt，加一句"请务必注意数据方案写入存储介质"，没什么用。后来我们把这个改成了超级红线，写在最显眼的位置，并且在流程里加了一个显式的门禁，没收到确认就不能进入下一阶段，从那以后这类错误次数减少非常明显。

怎么落地：

• 结构化记录：格式化精简记录执行流程违规记录，逼出本质，拒绝流水账

• 实时触发：用户说"Agent你做错了"的那一秒就必须落库，不攒批不延迟

• 自动加载：Agent启动时强制加载，历史教训抬头可见，不依赖记忆力

• 约束迭代：反复出现的错误必须升级，踩坑踩多了就从"建议"变成"铁律"

我们具体怎么做

第一件事：执行流程违规记录——让错误成为系统进化的燃料

最早我们做Agent的心态是"要尽量让它别犯错"。后来发现这个目标本身就是错的——错误一定会发生，你能做的不是杜绝错误，而是让错误成为系统进化的燃料。

每个专家Agent都有自己的"踩坑记录本"。格式被严格统一为四列：

|递增编号|日期|一句话错误描述|正确做法|

"一句话描述"这条要求很关键——它逼迫Agent把问题抽象到本质，而不是流水账式记录"那天发生了什么"。你必须用一句话说清楚"错在哪"，这本身就是一次思维提炼。

第二件事：自学习机制——让知识像飞轮一样越转越快

很多团队的经验管理停留在"记下来就完了"。但记下来只是第一步，真正的价值在于：经验能被重复加载利用、能被提炼成行为约束，反哺约束体系。如果经验只是躺在文档里，它就是死的；只有流动起来，才能变成飞轮。

我们设计了三级驱动：

• 实时记录：当用户指出"你这里做错了"，对应Agent必须立刻结构化记录。结构化是关键——结构化才方便检索，加载利用。流水账式的记录等于没记。

• 自动加载：Agent工作时，自动把自己的经验库加载进上下文。它每做一步都"看着"历史教训，不是靠记忆力，而是靠工程机制强制回顾。

• 行为约束迭代：定期统计哪些错误反复出现。如果一条错误被触发多次，说明它的约束强度不够，那就升级为超级红线。升级决策由工程师做，但触发信号来自数据。

Harness Engineering虽然很重要，但我们觉得还没有形成体系化的标准，我们知道它是一套约束体系，但仍然很少有人能把完整的Harness工程范式讲透彻。同时，随着Loop Engineering、Self Engineering等新生概念涌现，我们不禁要思考Harness未来的发展路径，可能有两条：（1）成为AI时代的DevOps标准规范；（2）成为过渡性概念，沦为历史范式。

路径1：成为AI时代的DevOps

核心命题：Harness演化为一门持续存在的工程学科，类比DevOps之于云原生时代的地位。

• 持续积累的核心工程学科：Harness不再是临时性工具集，而是沉淀出方法论+标准+工具链三位一体的体系。就像DevOps从"运维自动化脚本"演化为涵盖CI/CD、IaC、SRE、可观测性的完整学科。关键标志：有教材、有认证、有岗位（Harness Engineer）、有社区共识。

• Agent系统的标准化构建与运维实践：Agent从"手工调教的玩具"变成"工业化生产的系统"，需要标准化的构建（Prompt版本管理、Skill模块化、Agent编排规范、评测基线）和运维（上线灰度、回滚机制、效果监控、故障定位、成本控制）。现实信号：当前已经出现LangSmith、AgentOps、PromptLayer等"Agent运维"工具的雏形，LangChain已正式定义了Agent Development Lifecycle（ADLC）标准框架。

路径2：成为过渡性概念

核心命题：Harness是模型能力不足时的临时补丁，模型变强后会被吸收消解。

• 被更强的模型能力直接替代：今天我们用Harness做的事（任务拆解、工具调用、记忆管理、流程编排），未来模型可能内化为原生能力。历史类比：早期NLP需要分词器、词性标注器、句法分析器层层堆叠，大模型出现后这些"管道"几乎全部坍缩进端到端模型。

• 成为历史性的技术补丁：Harness会像jQuery、Flash、AJAX框架一样——曾经必不可少，最终被原生能力取代，沦为技术史脚注。关键判据：当模型context足够长、推理足够稳、工具调用足够准时，外挂的Harness框架就失去存在价值。

我们的判断：两条路径不矛盾。短期坚定走路径一（积累工程能力，把系统做稳），长期准备路径二（保持模块化，让每个支柱都是可独立移除的）。不管最终走哪条路，现在积累的工程经验都不会浪费。