1. 为什么“让AI写代码”这件事需要一套工程化框架过去一年我身边不少团队都在用AI辅助写代码。刚开始大家的反应都差不多哇效率飞起。但用了一段时间之后抱怨开始出现了——生成的东西时好时坏同一个需求问两遍结果完全不一样代码风格飘忽不定更麻烦的是当项目稍微复杂一点AI就开始“胡编”接口、遗漏边界条件甚至把之前能跑的代码改崩。这个现象其实不难理解。大多数人用AI写代码的方式本质上就是“对话式碰运气”打开一个聊天窗口把需求描述一遍拿到代码复制粘贴跑不通就再问一遍。整个过程没有任何结构化的约束没有验证环节没有回滚机制也没有可复用的流程沉淀。这就像你招了一个能力很强但完全没有工程素养的实习生他每次都能给你写点东西出来但你永远不知道他这次写的是不是靠谱的。Agentic Harness Workflow 框架要解决的就是这个问题。它的核心思路是不再把AI当成一个“问答机器人”而是把它当成一个需要被“驾驭”的执行单元用一套工程化的流程把它的能力框住、引导住、验证住。Harness这个词本身就有“马具、约束装置”的意思非常形象——AI的能力像一匹烈马跑得快但方向不定你需要一套缰绳和鞍具让它按照你想要的路线跑。这套框架适合谁我认为有三类人特别需要一是已经在日常工作中重度使用AI编码工具但苦于输出质量不稳定的开发者二是团队里负责制定研发流程的技术负责人需要一套可复制、可推广的AI协作规范三是对AI编码感兴趣但一直觉得“不太敢用在正经项目上”的工程师这套框架能帮你建立信心。接下来我会从设计思路、核心环节拆解、完整实操流程、常见问题排查几个维度把这套框架讲透。不是泛泛而谈的概念介绍而是我自己实际跑过多轮之后沉淀下来的具体做法。2. 框架整体设计与核心思路拆解2.1 从“对话式编码”到“流水线式编码”的范式转换传统用AI写代码的方式我把它叫做“对话式编码”。你的操作路径大概是这样的想清楚要做什么打开对话框打字描述等结果看结果不满意就重新描述满意就复制走。这个过程的问题在于所有的质量控制都发生在“人看结果”这一步而且完全依赖人的即时判断。Agentic Harness Workflow 做的事情是把这条路径改造成一条有多个检查点的流水线。每个检查点都有明确的输入、输出和验收标准。AI不再是“一次性给你一个答案”而是在每个环节里扮演特定角色完成特定任务然后交给下一个环节。我举个具体的对比。假设你要实现一个“用户注册接口”对话式编码的做法是直接跟AI说“帮我写一个用户注册接口”AI给你一段代码你看看觉得差不多就用了。至于参数校验全不全、异常处理到不到位、有没有考虑并发场景全靠你自己逐行审查。Harness Workflow的做法是先让AI输出接口的规格说明输入输出、边界条件、错误码定义人工确认规格没问题然后让AI基于规格生成测试用例人工审查测试用例是否覆盖了关键场景再让AI基于规格和测试用例生成实现代码最后自动运行测试验证实现是否通过。每一步都有明确的交付物和验收标准。这个转换带来的最大好处是可追溯和可复现。当最终代码出了问题你可以沿着流水线往回查是规格定义就有漏洞还是测试用例没覆盖到还是实现阶段AI理解偏了而不是像对话式编码那样只能重新问一遍然后祈祷这次能对。2.2 为什么选择“多角色分阶段”而不是“单角色端到端”有人可能会问为什么不直接让AI端到端完成整个任务为什么要拆成多个阶段、多个角色这个问题我一开始也纠结过。端到端看起来更省事一次对话就能出结果。但实际跑下来端到端的问题非常明显第一上下文窗口的约束。当一个任务涉及多个文件、多种关注点时AI在单个对话里很容易“顾此失彼”。你让它同时考虑接口设计、错误处理、性能优化、代码风格它往往会在某个维度上偷懒。第二错误传播。端到端模式下如果AI在早期阶段理解错了需求后面所有的输出都是错的而且你很难定位到底哪一步出了问题。分阶段之后每个阶段都有检查点错误在早期就能被发现和纠正。第三角色混淆。让同一个AI实例既当“架构师”又当“实现者”又当“测试者”它在不同角色之间的切换往往不够彻底。分阶段之后每个阶段给AI明确的角色设定和关注点输出质量会明显提升。我自己的经验是任务越复杂分阶段的价值越大。简单的单文件函数可能端到端就够了但一旦涉及多模块协作、需要严格的质量控制分阶段就是必须的。2.3 框架的四个核心阶段与流转逻辑经过多轮迭代我把这套框架的核心流程收敛为四个阶段阶段一意图澄清与规格定义。这个阶段的目标是把模糊的需求转化为明确的、可验证的规格说明。AI在这里扮演的是“需求分析师”的角色它需要主动提问、识别歧义、输出结构化的规格文档。人工在这个阶段需要确认规格是否符合预期。阶段二测试先行与验收标准。基于规格说明让AI生成测试用例。这个阶段的关键是“测试先行”——在写实现之前先把验收标准定下来。AI扮演“测试工程师”角色输出覆盖正常路径、边界条件、异常场景的测试用例。人工审查测试用例是否充分。阶段三实现生成与自验证。基于规格和测试用例让AI生成实现代码。AI扮演“开发者”角色但有一个关键约束它必须在生成代码后自己运行测试并根据测试结果迭代修正。这个阶段是自动化的核心环节。阶段四审查归档与知识沉淀。实现通过测试后进入审查阶段。AI扮演“代码审查者”角色检查代码风格、潜在问题、可优化点。人工做最终确认后将规格、测试、实现、审查意见一起归档形成可复用的知识资产。这四个阶段之间不是简单的线性关系。实际使用中阶段二发现问题可能需要回到阶段一修正规格阶段三的测试失败可能需要回到阶段二补充测试用例。框架的价值在于它让这些回退变得有迹可循而不是一团乱麻。3. 核心环节的详细拆解与实操要点3.1 意图澄清阶段怎么让AI问出“好问题”很多人用AI的时候习惯一次性把需求描述得很详细觉得这样AI就能理解得更准确。但实际效果往往相反——你描述得越详细AI越容易在你没提到的细节上“自由发挥”。Harness Workflow在意图澄清阶段的做法是反过来的先给一个粗略的需求描述然后让AI主动提问。具体操作是这样的你给AI的初始输入可以很简单比如“我需要一个用户注册功能”。然后你给AI的指令是“你现在的角色是需求分析师。请针对这个需求列出所有你需要澄清的问题按重要性排序。”AI通常会问出这些问题注册方式是什么邮箱、手机号、第三方密码强度要求是什么是否需要邮箱验证并发注册怎么处理错误码怎么定义等等。这个做法的好处是AI问出来的问题往往比你自己想到的更全面。因为AI见过大量的类似场景它知道哪些地方容易出问题。你只需要逐条回答这些问题规格就自然清晰了。注意这个阶段不要急着让AI写代码。我见过太多人跳过澄清阶段直接让AI生成实现结果就是反复修改、反复重来总耗时反而更长。回答完AI的问题后让它输出一份结构化的规格文档。这份文档至少应该包含功能描述、输入输出定义、边界条件、错误处理、非功能性要求性能、安全等。这份文档就是后续所有阶段的“合同”。3.2 测试先行阶段把验收标准“焊死”在流程里测试先行是这套框架里我最坚持的一个环节。原因很简单如果你不先定义“什么叫做完了”AI就会按照它自己的理解来交付。具体操作把上一阶段的规格文档喂给AI指令是“你现在的角色是测试工程师。请基于这份规格生成完整的测试用例。要求覆盖正常路径、边界条件、异常场景、并发场景。”AI输出的测试用例通常是表格形式或者代码形式。我建议要求它输出可执行的测试代码而不是纯文字描述。因为可执行的测试代码可以直接在后续阶段用来验证实现。这里有个关键技巧让AI为每个测试用例标注它对应规格中的哪一条。这样做的好处是当测试失败时你能快速定位是哪个规格点没有满足。同时如果某个规格点没有任何测试用例覆盖你也能一眼看出来。实操心得测试用例生成后不要直接进入下一阶段。花几分钟人工审查一下看看有没有明显的遗漏。AI生成的测试用例往往在正常路径上覆盖得很好但在异常场景和并发场景上容易偷懒。你可以追问一句“有没有哪些异常场景是你觉得重要但我可能没想到的”通常能挖出一些有价值的补充。3.3 实现生成阶段让AI“自己验证自己”这是整个框架里自动化程度最高的环节。把规格文档和测试用例一起喂给AI指令是“你现在的角色是开发者。请基于规格和测试用例生成实现代码。生成后请自己运行测试如果测试不通过请分析原因并修正直到所有测试通过。”这个“自己运行测试”的能力取决于你使用的工具链。如果你用的是支持代码执行的AI环境它可以自动运行测试并迭代。如果不支持你可以让AI输出代码后你手动运行测试把失败信息贴回去让它修正。无论哪种方式核心原则是AI必须对测试结果负责。不是生成完代码就结束了而是要确保代码能通过之前定义的验收标准。这个阶段有几个容易踩的坑第一个坑是AI为了让测试通过而“作弊”。比如测试要求某个函数在输入为空时抛出异常AI可能在函数开头直接写一个if input is None: raise Exception而没有真正处理空输入的业务逻辑。防范方法是在测试用例中不仅检查异常是否抛出还要检查异常的类型和消息是否符合规格。第二个坑是AI修改了测试用例来适配实现。这种情况在自动化迭代中偶尔会出现。防范方法是把测试用例文件设为只读或者在指令中明确要求“不得修改测试用例”。第三个坑是过度拟合测试用例。AI可能写出只对当前测试用例有效的代码换一个输入就崩了。防范方法是在测试用例中增加一些“随机化”或“参数化”的测试让AI无法针对特定输入硬编码。3.4 审查归档阶段把一次性成果变成可复用资产实现通过测试后很多人就觉得“完事了”。但Harness Workflow的最后一个阶段恰恰是最容易被忽视、但长期价值最大的环节。这个阶段要做三件事第一让AI做一次代码审查。指令是“你现在的角色是代码审查者。请审查这份实现代码关注代码风格一致性、潜在的性能问题、安全隐患、可读性、是否有更简洁的写法。”AI给出的审查意见你可以选择性采纳。第二人工做最终确认。AI的审查不能替代人的判断。你需要确认实现是否符合业务预期有没有AI没注意到的业务逻辑问题代码是否融入了现有项目的整体架构第三归档。把规格文档、测试用例、实现代码、审查意见一起保存到一个结构化的目录中。我通常的目录结构是这样的project/ features/ user-registration/ spec.md # 规格文档 tests/ # 测试用例 implementation/ # 实现代码 review.md # 审查意见 changelog.md # 变更记录这个归档的价值在于当下次有类似需求时你可以直接把之前的规格和测试用例作为参考喂给AI大大减少澄清和测试编写的时间。而且当新人加入团队时这些归档就是最好的学习材料。4. 完整实操流程从零跑通一个真实需求4.1 环境准备与工具链选型在开始实操之前先说一下工具链的选择。这套框架不依赖特定的AI工具但不同的工具会影响体验。我自己的选型逻辑是这样的工具类型推荐场景注意事项支持代码执行的AI环境实现生成阶段自动化迭代确认沙箱环境是否隔离避免影响本地项目纯对话式AI工具意图澄清、测试编写、代码审查需要手动复制粘贴测试结果效率略低但可控本地代码编辑器AI插件实现代码的最终集成注意插件是否会上传代码到云端敏感项目需谨慎版本控制工具全流程归档每个阶段的产出物都建议提交方便回溯我自己的组合是意图澄清和测试编写用一个对话式工具实现生成用一个支持代码执行的工具最终集成在本地编辑器里完成。这样兼顾了效率和可控性。4.2 第一步意图澄清的完整对话记录假设我要实现一个“文章草稿自动保存”功能。我的初始输入是这样的我需要一个文章草稿自动保存功能。用户编辑文章时系统每隔一段时间自动保存草稿防止意外丢失。然后我给AI的指令是“你现在的角色是需求分析师。请针对这个需求列出所有你需要澄清的问题按重要性排序。”AI返回的问题列表我整理后的版本自动保存的触发条件是什么定时触发还是内容变更触发保存间隔多长是否允许用户配置草稿保存在哪里本地存储还是服务端如果保存时网络不可用怎么处理草稿保留多久是否需要版本历史多个设备同时编辑同一篇文章草稿如何合并用户手动保存和自动保存冲突时以哪个为准草稿是否需要加密存储保存失败时是否需要通知用户草稿的数据结构是什么和正式文章的结构是否一致我逐条回答这些问题后让AI输出规格文档。规格文档的核心部分如下功能名称文章草稿自动保存 触发条件内容变更后延迟30秒触发或每5分钟定时触发以先到者为准 存储位置服务端按用户ID文章ID索引 网络异常处理保存失败时写入本地队列网络恢复后重试最多重试3次 草稿保留最近10个版本超过自动清理 冲突处理以最后写入为准但保留冲突版本供用户选择 通知策略保存成功不通知保存失败在界面显示轻提示 数据结构与正式文章一致额外增加draft_id和timestamp字段这份规格文档就是后续所有工作的基础。4.3 第二步测试用例的生成与审查把规格文档喂给AI指令是“你现在的角色是测试工程师。请基于这份规格生成完整的测试用例。要求覆盖正常路径、边界条件、异常场景、并发场景。每个测试用例标注对应的规格条目。”AI生成的测试用例我截取关键部分# 测试用例1内容变更后30秒触发保存 def test_auto_save_on_content_change(): # 对应规格触发条件-内容变更后延迟30秒 editor create_editor() editor.type(hello) time.sleep(31) assert draft_exists(editor.article_id) # 测试用例2网络异常时写入本地队列 def test_save_failure_queues_locally(): # 对应规格网络异常处理 with mock_network_down(): editor.type(hello) time.sleep(31) assert local_queue_has_item(editor.article_id) # 测试用例3草稿版本超过10个时自动清理 def test_draft_version_cleanup(): # 对应规格草稿保留-最近10个版本 for i in range(15): save_draft(article_id, contentfversion_{i}) assert count_drafts(article_id) 10 assert get_oldest_draft(article_id).content version_5我审查后发现两个问题一是没有测试“多设备同时编辑”的冲突场景二是没有测试“手动保存和自动保存冲突”的场景。我让AI补充了这两个用例。4.4 第三步实现生成与自动验证把规格文档和测试用例一起喂给AI指令是“你现在的角色是开发者。请基于规格和测试用例生成实现代码。生成后请自己运行测试如果测试不通过请分析原因并修正直到所有测试通过。不得修改测试用例。”AI生成的实现代码核心逻辑class DraftAutoSaver: def __init__(self, article_id, user_id): self.article_id article_id self.user_id user_id self.last_content None self.last_save_time time.time() self.local_queue [] self.save_interval 30 self.max_interval 300 def on_content_change(self, content): self.last_content content now time.time() if now - self.last_save_time self.save_interval: self._try_save() def on_timer(self): now time.time() if now - self.last_save_time self.max_interval: self._try_save() def _try_save(self): try: save_to_server(self.article_id, self.last_content) self.last_save_time time.time() self._flush_local_queue() except NetworkError: self.local_queue.append({ content: self.last_content, timestamp: time.time() }) if len(self.local_queue) 3: self.local_queue.pop(0)AI运行测试后报告有两个测试失败一个是版本清理的测试因为实现中没有处理版本数量限制另一个是冲突处理的测试因为实现中没有保留冲突版本。AI自动修正后所有测试通过。4.5 第四步审查归档与知识沉淀实现通过测试后我让AI做代码审查。AI提出的主要意见_try_save方法职责过重建议拆分为_save_to_server和_handle_failure本地队列使用列表存储频繁pop(0)效率低建议改用collections.deque缺少日志记录建议在关键节点增加日志时间间隔使用硬编码建议提取为配置项我采纳了前两条后两条根据项目实际情况决定暂不处理。最终归档的目录结构features/ draft-auto-save/ spec.md tests/ test_auto_save.py implementation/ draft_auto_saver.py review.md changelog.md整个流程从开始到归档大约用了40分钟。如果是对应功能比较熟悉的开发者可能更快。相比对话式编码反复修改的时间这个投入是值得的。5. 常见问题与排查技巧实录5.1 AI在意图澄清阶段问不出好问题怎么办这种情况通常发生在需求本身比较模糊或者AI对领域知识不够熟悉的时候。我的应对策略是给AI一些“种子问题”作为引导。比如你可以说“请从数据流、异常处理、并发场景、用户体验这四个维度来提问。”这样AI就有了一个提问的框架不容易遗漏重要维度。另一个技巧是让AI扮演不同的角色来提问。比如先让它以“后端开发者”的身份提问再以“前端开发者”的身份提问再以“测试工程师”的身份提问。不同角色关注的点不一样综合起来就比较全面了。5.2 测试用例总是覆盖不全怎么破AI生成测试用例时最容易遗漏的是异常场景和并发场景。我的做法是在指令中明确列出必须覆盖的场景类型并且要求AI为每个场景类型至少生成两个用例。另外我会让AI做一次“反向检查”把规格文档给它问“这份规格中哪些条目没有被测试用例覆盖”AI通常能识别出遗漏点。还有一个进阶技巧让AI生成“变异测试”用例。就是故意在实现中引入一些小错误比如把改成看测试能不能发现。如果测试发现不了说明覆盖不够。5.3 实现阶段AI反复修改但测试始终不通过这种情况通常有三个原因原因一规格本身有矛盾。比如规格说“保存失败时重试3次”但测试用例期望“保存失败时立即返回错误”。这种矛盾需要回到规格阶段解决。原因二测试用例的断言过于严格。比如测试要求错误消息必须精确匹配某个字符串但实现中的错误消息措辞略有不同。这种情况下可以放宽断言或者让AI统一错误消息的格式。原因三AI陷入了“局部最优”。它一直在微调某个函数但没有意识到问题出在架构层面。这时候需要人工介入给AI一个更高层次的指导比如“请重新设计这个模块的接口把保存逻辑和重试逻辑分离”。5.4 归档之后怎么复用归档的价值在于复用。我的复用方式主要有三种第一种作为新需求的参考。当有类似需求时直接把之前的规格和测试用例喂给AI说“请参考这个模式为新的需求生成规格和测试”。这样能节省大量澄清和编写测试的时间。第二种作为团队规范。把归档的目录结构和文档模板提取出来作为团队使用AI编码的标准流程。新人入职时直接看这些归档就能理解团队的AI协作方式。第三种作为质量基线。当AI生成的实现质量下降时可以对比之前的归档看看是哪个环节出了问题。是规格写得不够细还是测试覆盖不够还是审查环节被跳过了5.5 常见问题速查表问题现象可能原因排查方向解决技巧AI问的问题太泛初始需求太模糊检查初始描述是否缺少关键信息给AI提供提问框架或角色引导测试用例遗漏异常场景指令中未明确要求检查指令是否列出了场景类型要求AI做反向覆盖检查实现反复不通过规格与测试矛盾对比规格和测试的断言回到规格阶段统一口径AI修改测试用例自动化迭代中的“作弊”检查测试文件是否被改动设置测试文件只读或明确禁止修改代码风格不一致缺少风格约束检查是否提供了风格指南在规格中增加代码风格要求归档后找不到目录结构混乱检查归档规范是否统一制定固定的目录结构模板6. 我对这套框架的一些个人体会跑过多轮之后我最大的体会是这套框架的价值不在于“让AI写出更好的代码”而在于“让AI写代码这件事变得可管理”。对话式编码的问题不是AI写得不好而是你无法预测它这次写得好不好也无法在出问题时快速定位原因。Harness Workflow通过分阶段、多角色、强制验证的方式把这种不确定性降到了可接受的范围内。另一个体会是框架的收益随着任务复杂度的增加而增加。如果你只是让AI写一个简单的工具函数这套流程可能显得过于繁琐。但一旦任务涉及多个文件、多种关注点、多个协作方这套框架就能帮你省下大量的返工时间。还有一个容易被忽视的点归档本身就是一种学习。当你积累了一定数量的归档之后你会发现AI在某些类型的任务上表现特别好在某些类型上容易出问题。这些经验会反过来指导你更好地设计规格和测试用例。最后分享一个小技巧在意图澄清阶段让AI同时输出“成功标准”和“失败标准”。成功标准是你期望的行为失败标准是你绝对不能接受的行为。这样在后续的测试和审查阶段你就有了更明确的判断依据。这个技巧是我在一次复杂需求中偶然发现的后来成了我的标准操作。