从Vibe Coding到Harness—— 一套大仓AI工程化实战

作者:fitchzheng、leoshli

一篇属于后端微服务 + 前端微应用大仓的 Harness 实战分享。 不讲理念有多重要,只讲我们这一路是怎么搭起来、怎么撞墙、撞完怎么补的。

写在前面

这篇文章想聊的是一件具体的事:怎么让 AI 在一个真实的、跨多个仓库的前后端业务工程里稳定地跑完一个需求。

现在大家手里都有越来越强的模型,但只要你试过让 AI 独立做完一个完整的产品需求——从产品那条 TAPD 单子开始,到方案落地、代码改完、接口跑通、CR 通过、最后 MR 提到工蜂上——你就会发现一件事:模型够强了,工程没跟上。AI 一个人跑不完,因为整条链路上太多事不是"写代码"本身,而是协作、流程、信任、收口。

我们 TAB 实验平台是一个典型的前后端业务为主的技术平台:拥有超过30+的微服务、10+ 个前端微应用、各平台SDK库,我们把它们集成在整个大仓做统一管理,然后用沙箱做集成验证、用TAPD 管各种需求输入、iWiki 沉淀方案、工蜂托管代码等等。在这种工程里搭建 Harness,会遇到一组很实在的一些挑战,比如:

  • 你可能有时不是改一个仓库,是同时动可能跨 5 个 submodule 的代码
  • 你不仅是验证一个功能是否跑得起来,是要拉沙箱、刷 schema、起 Redis、跑真实 HTTP 接口测试,是让整个功能能够真正放心上线
  • 你不是面对一份本地用户文档,是面对 TAPD 单 + iWiki 文档 + 工蜂 MR + Knot知识库管理的四套外部输入输出系统
  • .......

我们花了一段时间把这套 Harness 慢慢搭起来。这一路上踩了不少坑、撞了不少墙、删过不少自以为正确的设计。这篇文章把这些经验完整复盘一遍,希望对正在做类似事情的同学有用。

全文阅读约 25 分钟。 一共 10 小节,按"先讲项目 → 再讲方法论 → 再讲撞墙 → 最后讲取舍"的顺序展开。如果时间紧,可以直接跳到第六章(门禁脚本)和第七章(Team Mode 撞墙复盘)——这两章的密度最高、踩坑最深,对其他团队可能也最有参考价值。


第一章:TAB工程背景

在讲我们怎么搭 Harness 之前,必须先让你知道我们在搭什么样的工程上。否则后面所有取舍都没法理解——同样一套方法论,落在不同工程上长出来的样子会差很多。

1.1 TAB 工程画像

TAB 是公司内部的 A/B 实验平台——产品同学发起一个实验、配人群、配指标、灰度推全,背后是一整套从实验编排到效果统计的服务体系。技术上它有几个显著特征:

维度
TAB 的样子
仓库形态
多工作区 + 多子仓库(实验编排服务、人群服务、指标服务、网关、前端微应用…)
主语言
Go、Ts语言为主,同时融合各平台SDK技术栈,以及少量 Python 工具链
架构分层
胶水层(协议↔领域对象转换)→ 接口层 → 服务层 → 领域层(数据访问 + 领域模型)
横切关注点
7 个切面顺序串成一条链:错误 → 日志 → 数据库上下文 → 鉴权 → 参数校验 → 事务 → 出参整形
验证手段
一键拉起完整沙箱环境(Docker Compose),数据库 / 缓存全新初始化,可跑真实 HTTP
外部协作
TAPD 管需求单、iWiki 沉淀制品方案、工蜂托管代码 + + Kont知识库管理 + MR、企微通知等

它的真实复杂度,在于任何一个看上去 虽然只有个一行的 PRD,可能牵动 3个子仓库、改 5 个协议字段、增 8 个服务方法、补 12 个单测、加 2 个接口测试等一系列复杂流程。

1.2 Harness 在 TAB 上要解的真实痛点

团队一起坐下来盘点过,跑 PRD 这件事在 TAB 上的真实痛点不是"AI 写得不准",而是这四件事:

真实卡点
长什么样
PRD 不能被信任
产品给你一句话:"加个白名单删除"。但删除后会不会触发下游回收?灰度怎么处理?接口幂等吗?没人知道
方案对不上代码
方案写得很漂亮,但具体改哪几个服务、加几个协议字段、和现有数据访问层怎么对齐——看不出来
改完没人验证
"我改完了"和"我跑过沙箱接口测试且新增覆盖率 ≥85%"是两件事。前者是 AI 的口头汇报,后者是机器可读的事实
交付环节碎成一地
写完代码要去 TAPD 改单子状态、去 iWiki 沉淀方案、去工蜂提 MR、在评论区贴度量——动作都对,但全靠人记

