1. 为什么“能跑通的 AI 代码”离“能交付的工程”还差一大截很多人第一次用 AI 写代码体验都差不多丢一段需求进去几秒钟吐出一整段函数跑一下还真能过。于是很自然地产生一个错觉——AI Coding 已经能替代相当一部分开发工作了。但真正把 AI 生成的代码放进一个需要长期维护、多人协作、要过测试和评审的项目里问题就全冒出来了命名风格前后不一致、边界条件没处理、异常路径直接吞掉、依赖版本随手写、注释和实现对不上、同一个功能在三个文件里各写了一遍。这不是模型能力不行而是单次对话式的 AI Coding 本质上是一次性的。它没有“流程”这个概念你问一句它答一句上下文一断之前所有的约定、约束、风格偏好全部归零。下一次生成它又是从零开始猜你想要什么。所谓Agentic Harness Workflow拆开看就是三个词。Agentic指的是让 AI 以“智能体”的方式工作能自己规划步骤、调用工具、根据结果调整下一步而不是被动地一问一答。Harness原意是“马具、挽具”在工程语境里指的是那套把能力“约束住、引导好”的外壳——它规定了 AI 能做什么、按什么顺序做、做完怎么验证。Workflow则是把整个开发动作拆成有先后依赖的环节每个环节有明确的输入、输出和验收标准。把这三个词拼起来核心思想就一句话不要让 AI 直接给你最终答案而是让 AI 在一个被约束好的流程骨架里一步一步地把活干完每一步都可检查、可回退、可复现。这跟传统软件工程里“把大问题拆成小任务、每个任务有明确验收”的思路是一脉相承的只不过执行者从人换成了 AI 智能体。这篇文章适合三类人看。第一类是已经在日常开发里用 AI 辅助写代码但总觉得“生成的东西不太敢直接用”的开发者第二类是想把 AI Coding 引入团队、但苦于没有规范可循的技术负责人第三类是对 Agent 编排、工作流引擎感兴趣想看看这套东西在真实编码场景里怎么落地的人。下面我会从框架的整体结构讲起然后逐个拆解关键环节的设计逻辑再给出可以直接抄的配置和踩坑经验。全程不涉及任何具体平台的绑定讲的是通用的工程方法。2. Agentic Harness Workflow 的整体骨架长什么样2.1 三层结构编排层、执行层、验证层一套能真正用于工程交付的 AI Coding 流程我习惯把它拆成三层来看这三层各司其职缺一不可。编排层Orchestration Layer负责“决定下一步做什么”。它接收一个高层目标比如“给用户模块加一个手机号登录接口”然后把它拆成若干子任务先读现有代码结构、再确定接口签名、再写实现、再补测试、再跑校验。编排层不关心代码具体怎么写它关心的是任务之间的依赖关系和执行顺序。这一层通常由一个规划器Planner来承担可以是基于规则的状态机也可以是让 AI 自己规划再人工确认。执行层Execution Layer负责“真正把代码写出来”。它接收编排层下发的具体子任务调用代码生成能力产出结果。这一层的关键是上下文注入——在生成之前必须把相关的现有代码、接口约定、命名规范、依赖清单都塞进上下文里否则生成的东西就是空中楼阁。验证层Verification Layer负责“判断这一步到底过没过”。这是最容易被忽略、但恰恰是工程化与否的分水岭。验证可以是静态检查语法、类型、lint、可以是单元测试、可以是接口契约比对也可以是让另一个 AI 实例来做代码评审。验证不通过就把失败信息回传给编排层触发重试或人工介入。三层之间的关系是编排层驱动执行层执行层的产物交给验证层验证层的结果反馈给编排层决定下一步。这是一个闭环而不是单向流水线。2.2 为什么必须是闭环而不是流水线很多人搭 AI 工作流第一反应是搭一条直线需求 → 生成 → 测试 → 完成。这条线在理想情况下能跑通但现实中只要中间任何一步出问题整条线就断了而且断在哪里、为什么断你很难定位。闭环的价值在于失败是可处理的。举个具体场景执行层生成了一个函数验证层跑单元测试发现某个边界条件返回了 null 而不是空数组。在流水线模式下这个失败要么被忽略测试没接进来要么直接终止人工去看。而在闭环模式下验证层把“期望空数组、实际 null、出错行号、相关断言”打包成一个结构化的反馈回传给编排层编排层判断这是一个“可自动修复的小问题”于是重新下发一个带修复提示的子任务给执行层。执行层拿到原始代码加失败信息重新生成。这个过程可以自动重试两到三次大部分低级错误在这一步就被消化掉了。我实测下来加了闭环之后AI 生成代码的“一次通过率”从大概四成提升到了七成以上剩下三成里还有一部分是重试两轮后通过的。真正需要人工介入的比例大幅下降。这就是闭环带来的工程价值——它把“AI 偶尔犯错”这个不可避免的事实转化成了“系统能自己纠错”的稳定能力。2.3 一个最小可用的目录与配置约定要让这套流程跑起来项目里得有一些约定俗成的“锚点”让 AI 知道去哪里找信息、往哪里写东西。我一般会在项目根目录建一个.harness/目录里面放几类文件.harness/ workflow.yaml # 工作流定义有哪些阶段、依赖关系、重试策略 context/ # 上下文注入源 conventions.md # 命名、目录、注释规范 interfaces.json # 对外接口契约 deps.lock # 依赖版本锁定 prompts/ # 各阶段使用的提示模板 plan.md implement.md review.md artifacts/ # 每个阶段的产物落盘便于追溯workflow.yaml是整个流程的大脑它用声明式的方式描述阶段。下面是一个简化但可用的示例stages: - name: plan prompt: prompts/plan.md inputs: [context/conventions.md, context/interfaces.json] outputs: [artifacts/plan.json] next: implement - name: implement prompt: prompts/implement.md inputs: [artifacts/plan.json, context/conventions.md, context/deps.lock] outputs: [artifacts/code/] next: verify - name: verify run: scripts/verify.sh inputs: [artifacts/code/] on_fail: retry: implement max_retries: 3 feedback: artifacts/verify_report.json on_pass: done这份配置里最关键的是on_fail那段。它明确告诉系统验证失败时回到 implement 阶段重做最多三次并且把失败报告作为反馈传回去。这就是闭环的落地形式。artifacts/目录的存在让每一步的产物都留痕出问题时可以精确回溯到是哪一步、哪次重试产生的。提示deps.lock这类依赖锁定文件一定要纳入上下文注入。我踩过的坑是AI 生成代码时经常随手写一个它“记忆里”的版本号结果和项目实际依赖对不上装都装不起来。把锁定文件喂给它它就会照着现有版本写。3. 编排层把模糊需求拆成可执行子任务3.1 规划器到底该由谁来做编排层的核心是规划器。规划器有两种实现路线各有取舍。第一种是规则驱动。你预先定义好一套任务模板比如“加接口”这个需求固定拆成“读现有路由 → 定义请求响应结构 → 写处理函数 → 注册路由 → 补测试”五步。规则驱动的好处是稳定、可预测、不烧 token坏处是灵活性差遇到模板没覆盖的需求就抓瞎。第二种是AI 驱动。让一个规划用的 AI 实例读需求自己输出任务列表。好处是灵活能处理各种奇形怪状的需求坏处是它可能规划得过于粗糙或者过于琐碎而且每次规划结果可能不一样不利于复现。我的实际做法是混合用规则定义“必须有的阶段”比如任何代码改动都必须经过验证阶段用 AI 来填充“阶段内部的具体子任务”。这样既保证了流程骨架的稳定又保留了应对复杂需求的灵活性。规划器输出的任务列表我会强制要求是结构化的 JSON每个任务包含id、description、depends_on、expected_output四个字段。结构化是必须的因为下游的执行层和验证层都要靠这些字段来驱动。3.2 任务粒度的黄金分割点任务拆得太粗执行层一次要生成几百行代码出错概率高、验证也难定位拆得太细比如“写一个变量声明”都算一个任务那编排开销比干活还大。那粒度到底怎么定我的经验法则是一个子任务的产物应该是一个能被单独验证的最小单元。换句话说如果这个任务的输出没法单独跑测试或者单独做静态检查那它就拆得不够细如果它的输出小到验证本身比生成还费劲那就是拆过头了。具体到代码场景一个合适的子任务通常是“一个函数”或“一个类的某个方法”这个级别。比如“实现手机号格式校验函数”是一个合适的任务它的产物是一个独立函数可以单独写测试验证。而“实现整个登录模块”就太粗了“声明一个字符串变量”又太细。还有一个实用技巧让规划器为每个任务预估一个复杂度分数比如 1 到 5。复杂度高的任务编排层可以自动再拆一层复杂度低的可以几个任务合并执行。这个分数不需要很准它的作用是给系统一个“要不要继续拆”的信号。3.3 依赖关系与并行执行任务之间不是孤立的有依赖就得串行没依赖就可以并行。编排层要能识别出哪些任务可以同时跑这对整体效率影响很大。判断依赖的原则很简单如果任务 B 的输入里包含了任务 A 的输出那 B 依赖 A。比如“写处理函数”依赖“定义请求响应结构”因为函数签名要用到结构定义。而“写模块 A 的测试”和“写模块 B 的测试”之间没有数据依赖就可以并行。并行执行在实现上要注意两点。一是产物隔离两个并行任务不能往同一个文件里写否则会互相覆盖。解决办法是让每个任务写到独立的临时文件最后由一个合并步骤统一落盘。二是失败传播如果并行的两个任务里有一个失败了另一个要不要回滚我的做法是让成功的那个保留产物失败的那个单独重试不牵连已经成功的部分。这样能最大化利用已经完成的工作。下面这张表总结了编排层几个关键决策点的取舍决策点方案 A方案 B我的选择与理由规划器实现纯规则驱动纯 AI 驱动混合骨架用规则细节用 AI任务粒度粗模块级细语句级函数级以“可单独验证”为准并行策略全串行全并行按数据依赖判断无依赖才并行失败处理整体终止局部重试局部重试成功产物保留4. 执行层让 AI 写出的代码“像这个项目里的人写的”4.1 上下文注入的四个必给项执行层最容易犯的错误是只把“要做什么”告诉 AI却不告诉它“在这个项目里应该怎么做”。结果就是代码逻辑对但风格完全不对评审的时候被打回来重写。要避免这个问题生成之前必须注入四类上下文。第一类是规范类包括命名约定驼峰还是下划线、常量全大写还是小写、目录结构约定测试文件放哪、工具函数放哪、注释风格要不要写函数级注释、用什么格式。这些看起来是小事但恰恰是“像不像项目里的人写的”的关键。第二类是接口契约也就是这个模块对外暴露什么、依赖什么。把接口定义喂进去AI 生成的函数签名就不会跑偏也不会自己发明一套不存在的调用方式。第三类是依赖清单前面提过的锁定文件。这能防止 AI 引入项目里根本没有的库或者用错版本。第四类是相似代码样例这是最有效但最容易被忽略的一项。从项目里挑两三个和当前任务结构相似的现有函数一起喂进去。AI 有很强的“模仿”倾向给它看几个符合规范的样例它生成的东西会自然地贴近这些样例的风格。我实测过加了样例注入之后生成代码的“风格一致性”提升非常明显评审打回率下降了一大截。4.2 提示模板的写法约束比指令更重要写执行层的提示模板很多人习惯用一堆“请你务必”“一定要”这样的祈使句。但实际效果往往不好因为 AI 对“务必”这种词的敏感度远不如对具体约束的敏感度。更有效的写法是把约束写成检查清单让 AI 在生成后自己对照检查。比如生成代码后请逐条确认 1. 所有函数名使用小驼峰类名使用大驼峰 2. 每个导出函数必须有 JSDoc 注释包含 param 和 returns 3. 不允许引入 deps.lock 之外的任何依赖 4. 所有异步操作必须有错误处理分支 5. 边界条件空值、空数组、超长输入必须有显式处理这种清单式约束的好处是它把“风格要求”变成了“可勾选的项”AI 在生成时会更有针对性地满足每一条。而且这份清单本身也可以作为验证层的检查依据一举两得。4.3 生成结果的落盘与版本管理执行层产出的代码不能直接覆盖项目里的文件必须先落到artifacts/目录经过验证层确认后再合并。这个“先落盘、后合并”的机制非常重要它给了你一个天然的缓冲区。落盘时我会给每个产物打上元信息来自哪个任务、第几次重试、用了哪份上下文。这些元信息在排查问题时特别有用。比如某次生成质量特别差你可以回溯到它当时用的上下文版本看看是不是某份规范文件被改坏了。合并阶段我建议用标准的版本控制流程把 AI 的产物当成一次普通的代码提交来对待——该走的分支走分支该有的 diff 有 diff。这样即使 AI 生成了有问题的代码也能通过常规的代码回滚机制处理不会污染主干。注意千万不要让执行层直接写生产代码目录。我见过有人图省事让 AI 直接改源码结果一次错误的批量替换把几十个文件改乱了恢复起来极其痛苦。落盘缓冲这一步省不得。5. 验证层怎么判断 AI 这一步到底过没过5.1 静态检查、单元测试、契约比对的分工验证层不是一个单一动作而是一组检查的组合。不同检查负责不同层面的问题分工要清楚。静态检查负责语法、类型、lint 规则。这一层最快也最便宜能在几秒内筛掉大量低级错误。它检查的是“代码本身是否合法”不关心逻辑对不对。单元测试负责逻辑正确性。这是验证层的核心也是最能发现问题的一环。但单元测试有个前提——得有测试。如果 AI 生成的是新功能测试也得一起生成如果是改现有功能得跑现有的测试看有没有回归。契约比对负责接口一致性。它检查生成的代码是否遵守了interfaces.json里定义的接口。比如接口约定返回{ code, data, message }生成的函数却返回了裸数组契约比对就能抓出来。这一层在多人协作、多模块集成的场景里特别重要。三层检查的顺序应该是先静态、再契约、最后单元测试。因为静态检查最快先用它筛掉明显不合法的避免把时间浪费在跑测试上。契约比对次之它比单元测试快能提前发现接口层面的偏差。单元测试最慢但最深入放最后。5.2 把失败信息变成“可修复的反馈”验证层最有价值的地方不是“判断对错”而是“把错误转化成执行层能理解的修复指令”。同样一个测试失败如果只告诉执行层“测试没过”它大概率会瞎改如果告诉它“第 42 行断言期望空数组、实际返回 null原因是入参为空时没有走默认分支”它就能精准修复。所以验证层的输出必须是结构化的我一般要求包含四个字段location出错位置、expected期望值、actual实际值、hint可能的原因。这个结构回传给执行层时会作为修复提示拼进新的生成请求里。这里有个细节hint字段最好由验证层自己生成而不是简单地把原始错误信息丢过去。因为原始错误信息往往很底层比如某个断言库的堆栈AI 不一定能直接理解。让验证层做一次“翻译”把底层错误翻译成自然语言的修复建议效果会好很多。5.3 重试策略什么时候该重试什么时候该停重试不是无脑循环。如果一个问题重试三次都修不好那大概率不是执行层的能力问题而是任务本身定义有问题或者上下文给得不对。这时候继续重试就是浪费资源。我的重试策略是这样的第一次失败直接带着反馈重试第二次失败检查是不是上下文缺失补上相关上下文再重试第三次失败停止自动重试转人工介入并把前三次的失败记录一起呈现给人工。这个策略的核心是“每次重试都要有变化”要么换反馈要么换上下文不能原样重试。还有一个判断标准是失败类型。如果是语法错误、类型错误这类确定性问题重试通常有效如果是“需求理解偏差”这类模糊问题重试往往越修越偏不如直接人工介入重新定义任务。区分这两类失败能省下大量无效重试。失败类型典型表现处理策略语法/类型错误编译不过、lint 报错直接重试通常一次就好逻辑错误测试断言失败带结构化反馈重试最多三次契约偏差接口签名不符补充接口上下文后重试需求理解偏差实现的功能和预期完全不同停止重试人工重新定义任务6. 实测中那些文档不会写的坑6.1 上下文不是越多越好刚开始搭这套流程时我有个朴素的想法把项目里所有相关文件都塞进上下文信息越全AI 生成得越准。结果适得其反。上下文太长之后AI 的注意力被稀释反而抓不住重点生成质量下降而且 token 成本飙升。后来我改成按需注入每个任务只注入和它直接相关的上下文。写一个工具函数就只给它同目录下其他工具函数的样例不需要把整个项目的规范都塞进去。上下文精简之后生成质量反而更稳定了。经验值是单个任务的上下文控制在几千 token 以内比较合适超过这个量就要考虑是不是塞了无关内容。6.2 规范文件本身也会“腐烂”.harness/context/conventions.md这类规范文件一开始写得挺认真但项目在演进规范却没跟着更新。结果就是 AI 照着过时的规范生成代码和项目现状对不上。解决办法是把规范文件和代码放在同一个评审流程里。每次代码评审如果发现规范过时了就顺手更新规范文件。另外可以定期比如每个迭代让 AI 自己扫一遍代码库对比规范文件找出不一致的地方作为规范更新的输入。规范文件是活的不是写完就扔那儿的。6.3 并行任务的产物冲突前面提到并行执行要产物隔离但实际做的时候还是踩过坑。有一次两个并行任务都要修改同一个配置文件虽然写的是不同字段但因为是整文件覆盖后写的把先写的覆盖掉了。解决办法是对共享文件的修改强制串行。编排层在分配任务时要识别出哪些任务会碰同一个文件把这些任务排成串行。识别方法可以简单点让规划器在输出任务时标注每个任务会涉及哪些文件编排层据此做冲突检测。这个机制加上之后产物冲突基本没再出现过。6.4 验证层的“假阳性”验证层偶尔会误报——明明代码是对的测试却失败了。常见原因是测试本身有问题或者测试环境不稳定。这种假阳性如果直接触发重试会让执行层去“修复”一个根本不存在的问题越修越乱。应对方法是给验证结果加一个置信度。对于偶发性的失败比如超时、环境相关先自动重跑一次如果重跑通过就认为是假阳性不触发重试。只有稳定复现的失败才进入重试流程。这个机制能过滤掉大部分环境噪声。7. 从单机脚本到团队流程的扩展思路7.1 产物追溯与审计当这套流程从个人用扩展到团队用时追溯能力就变得重要了。谁在什么时候、用什么上下文、生成了什么代码、经过了哪些验证、最终有没有合并——这些信息都要能查。实现上artifacts/目录的元信息要持久化最好和版本控制系统打通。每次 AI 生成的产物都关联一个唯一的任务 ID这个 ID 贯穿规划、执行、验证、合并全过程。出问题时凭这个 ID 就能拉出完整的链路。这在团队协作里尤其重要因为代码是 AI 生成的出了问题不能只怪“AI 抽风”得能定位到具体是哪一步的上下文或约束出了问题。7.2 多人协作时的规范统一团队里每个人对“好代码”的理解不一样如果各自维护一套.harness/配置很快就会分裂成好几套风格。解决办法是把.harness/目录纳入版本控制作为团队共享资产。规范文件、提示模板、工作流定义都走统一的评审流程。个人可以有本地的临时覆盖但默认配置必须是团队统一的。另外可以定期做“规范对齐”把一段时间内 AI 生成后被人工修改的代码收集起来分析人工都改了些什么这些修改往往暴露了规范或提示模板的不足据此迭代配置。7.3 成本与效率的平衡这套流程比单次对话式生成要慢因为它多了规划、验证、重试这些环节。但慢不等于低效关键看“有效产出”。单次生成可能十秒出结果但你要花十分钟去改流程化生成可能两分钟出结果但改的时间缩短到两分钟。算总账流程化是划算的。不过成本确实要控制。我的做法是分级处理简单的、低风险的任务比如改个文案、加个日志走轻量流程跳过规划直接生成加静态检查复杂的、高风险的任务比如核心逻辑、对外接口走完整流程。不是所有任务都值得上全套流程按需分级能省下不少开销。8. 我在这套框架上的一些个人体会搭这套东西的过程中最大的感受是AI Coding 的瓶颈从来不在生成能力而在工程约束。模型能写出漂亮的代码但它不知道你的项目长什么样、你的团队在意什么、你的历史包袱有哪些。Harness 的价值就是把这些“模型不知道但很重要”的东西变成结构化的约束喂给它。另一个体会是验证层的投入回报比最高。很多人把精力花在优化提示词、换更强的模型上但提升有限。反而是把验证做扎实——静态检查、单元测试、契约比对三件套配齐——带来的质量提升最明显。因为验证层是唯一能“客观判断对错”的环节没有它前面生成得再好你也不敢用。最后一个建议是从小处开始。不要一上来就搭一套覆盖全项目的大流程先挑一个模块、一类任务试起来。跑通一个闭环积累一些上下文和提示模板再逐步扩展。这套东西是长出来的不是设计出来的。我最初就是从“给工具函数加测试”这一个场景开始的跑顺了之后才慢慢扩展到接口开发、模块重构这些更复杂的场景。这套框架后续还能往几个方向扩展。一是把代码评审也纳入流程让 AI 先做一轮自评审再交人工二是把部署和监控的反馈接进来让线上问题能自动触发修复流程三是把多个项目的规范沉淀成可复用的模板库新项目直接继承。这些方向我还在摸索等跑出稳定经验了再单独写。