返回文章

从能跑到可交付:一套前端 AI 协作系统的设计笔记

上篇《AI 写代码,最缺的不是 Prompt,而是一个能暴露错误的现场 》讲的是为什么:模型不是不会写,而是没有现场感,不知道自己错了,也没办法及时发现。

这篇讲怎么做。

过去一段时间,我把那套想法落成了一个能跑的系统:一套前端 AI 协作系统。它不是一个更长的提示词,而是一组互相咬合的设计:五层约束管住代码往哪写,一个五阶段状态机管住一件事怎么走完,评测管住什么叫做对了,内核管住长流程别中途失忆。

2026-11 修订说明:这篇文章最初写于 2026 年 10 月,描述的是这套方法的早期形态(八个阶段、每阶段一份 Skill)。此后我把整套系统重写成开源工具 frontend-harness-cli 并持续迭代,流程的形态变了:阶段变成了内核状态,Skill 改按产物命名,验收换成了带否决权的评分表。本次修订把机制部分全部换成开源版的现行形态,设计思想、实测数据和踩坑记录保留原样。现在文中讲的每个机制,都能在仓库里找到对应实现。

先给结论,再展开。LangChain 在 Terminal Bench 2.0 上做过一个实验:模型不变,只改外围的 Harness,得分从 52.8% 涨到 66.5%,多了 13.7 个百分点,排名从三十名开外进了前五。

我的感受也类似。模型没有变聪明,是它犯错的空间变小了,发现错的速度变快了。

下面按五层约束、五阶段与三个角色、Skill 怎么组织、评测怎么做、内核怎么跑、踩过的坑、怎么落地、它的边界在哪,这个顺序讲。

一、五层约束:先把轨道铺好

我把前端的约束分成五层。自下而上是:语言、样式、状态、工程、美学。

每一层回答一个问题。语言层问错不错,样式层问稳不稳,状态层问准不准,工程层问通不通,美学层问对不对。顺序不能乱。代码都编译不过,谈视觉还原没有意义。

第一层,语言约束。 用 TypeScript 的严格模式钉死:显式类型,不许用 any 绕过去,不许用忽略类型的注释把报错盖住。类型即文档,函数签名要让调用方一眼看出会返回什么、可能出什么问题。

我把这层比作有刻度的尺子。写错了,尺子当场拦住,不需要等运行起来才发现。

第二层,样式约束。 颜色、间距、字号全部走设计变量(Design Token),不写死数值;组件样式用 CSS Modules 做作用域隔离。这些规则不靠评审时口头提醒,而是写进 Stylelint 和 ESLint,违反就报红。

这层像一个只有 8 种颜色的调色板。AI 选不了错的颜色,因为错的颜色根本不在板子上。

第三层,状态约束。 状态要有显式的结构定义:字段、类型、初始值、哪些可缺省,都写清楚。客户端状态和服务端数据分开,单一数据源。本地存储的键必须带命名空间,能一眼看出它属于哪个页面、哪类数据,而不是随手起个名字全站共用。

这层像一座城市只有一条公路从水厂到每家每户。你不需要猜水从哪来,打开龙头就有,出了问题也知道沿哪条路查。

第四层,工程约束。 目录结构、模块之间能不能互相引用,用架构 Lint 强制;文件大小和函数长度设上限——比如单个源文件不超过 300 行,函数也要控制在可读的长度内,超了就必须拆。再加上提交前钩子和 CI,把类型检查、Lint、构建、测试串成一条流水线,不通过就不让进。

这层是交通规则加红绿灯。不是建议你别闯,而是路口的设计让你闯不过去。

第五层,美学约束。 设计变量再往上走一层:颜色、间距、圆角、阴影、动效都沉淀成 Token,高频界面模式封装成组件,再用截图对比做视觉回归。

这层像乐高。错误尺寸的积木根本不存在,能拼错的余地就小了。

这里有个前端特有的判断,值得单独说。

LangChain 总结的通用 Harness 是六层:文件系统、沙箱、代码执行、记忆、上下文管理、编排。落到前端,我把前几样做了压缩:文件系统、沙箱、代码执行,本质上都被工程约束吸收了——构建失败就是沙箱失败,Lint 跑通就说明代码能执行;记忆在前端就是状态,归到状态层;编排单独拿出去,变成后面的状态机。