注意,这四件事没有一件是模型问题。它们都是协作问题、流程问题、信任问题。

也就是说,我们要搭的 Harness,主要不是给 AI 用的,是给团队用的。它的目标不是让 AI 看上去更聪明,而是让 AI 在 TAB 这个工程里稳定、规范、可被审计地把事情做对。

1.3 SPEC-First:从一份完整的设计文档开始

我们 Harness 落地的第一步不是写 Rule、不是拆 Agent,而是先和团队一起磨出一份完整的全链路产研流程技术设计文档。这份文档承担的作用就是:

  • 把目标拆成四个子目标:PRD 质量、需求分析、自动实现、集成验证
  • 把"AI 能跑完什么"和"必须人介入什么"划清楚
  • 把"做完什么算 Harness 一期"定下来,达成共识

没有这份 SPEC,Harness 不会被搭出来,会被搭歪。 因为 Harness 不是一组工具,是一种工程纪律。纪律必须先有共识。


第二章:Harness 在 TAB 上由哪几块东西组成

我们这套 Harness 由六个层次的资产组成:Rule(规则)、Skill(标准操作手册)、Sub Agent(专职角色)、Workflow(流程定义)、Scripts(门禁脚本)、MCP(外部系统接口)。这几个概念在不同工程里会长成不同样子,下面讲它们在 TAB 大仓里具体的形态。

2.1 Rule:我们最后没怎么写

这件事可能违反直觉。Rule 是写给 AI 看的自然语言约束,看上去最容易写、也最容易被想到。但 Rule 有一个天然的天花板:自然语言天然能被解释性执行——AI 可以说"这条规则在这个场景下不适用""我做了等价的事""这是历史问题",每一句都可能是真的,但你没法每次都翻 git log 去验证AI所说的。

因此,我们的体感变成:在我们的业务大仓里,Rule 几乎全部下沉成了 Skill 或脚本,独立的 Rule 反而最少。

为什么?因为我们设计的Harness,几乎所有约束都是有判定的:

  • "数据访问层必须用 GORM,不许直接拼 SQL" → 写成 lint 规则就行
  • "错误必须用统一错误码包,不许用标准库 error" → 一个 lint 检查器搞定
  • "服务层覆盖率 ≥70%、数据访问层 ≥50%" → 脚本进行强制规定
  • "任何写操作必须走事务切面" → CR 阶段静态扫描

能判定的就别留在 Rule 里。这是我们和其他工程一个很明显的差别,我们会更早地把所有规则脚本化了。

2.2 Skill:注意力管理而非能力增强

我们当前只留了 11 个 Skill,按职责分四组:

脚手架与代码层规范(4 个)

  • 协议与领域模型脚手架
  • 数据访问层规范手册(GORM 规约 + 数据库 mock 单测约束)
  • 业务服务层规范手册(面向对象写法 + 切面对齐)
  • HTTP 处理层规范手册

测试规范(2 个)

  • 单元测试规范(mock 框架 + 函数打桩约定等)
  • 接口测试生成(沙箱真实HTTP等)

需求理解阶段的内部能力(3 个)

  • PRD 完整性自评工具(5 维度评分 0~100)
  • 影响半径分析工具(涉及多少个子仓库、多少个接口等)
  • PRD 模板

代码审查阶段的能力(2 个)

  • 范围溢出检查(对比是否超出技术方案的计划)
  • 前端增量与视觉审查

每个 Skill 解决的问题是同一个:把"这件事具体怎么做"从主 prompt 里拆出去,让主 Agent 的注意力只放在当下的认知任务上。

举个具体例子。我们数据访问层有一套很硬的规矩:必须用 GORM、必须用数据库 mock 写单测、增量覆盖率必须 ≥80%、错误必须用统一错误码包、包内类型必须按统一前缀命名等等。如果把这些规矩塞进开发 Agent 的主 prompt里面,会发生两件事:

  1. 主 prompt 越来越长,开发 Agent 真正该关心的需求上下文被淹没
  2. 改一条规矩,每个 Agent 同步都都得修改

所以我们独立成一份"数据访问层规范手册",开发 Agent 跑到数据访问任务时按需加载。这就是 Skill 的本质——AI 在某一类任务上的标准操作手册。在后端这边它的价值更直接:Skill 不是 AI 的能力增强,是 AI 的注意力管理。

2.3 Sub Agent:我们最后只留了 4 个

Sub Agent 这一层的本质是给认知工作分工——把一条长链路按"谁该关心什么"切成几个独立角色,每个角色只看自己该看的输入、只产自己该产的输出。

我们最终只留了 4 个:需求 Agent 方案 Agent 开发 Agent / 代码审查 Agent,外加 1 个总控 Agent 在最外面调度。先看一眼当前的角色契约:

角色
职责
必读
必写
不许做
需求 Agent
把 TAPD 链接 → 结构化的需求理解 + 影响半径分析
TAPD 单 / PRD 文本
需求理解文档 / 代码影响地图
不许写技术方案
方案 Agent
把需求 → 可执行的技术方案
需求理解文档 / 代码影响地图
设计文档 技术规约 任务清单
不许改需求理解文档
开发 Agent
按设计落代码 + 接口测试产物
需求理解 设计 技术规约 / 任务
实际代码 + 接口用例文档 + 增量 Go 接口测试 + 单元测试
不许超出设计文档计划范围
代码审查 Agent
从 4 个维度收口
上游全部产物 + git diff
代码审查结论文档
不许改代码,只能产出阻塞项

为什么只有 4 个 Agent? 因为还有一类角色——流程调度、跑门禁、跑测试、提 MR——它们看上去也像"角色",但其实是纯确定性工作。我们把这一类全部下沉成了 总控 Agent + 脚本 的组合:

  • 流程调度(决定下一阶段是什么)→ 总控 Agent 里以伪代码形式存在的状态机
  • 门禁入口 → 统一门禁脚本
  • 测试执行 → 沙箱部署 接口测试 前端冒烟 三个独立的门禁脚本
  • 分支与交付 → 分支准备脚本 + 交付收尾脚本

它们的工作完全是确定性的:决定下一阶段、跑门禁、跑测试、提 MR。这些东西没有任何认知工作,让 AI 来解释执行只会徒增 token 和不确定性。

能写成 bash 的就别让 Agent 跑——这是我们 4 个 Agent 这个数字背后真正的判断标准。

2.4 Workflow:13 个阶段的接力赛

Workflow 不是流程图,更像是一份接力赛规则:每一棒交什么、下一棒接到什么才能开跑、跑砸了回到哪一棒重来。Agent 之间是接力关系,不是协商关系——这个比喻在我们后面所有讨论里都很有用。

我们的接力赛 13 棒长这样:

初始化 → 需求分析 → 需求确认 → [Bug 复现] → 技术方案 → [方案确认]

→ 方案评审 → 分支准备 → 开发 → 集成测试 → 代码审查 → 验收 → 交付收尾

方括号的是条件触发——bugfix 类需求才走 Bug 复现;涉及改协议或跨多服务时才弹方案确认。

每棒都明确写在流程定义文档里:

  • 当前阶段是哪一棒(checkpoint 文件里的阶段字段)
  • 这一棒要交付什么(产物清单)
  • 下一棒接手前必须看到什么(必读文件)
  • 什么情况打回(打回规则表)
  • 打回后回到哪一棒(集成测试失败回开发、方案评审失败可以回方案 Agent 或需求 Agent)

这套规则不是写在长文里,是单独抽成可校验的资产——一份高层流程定义文档、一份伪代码状态机文档、再加一个自检脚本检查完整性。流程一旦从"长文里的描述"变成"机器能校验的资产",它的稳定性就会上一个台阶。

第三章会展开讲为什么是 13 棒、为什么不能再少。

2.5 Scripts:最硬的那道墙

这个概念在我们这里就是流水线上的 7 道门禁脚本。第六章会单独展开。这里只留一句话:

Scripts 的价值不是多了一组工具,是把"完成"这个词的定义权从 AI 手里拿了回来。

2.6 MCP:通往交付闭环的接口层

MCP(Model Context Protocol)这一层做的事很具体:让 AI 能在受控、结构化、可审计的边界内调用外部系统——TAPD、iWiki、工蜂、企微、Knot。

我们目前接了 5 个 MCP:

  • TAPD MCP:读 / 改 TAPD 单、加评论、关联 git 分支、状态扭转等
  • iWiki MCP:写方案、批量上传制品等
  • 工蜂 MCP:MR 创建、CR 评论拉取
  • Knot MCP:拉取前端设计规范以及代码规范
  • 企微 MCP:交付完成后通知

这一层补的是从开发闭环到交付闭环的最后一段路——单纯写完代码不算交付,需求单状态推进、方案归档、MR 提出、群里通知,每一步都得做。第九章会展开讲我们在这条路上踩过的坑。

第三章:为什么 13 个阶段一个都不能合

在 TAB 这种跨超多个子仓模块的环境里,每一个阶段的存在都对应着一类历史教训。这一章把这些教训摊开讲。

3.1 直觉上你会觉得"能不能合"

我们一开始也想合:初始化和需求分析合并?开发和集成测试合并?合理啊,一个 Agent 顺手就把测试也写了嘛。

每次"合"都被现实打回来。每一个阶段的存在都对应一类痛点:

阶段
它存在是因为
不分开会怎样
初始化
解析 TAPD 链接、派生需求 ID、改 TAPD 状态、打 Harness 标签——一组只在最开头跑一次的副作用
和需求分析混合,需求分析被打回时 TAPD 状态被反复改
需求分析
把模糊需求 → 结构化的需求理解文档,并跑 PRD 完整性自评 + 影响半径分析
直接进技术方案,方案设计被迫脑补需求边界
Bug 复现
bugfix 类需求必须先在沙箱复现,再去改
直接改代码,最后发现根本复现不出来,前面全白做
分支准备
在开发之前在每个涉及的子仓库创建特性分支
在开发里临时切分支,分支名跑偏,MR 目标分支错乱
集成测试
在代码审查之前用真实 HTTP 把接口用例打一遍
留到验收才发现接口对不上,代码审查已经评过了,全部白评
验收
代码审查之后再幂等重跑接口测试 + 跑 diff 基线对比
没有"基线对比",AI 用"这是历史问题"糊弄过去
交付收尾
提交 推送 提 MR 度量 推 iWiki / 回写 TAPD 评论
散落在开发末尾,必然漏一项

合并阶段省下来的是流程图复杂度,但代价是状态机里多一堆隐式分支。我们最终接受了"流程图复杂一点"的代价。

3.2 一个值得展开讲的故事:集成测试是怎么从"后置"挪到"前置"的

这是我们走过最值得分享的一段弯路。

最早的设计里没有集成测试这一步。接口测试放在验收阶段里,跟"日志验收"并列。逻辑很顺:代码审查评完代码 → 验收阶段跑测试 → 通过 → 交付收尾。

跑了几个真实需求之后,我们发现一个让人沮丧的循环:

开发写完 → 代码审查 Agent 把整个 diff 仔细审了 200 行 → 代码审查通过

↓

验收阶段跑接口测试 → 失败(路径写错 / 参数对不上 / 错误信息没对齐)

↓

打回开发 → 改 → 重新过代码审查 → ...

代码审查是整条链里最贵的环节,每次跑都要审查 Agent 把整个 diff 重看一遍。但接口测试问题其实是个几秒就能验证的事——我们却让它躺在代码审查之后,让最贵的环节背最便宜的锅。

决策:接口测试前置到代码审查之前,作为强制硬门禁。不通过不准进代码审查。

开发 Agent 写业务代码 + 单测

→ 同时产出接口用例文档 + 增量 Go 接口测试代码

→ 集成测试阶段拉沙箱 + 真实 HTTP 打一遍

→ 通过才进代码审查

这一改之后,代码审查阶段的平均打回次数从 1.8 次降到 0.4 次。

但这次调整真正值得说的不是"少打回了",而是它顺手把 "开发完成"的定义改了:以前"开发完成 = 业务代码 + 单测",现在"开发完成 = 业务代码 + 单测 + 接口用例文档 + 增量接口测试代码"。

让产生问题的人,同时产生验证手段——这才是一个真正交付完整的开发阶段该有的样子。

3.3 一个反过来的故事:Bug 复现怎么从"必走"变成"可选"

接着说一个反方向的取舍。Bug 复现这个阶段最早是所有 bugfix 必走的——不复现不让改。

跑了几次发现一个问题:很多 bug 是产品同事报的,TAPD 单里写得很清楚(请求 期望 实际),不需要复现。强制复现等于在沙箱里多花好几分钟跑一遍已经知道答案的事。

所以我们把 Bug 复现改成条件触发:仅当需求类型是 bugfix 且 用户明确要求复现时才走。默认跳过直接进技术方案。

这件事的小教训:

流程要给"明显已经清楚的事"留一条快车道。强制所有需求走最严格的路径,等于惩罚那些已经准备充分的需求。

3.4 阶段切分的判断标准

我们最后总结的"是否应该独立成阶段"的判断标准只有两条:

  1. 它是否有独立的失败模式?(集成测试失败 ≠ 代码审查失败 ≠ 开发失败)
  2. 它失败时回退的位置是否不一样?(集成测试失败回开发、代码审查失败可能回到方案)

两个都是"是" → 必须独立。否则就合。13 个阶段每一个都过这两道筛子。


第四章:四个 Agent 是被问题一步步逼出来的

我们的 4 个 Agent 不是设计出来的,是被一次次撞墙逼出来的。这一章把这条演进路径完整复盘一遍。

4.1 第一阶段:单 Agent 跑全流程

最早我们试过"一个 Agent 干到底"——它读 TAPD、写方案、写代码、写单测、自己审查、自己跑测试。

跑了几个需求就出现一组很典型的问题:

  • 上下文混杂:它分不清"TAPD 里写的"和"它自己推断的"
  • 天然缺乏制衡:它写的方案它自己审,几乎不会否决
  • 倾向往前推进:它会主动找理由说"问题不大,继续…
— 以上为试看内容(约 40%),开通会员后阅读全文 —