压完之后空出来一层,我把它留给了美学。

这不是凑数。通用 Harness 的文献很少谈美学,因为多数任务的对错是二值的。但前端不一样。Omni-I2C 这类图文转代码基准里,当前最强的模型视觉还原能到七成多,细到参数级的精度只有四成左右,而且实体和布局错误占了所有错误的六成以上(来源:Omni-I2C 基准,2026)。也就是说,功能对了,页面仍然可能是不对的。用户会不会用,很大程度取决于这一层。

这五层在开源版里落在两个地方:一是 harness init 时按技术栈装进项目的规则与栈包(Next.js、React、Vue、Node 各一份),二是评测里的五维扫描逐项回查——约束写下去,还要有人查,这两件事缺一不可。下一节先讲流程怎么走。

二、五阶段与三个角色:流程是状态机,不是文档

有了轨道,还需要列车时刻表。早期版本我把一个需求拆成八个阶段,每个阶段写一份 Skill 让模型照着走。重写成开源版时,我把这件事推翻了:阶段不该是文档,应该是代码里的状态。 文档靠模型"记得遵守",状态靠程序强制执行——这是整套系统最重要的一次形态变化。

现在一个功能(feature)的一生只有五个阶段,由内核的状态机驱动:

澄清(clarify)→ 实现(implement)→ 评测(evaluate)→ 确认(verify)→ 交付(done),外加一个随时可能进入的暂停(paused)。

干活的不是"主对话里的模型",而是三个角色,各有自己的上下文、输入包和权限边界:

  • 规划者(planner):只在澄清阶段出现。把一句话需求追问到开放问题清零,然后按固定顺序产出契约文件:prd.md(每条需求带编号)、vision.md、tech-design.md、pages.json、tasks.json、rubric.json、e2e-cases.json。你已经有成稿 PRD 也可以:harness new <功能> --prd <文件> 直接原文导入,编号一个不改,澄清缩减为只确认加补缺口。
  • 开发者(developer):在实现阶段一次做一个任务:实现、跑检查、做一次精确提交。它有一个刻意的权限设计——永远看不到 rubric。它按计划干活,不是对着考题干活。
  • 评判者(evaluator):在评测和确认阶段各出现一次,而且两次必须是不同的全新上下文。按 rubric 逐条打分,只交证据,不许顺手改代码。

整条流水线有三个原则,都是踩出来的。

原则一:先定义"完成"长什么样,再写代码。

澄清阶段结束有一道覆盖门禁(coverage gate):每条需求编号都必须有至少一条"必查项"(essential)、一条挂在具体锚点上的品质条目(或一份书面豁免)、以及覆盖六大类的端到端用例。覆盖不全,状态机不放行,代码一行都不许写。

为什么这么狠?Anthropic 有个发现我很认同:评分标准的措辞不只是用来判断好坏,它会直接塑造生成者的输出方向。你把"完成"写清楚,AI 写的时候就在朝那个方向收敛。反例就是那句最常见的"把首页做完"——AI 自由发挥六个小时,你验收时发现方向错了。模糊的指令不会被执行,只会被放大。

原则二:检测和修复必须分开。

评测只报告问题,永远不许顺手改代码。修复只能回到实现阶段,而且只许修评测报告里列出的开放项。

原因很实际。修复必然引入新问题:评测顺手修了样式,可能改坏类型;修了类型,可能漏掉文案。更麻烦的是评测一旦动了代码,这次评测就没法复现了——你分不清报告说的是哪一版代码。分开之后,每次评测对应一份固定的报告,每次失败走哪条路重试,都有记录可查。

原则三:否决权大于总分,稳定大于一次通过。

rubric 里的条目分三档:command(命令真跑)、judge(凭证据判断)、manual。其中两类条目带否决权:essential 条目得 0 分,整个功能直接判失败;pitfall 条目被触发(比如用了忽略类型的注释绕过检查),同样直接失败——总分再高也没用。

过了评测还不算完。确认阶段换一位全新的评判者,把所有 judge 条目的证据从零重新生成——比上一次评测旧的证据直接记 0 分——并且要求连续通过若干轮。一次通过可能是运气,换人、换证据、连过几轮,才叫稳定。

还有一条和任务绑定的硬校验:开发者声称某个任务做完了,必须报出那次提交的 SHA,内核用 git rev-parse 验它真实存在。报一个不存在的 SHA,任务不记完成。这条规则听起来好笑,但它拦下的是真实发生过的事:模型会"声称"自己提交了。

给老读者一张对照表,我早期文章里的八个阶段如今在哪:初始化变成了 harness init 命令;文档沉淀消失了——契约文件在澄清阶段就已落盘,产物即文档,交付后由 sync-overview 把稳定结论沉淀进项目概览;发布变成了交付阶段的门禁(你项目自己的构建、测试、Lint 必须全绿);进化拆成了两条受守护的回路,第五节细说;修复回路住在评测与实现之间。阶段没有消失,只是从"要背的流程"变成了"不用背的状态"。

三、Skill 的设计:从阶段文档到产物契约

这一节多讲几句,因为 Skill 是这套系统里变化最大的部分——大到我认为它值得单独拿出来说:从经典八阶段到现在的 CLI,阶段消失了,Skill 却从 14 份长到了 21 份,而且每一份都变短了。 这不是数量游戏,是分工变了。早期形态里,一份 Skill 就是一个阶段:ait-clarify、ait-generate、ait-evaluation……每份 100 到 230 行,自己带着触发条件(“用户说’出方案’时用我”)、自己记着上一步是谁、自己管一整段流程。它既是说明书,又是流程本身。

新设计里,Skill 的权力被拆走了两块:顺序归内核,判断归评测,Skill 只剩下一样东西——把一份产物做出来的手艺。 21 份 Skill 没有一份以阶段命名:澄清是一条著述链(clarify-requirements → write-prd → write-quality-vision → write-tech-design → write-dev-plan → write-acceptance-criteria);实现有 implement-task、systematic-debugging;评测有 e2e-testing、api-testing、deterministic-eval、fix-from-report;交付有 ship-checklist、sync-overview;再加一批通用手艺(component-from-design、state-schema-first、i18n-extract 等)。平均每份 70 行上下,最短的不到 40 行。

一份 Skill 的解剖

拿 write-prd 做标本。一份新 Skill 由五块组成,每块都有明确的契约味道:

第一行描述就是接口声明。 它写的是:“规划者专用,著述链第 1 步;仅在 clarify-requirements 以 confirmed-by-user: yes 且开放问题为 0 收尾后使用。“角色、位置、前置条件,一句话说全——给内核和角色看的,不是给人看的广告语。

Gate(前置门)。 进这份 Skill 之前先核查文件:澄清确认稿存在吗?确认标记对吗?项目概览读了吗?条件不满足就停下、退回上一份 Skill。老形态的触发靠模型"觉得该用了”,新形态的前置条件是能逐项核查的事实。

产物结构(输出契约)。 prd.md 的九节是写死的:问题、用户与场景、用户故事、带编号的需求、非功能需求、“好样子"长什么样、非目标、成功度量、概览增量。尤其关键的一条:需求编号 REQ-n 会被逐字抄进 rubric.json 成为评测的分母。Skill 的产出不再是"写给下一个人看的文档”,而是"要被机器消费的合同”——写含糊了,覆盖门禁当场拦下。

模式分支(Mode check)。 这是老 Skill 完全没有的能力:同一份 Skill 会先看状态,再决定怎么干。如果 state.json 标记这个功能的 PRD 是用户导入的,write-prd 切到"只规范化"模式:只补缺号、只报缺节,永不重编、永不改词。入口不同,纪律不同,写在同一份文件里。

Rules 与 Done Criteria。 Rules 是具体禁令(“一需求一句可测的话"“不许把实现细节写进 PRD”);Done Criteria 是可验收的收尾条件(“九节齐全、编号连续、无 TODO”),最后一行明写下一份 Skill 是谁——但注意,这只是提示,真正的顺序由内核状态决定,Skill 说了不算。

为什么要这么设计

五个决策,逐个说理由。

一、按产物切分,不按阶段。 阶段是流程概念,切出来的单位无法验收:“执行澄清阶段"做完没有?没人能判断。产物是实物:“prd.md 九节齐全、编号连续"能判断。粒度小还有两个附带好处:失败时能定位到是哪一份手艺出了问题;组合时灵活——implement-task 被每个功能复用,fix-from-report 跨阶段复用,不必在每个阶段文档里各抄一份。

二、把流程知识从 Skill 里剥走。 老形态最大的教训在第六节坑二:顺序写在文档里,靠模型自觉,衔接处必然出错。新形态里 Skill 只声明自己的前置门和完成标准,“下一步是谁"由状态机裁定。这就像把交通规则从司机手册里搬进了信号灯系统:手册还写着规则,但让你停下来的不再是你的记性。

三、产出契约化,让下游能机器校验。 一条 REQ-3 在 prd 里诞生,在 rubric 里变成检查项,在评测报告里变成一行证据,在覆盖门禁里是分母的一部分。整条链能对上号,前提是源头这份 Skill 的产出足够结构化。Skill 写得"文采好"没用,写得"可消费"才有用——这是给 AI 用的文档和给人看的文档最根本的区别。

四、按角色打包,可见性即权限。 harness init 时按角色把 Skill 装进各自的任务包:规划者拿到著述链,评判者拿到评测技能,开发者的包里根本没有评测类 Skill——和它看不到 rubric 是同一个设计。老形态是全局注册表,所有 Skill 对所有人可见,每轮对话都要为整张列表付上下文成本,我当年还得立一条"全局不超过 12 个"的硬上限去抢救。新形态把这个问题从"配额管理"变成了"打包问题”:不需要全局列表,只需要每个角色在干活时手边有它那几份。

五、Skill 自己也要被评测。 系统里有一套黄金集(harness skills eval 的 cases):一批标准任务,定期给 Skill 们打分,退化就报警。老形态里 Skill 的质量全凭手感,“进化"靠人复盘完手动改文档。新形态把 Skill 当代码管:有契约、有门禁、有回归测试。规则会随模型升级而过期(第八节会讲消融),没有回归测试,你连它什么时候开始拖后腿都不知道。

还有一个顺带解决的问题:宿主可移植。 老 Skill 绑在单个工具的生态里(触发方式、提问工具都是那家的专有约定);新 Skill 通篇只引用文件和状态——确认稿在哪个路径、状态文件里哪个字段——不引用任何宿主的专有能力。同一份 Skill 因此能装进 Claude Code、Codex 或任何能读文件的运行时,init 时按宿主渲染外壳即可。另给每份 Skill 配了一份中文阅读版(SKILL.zh-CN.md),人审阅时读中文,生效的仍是英文版——给人看的和给机器执行的,正式分家。

把新旧两套摆在一起,差别一目了然:

经典八阶段(ait)现在的 CLI
数量与粒度14 份,100–230 行/份21 份,38–134 行/份
命名按阶段(ait-clarify)按产物(write-prd)
谁定顺序Skill 文档自述,模型执行内核状态机裁定
触发用户话术/事件触发,全局注册角色任务包按需装载
产出给下一阶段看的文档被 rubric 与门禁消费的契约
可见性全局可见,有数量上限按角色打包,不需要的不可见
质量保障人工复盘、手动进化黄金集回归评测
宿主绑定单一工具生态只引用文件与状态,跨运行时

最后保留一条老经验,它没被推翻,只是换了位置:上下文会被压缩,活在对话里的流程细节会死。所以 Skill 必须是磁盘上的文件、由任务包在每一步重新递到角色手边,而不是指望任何人(包括模型)“记得"它。这篇旧版在这一节的标题是「放错位置,写得再好也会丢」——新设计等于承认了这句话,并把"放对位置"做成了安装程序的职责,而不是用户的自觉。

四、评测必须确定性:不让模型给自己打分

整套系统里我最坚持的一条:写完代码之后,判断对错尽量用代码,不用模型。

Anthropic 在他们的长周期 Harness 设计里说得很直白:开箱即用的 Claude 是一个糟糕的 QA。它能看到真正的问题,然后说服自己"这些问题没什么大不了”,照样批准自己的工作。

这不是某个模型的毛病,是位置决定的。让生成者兼任评审者,它天然对自己宽容。所以评测拆成两层:

第一层,rubric 评测,判"这个功能做对没有”。 契约的一部分,澄清阶段就写好。条目分两种跑法:command 条目是确定性命令——编译器、grep、测试、五维扫描(见下层),退出码说话;judge 条目确实需要判断的(比如"空状态文案是否说清了下一步”),由评判者凭新鲜证据打分——Playwright 现场截图、真实 API 探测的返回,而不是"读一遍代码觉得没问题”。每条检查都必须给证据:具体到哪个文件、哪一行、哪张截图。没有证据,就不算通过。

第二层,五维扫描,判"这批代码健康不健康”。 它是独立的一台仪器(harness scan,也能脱离全流程单独跑),五个维度:

  • 结构:类型能不能编译通过、有没有用忽略规则绕过检查、导入关系合不合架构约束、文件和函数有没有超长;
  • 数据:文案键是否齐全、状态结构是否闭合、本地存储的键有没有按命名空间规范;如果项目给了数据规格(Data Spec),逐字段做差异比对;
  • 逻辑:需求的功能点清单逐条核对代码里有没有对应的实现和关键分支——这就是为什么功能点必须写在写代码之前,它是评测的考卷,考后出题就没意义了;
  • 界面:样式有没有走组件作用域、颜色间距有没有用变量、有没有写死数值;如果给了设计稿,做截图的像素级保真比对;
  • 端到端:真的把测试跑起来,统计通过和失败的数量,看主链路有没有覆盖到。

这里有个口径必须说清,否则就是骗人:扫描有两种模式。 项目配置齐全时,结构维真的跑 tsc、端到端维真的跑你给的测试命令、数据维拿规格逐字段 diff——这是实测。零配置时拿不到这些输入,扫描退回静态检查兜底,这时报告必须明示哪些维度"未实测",不许拿静态分数冒充真跑的结果。分数的可信度分级,要写在报告里,而不是藏起来。

最后是报告的规矩:每份评测报告写完就不许再改。后续重新生成了代码、重新评测,写新报告,旧的留着。这样复盘的时候能回答一个很关键的问题:这次翻车的原因,上次的报告里是不是已经预警过了?如果预警过,问题在路由和修复;如果没预警,问题在评测本身。没有留档,这笔账永远算不清。

五、内核:长流程不能靠模型"记住"

五个阶段如果全在一个主对话里跑,会发生什么?

每进一个阶段,就要把那个阶段的说明加载进上下文。走到后半程,上下文必然触发压缩。而压缩一来,前面阶段的约束和结论就被磨成了摘要里的几句话,越关键的细节丢得越干净。

我用探针式抽查量过这件事:在流程开始时埋一组关键规则作为探针,在每个阶段结束时抽查这些规则还记得多少。主对话模式下,走到第五阶段,信息保留率只剩 40% 左右。

解法是把流程从对话里搬出来,交给一个确定性的内核。它是零依赖的 Node 程序,逻辑很朴素:

每个功能有一份状态文件(.harness/tasks/<功能>/state.json),是整条流水线的唯一事实源:当前阶段、各阶段的历史、任务清单、契约文件的位置、评测结论都在里面。任何人——包括模型自己——都不许手改这个文件,所有状态变更只能走内核命令。状态文件长这样(简化版):

{
  "feature": "todo-app",
  "phase": "evaluate",
  "history": [
    { "event": "clarify-done", "at": "…" },
    { "event": "task-done", "task": "add-todo", "commit": "a1b2c3d" }
  ],
  "prd": { "source": "imported", "numberingComplete": true },
  "verdict": { "passed": false, "openItems": ["REQ-3"] }
}

角色们通过任务包和内核打交道:内核按当前阶段生成一份限定输入包——比如评测阶段的评判者只拿到 rubric 和代码入口,开发者的包里根本没有 rubric 这一项。角色跑完,把产出写回文件就退出,下一步做什么由内核读状态决定,不由任何模型"回忆"。

使用上有两种姿势。交互式:你在 Claude Code 或 Codex 里工作,每个功能的第一条命令是 harness next <功能>,它只告诉你当前这一步该做什么,做完再问下一步——单步协议,人随时能接管。无人值守:harness run <功能> 由驱动器按协议把整条流水线跑完,只在澄清确认和暂停时找人。

评测失败时,内核按结论路由:有开放项,退回实现阶段只修那些项;评判者对 rubric 本身有改进建议,先交规划者回应——这是进化阶段的第二条回路,而且方向被锁死:rubric 只能收紧,放松必须人批。 所有循环都有预算上限,耗尽了状态机进入 paused,停下来等人决定,绝不无限打转。

同样用探针式抽查量这个模式,走到第五阶段,信息保留率能到 95% 左右。差别不在模型,在信息放在哪。放在对话里,就要陪着对话一起被压缩;放在文件和程序变量里,就不会。

六、踩过的四个坑

坑一:评测一开始用模型判断。

最初的评测是让模型看代码、写结论。结果它给自己打了满分,嘴上说 100 分,代码实际跑起来只有三成左右能用,端到端测试全军覆没。

根因就是第四节说的自我宽容。修复是把能确定性化的全部改成命令和证据:编译器退出码、测试通过数、逐行证据。经验一句:Lint 的报错不只是报错,它同时是给模型的修复指令。报告写得越具体,它改得越准。

坑二:把流程写成文档,让模型照着走。

早期版本的八个阶段是八份 Skill 文档,靠模型自觉按顺序执行。第一次端到端跑,八个阶段只跑了四个:有几个阶段被莫名其妙地跳过了,流程却显示一切正常。

根因在"下一步走哪"的判断上:靠模型读文档判断,和后来靠代码判断时写错条件,犯的是同一类错误——衔接处没有硬校验。某个阶段还没跑过、历史为空,判断逻辑误判成"已经通过,去下一个"。修复分两步:先把判断拆成明确的三步(先看有没有失败且还有重试次数,再看是不是从没跑过,最后才看通过没有),再往前一步,把整个流程从文档搬进代码状态机。经验一句:这种衔接错误,单元测试测不出来。每个阶段单独测都是对的,错的是阶段之间。它必须端到端真跑一遍才能信。

坑三:在主对话里跑完整条流水线。

症状就是第五节的前半段:跑到后半程,前面阶段立的规矩基本被压缩吃掉,后面的阶段等于在一个失忆的上下文里凭感觉干活。

修复是把阶段拆给独立角色、状态搬进文件。经验一句:主上下文永远不要堆叠流程内容。任何"在一次长对话里跑完长流程"的设计,都会在中段崩掉,只是早晚问题。

坑四:静态分数冒充实测分数。

扫描器早期有个很隐蔽的问题:零配置跑出来的静态检查分数,和配置齐全后真跑编译、真跑测试的分数,长得一模一样——都是一个 0 到 100 的数字。拿前者去汇报,等于说"我测过了",其实最关键的几个维度根本没测。

修复是给每个维度标来源:实测还是静态推断;拿不到输入的维度在报告里明示"未验证",分数旁注明口径。经验一句:测不成,就写无法评估,不许写成一个看起来很真的数字。 这条对评测系统是诚信问题,不是精度问题。

七、落地:现在只需要三步

这套系统已经开源,所以"落地"不再是从零自建,而是三步:

  1. 装:git clone 仓库,或把一句话 prompt 粘进你正在用的 Claude Code / Codex,让 Agent 自己装好 CLI 并初始化你的项目——我在体检页 上放了一个现成的"一个 prompt"版本,复制即用。
  2. 跑:harness init 按你的技术栈(Next.js / React / Vue / Node)装好规则和技能包;然后 harness new <功能> 开第一个功能,有成稿 PRD 就加 --prd 导入。交互式用 harness next 一步步走,无人值守用 harness run。
  3. 先体检,再上全流程:拿不准值不值得上整套,先对现有仓库跑一次 harness scan 五维体检,或者在上面的体检页粘贴公开仓库链接在线跑一份——十分钟拿到一份带证据的报告,再决定。

如果你想抄的是设计而不是工具,我的建议仍然是先拿走最小的一块:语言层加工程层约束。 严格模式加两个 Lint,今天下午就能让 AI 在你的项目里少犯一类错。约束不需要等系统完整才生效,这是四周路径也好、三步也好,都不变的第一步。

至于建设顺序,我自己的经验是:先钉约束(一周),再给澄清和实现写技能,再上评测,最后才值得写内核。顺序反过来——先搭编排、后补评测——是最常见的死法:流程跑得越顺,垃圾产出得越快。

八、局限:它测不了什么,我很清楚

第一,美学层只能测一半。

自动化能查的是:有没有用变量、作用域对不对、截图和设计稿的像素差多少。但"颜色搭配合不合理"“间距有没有节奏"“字号层次清不清楚”,这些判断目前自动化只能覆盖一半左右,剩下一半还得靠截图加人工评审,或者靠一个独立的评审代理打分,而且那个分数要刻意往怀疑的方向校准,不能再犯自我宽容的毛病。

这也是为什么我说美学是前端特有的一层,同时它也是五层里最弱的一层。承认它弱,比假装它被解决了重要。

第二,“通用"还没有完全验证完。

这套系统在 Next.js 项目上验证得最深;Vue 等其他栈的栈包已经就位,但我的验收线是:Next.js 与 Vue 两个异构项目各用它跑通一个真实需求,在那之前我不对外宣称"通用已验证”。工具可以先用,结论不能先行。

第三,约束有保质期。

这套系统不是搭完就一劳永逸的。每次模型升级,都应该做一次消融:把某条约束撤掉,看效果变好还是变差。有些约束是补模型当下的短板,模型补上了,它就从护栏变成了路障;还有个更隐蔽的现象,模型会过拟合它长期使用的工具和 Harness,换掉某个环节的做法,效果反而会掉,这也只能靠实测发现,靠想是想不出来的。

还值得一提的是整个行业的背景并不乐观:有调查说,高频使用 AI 编码的人里,接近七成报告 AI 生成的代码至少有一半概率带来部署问题,一半左右的人觉得代码质量在下降。速度先到了,交付系统没跟上。这套 Harness 解决的是我自己项目里的那一份,不是什么通用解药。

写在最后

回到开头那句话:不要更聪明的马,要更好的赛道。

模型会变,而且变得很快。但回头看,这套系统里真正的核心不是哪个具体的数字或者工具,而是五个补偿性的设计:先定义完成再动手、检测和修复分开、上下文尽量被动给到、长流程拆进独立上下文、评测只信确定性的证据。

它们补偿的不是模型的智商,而是模型的几个结构性短板:不知道自己不知道、会说服自己没问题、记不住长流程、会被上下文淹没。这些短板短期内不会因为模型大一号就消失,所以这套设计也不会很快过期。过期的只会是具体的某条约束,那正是消融要定期清理的。

这套系统已经完整开源:frontend-harness-cli (内核、三个角色、21 份 Skill、五维扫描都在里面,扫描的前身是早期的 ai-code-gate,现已并入作为传感器层)。只想先看一份报告的,去体检页 粘贴一个公开仓库链接就行;想直接让自己的 Agent 用上它,同一个页面有一条复制即用的 prompt。

上篇讲为什么需要现场,这篇讲现场怎么搭。下一篇如果写,我想写写进化回路:一个系统怎么把每次失败变成自己的规则——哪些已经自动化了,哪些还必须留给人。

参考资料

  • LangChain:《The Anatomy of an Agent Harness》——Agent = Model + Harness 的六层解剖与 Terminal Bench 2.0 数据
  • Vercel:《AGENTS.md outperforms skills in our agent evals》——被动注入与主动检索的对照实验
  • OpenAI:《Harness engineering: engineering in the agent-first world》与 Codex 团队零手写代码的内部实践(经 Yage.ai 调研整理)
  • Anthropic:《Harness design for long-running application development》——长周期应用的 Harness 设计与评审者自我宽容问题
  • Omni-I2C 基准(2026)——图文转代码任务上主流模型的视觉还原与参数精度数据
  • Fred Brooks:《No Silver Bullet》(1986)——本质复杂度与偶然复杂度的区分