1. 从“让AI写代码”到“管理AI写代码”：这个框架解决的问题
1.1 对话式AI编程的三个失控瞬间
我真正下定决心把AI Coding工程化，不是因为AI写得不好，而是因为它在“自由发挥”时给我带来的惊吓实在太多。先说三个我亲身经历过的瞬间。
第一次，我让AI帮我重构一个老模块的缓存逻辑。它确实把缓存逻辑改好了，但顺带把旁边一个无关的配置类也改了，原因是它“觉得”那两个类长得像。代码评审的时候我对着diff看了半天，才发现多出来的几十行改动根本不是本次需求要的。这还是小事，更麻烦的是，由于它的改动没有和现有代码充分对齐，集成测试一连红了三个小时，定位问题比人工写代码还慢。
第二次，AI在对话窗口里说“已完成，测试全部通过”。我当时偷懒没有立刻复核，等提交代码后，CI直接fail掉——它所谓的“测试通过”，是在没有运行测试套件的情况下，根据代码结构猜测出来的结论。后来我看它的输出日志，发现它根本没有执行任何测试命令，只是模型根据训练数据“推断”出这种写法大概率能通过。
第三次，是一个多月后我回头做代码审计，发现一个用AI生成的支付回调模块，核心逻辑里有一段注释写着“如果有边界情况请人工检查”。这句话在代码评审时完全被漏掉了。它不会主动告诉你哪里不可靠，而是用一种看似礼貌的注释把责任推给你，但产品经理不会看注释，测试也不会针对注释里的边界情况设计用例。
这三个瞬间让我意识到问题不在模型能力，而在于流程。对话式AI编程的本质是“点对点的闲聊”，你问一句它答一段，没有需求基线，没有质量门禁，没有可追溯的产物。代码能不能用，完全取决于模型当时的状态和你提问的技巧。这在写脚本、做原型时可以接受，一旦面对长期维护的生产代码库，就是灾难。
1.2 Harness在AI Coding中到底意味着什么
Harness这个词的本义是“挽具”，就是套在马身上、把马的力气导向特定方向的绳索和金属件。给一匹烈马套上挽具，它不是不能跑了，而是只能往你想要的方向跑。
在Agentic Harness Workflow框架里，Harness就是那套挽具。它不是用来限制Agent（智能体）能力的，而是给它设定一个明确的执行环境：输入是什么、允许操作哪些文件、调用哪些工具、每一步要产出什么格式的内容，以及哪些节点必须停下来接受验证。Agent仍然拥有自主决策能力，可以自己规划代码结构、选择算法、调试错误——但这一切都被框在一个可观测、可干预、可回滚的流程容器里。
这个框架解决的核心问题，不是“AI能不能写出代码”，而是“AI写出的代码能不能被团队信任”。信任的前提是可验证、可解释、可回退。要做到这三点，靠单个提示词是远远不够的，必须由外部工作流引擎来兜底。
1.3 对话式AI编程与工程化AI编程的差别
我把两种方式的差别整理成一个表格，方便你对照理解：
| 维度 | 对话式AI编程 | Agentic Harness工程化流程 |
|---|---|---|
| 需求传递 | 口头描述，容易丢失上下文 | 结构化任务描述，带需求快照 |
| 执行过程 | 黑箱，AI随意操作 | 分阶段执行，每步留痕 |
| 质量验证 | 依赖AI自觉 | 独立验证Agent强制执行测试与静态检查 |
| 代码审查 | 面对大段diff无从下手 | 分步diff，每步都有上下文 |
| 失败处理 | 同一对话里反复纠正，越聊越乱 | 失败自动回炉，重新规划并携带验证信息 |
| 可追溯性 | 几乎没有 | 每个决策节点都有日志和产物 |
从这张表能看到，工程化AI编程并不是把AI去掉，也不是让AI什么事都自己干，而是把人的管理智慧内化到一个工作流框架中，让AI的能力在可控范围内发挥。
2. 核心设计：让每个智能体都跑在“轨道”上
2.1 工作流四段式：计划、执行、验证、反馈
Agentic Harness Workflow框架把一次AI Coding任务拆成四个阶段：计划、执行、验证、反馈。这四个阶段构成一个闭环，而不是一次性走完就结束。
计划阶段是整个流程的大脑。在这个阶段，框架会综合任务描述、相关代码库结构、已有测试覆盖情况，生成一份Task Plan。Task Plan里包含：本次任务的目标定义、需要修改的文件列表、预计影响的模块、需要的测试策略。这份计划必须经过人或者一个独立的评审Agent确认，才能进入执行。这一步非常关键，因为如果计划就是错的，后面的执行再完美也是白搭。
执行阶段接收经过确认的Task Plan，由编码Agent负责实现。但这里的“执行”不是让它一次性输出整个文件，而是允许它通过工具调用逐步修改代码。每一步改动都会记录在案，包括改了什么文件、为什么改、基于哪条计划项。执行Agent不允许跳过验证直接宣称成功——它只能提交“待验证”状态。
验证阶段是独立于执行Agent运行的。框架会启动专门的验证Agent，执行编译、单元测试、风格检查、依赖检查，再结合代码diff的语义分析，给出“通过”或“不通过”的结论，并附上失败原因列表。这里的关键原则是：验证者不能和执行者是同一个Agent，甚至验证Agent的上下文里不能包含执行Agent生成的中间解释，只能看到最终代码和原始需求，这样能避免“自己证明自己没错”的偏差。
反馈阶段处理验证失败的情况。验证结果会被结构化地送回计划阶段，计划Agent根据失败原因修订Task Plan，或者直接判定“任务不可完成”，请求人来介入。这个闭环允许最多重试N次，超过阈值就停止，避免AI在错误方向上无限耗算力。
2.2 约束与自由的边界：Agent的决策空间设计
很多人在设计Agent流程时有一种误解，认为给Agent越多权限，它就越能干。实际上，一套好的Harness应该精确划定Agent的决策空间，就像地铁必须有轨道一样，Agent的自由只能在轨道内。
我建议从四个维度约束Agent：
第一，文件系统权限。Agent只能修改它被允许修改的目录，比如某个服务的src目录；对于配置文件、CI脚本、依赖锁定文件，只能读不能写，或者写入需要额外审批。一些框架默认允许Agent任意改文件，这等于让一个实习生在没有评审的情况下随意动生产代码，后果可想而知。
第二，工具调用权限。Agent可以调用什么外部工具？比如它可以运行git diff、pytest、eslint、npm test，但不能调用来路不明的任意Shell命令，更不能访问生产环境的密钥接口。工具白名单机制是必须的。
第三，任务规模上限。如果一个任务要求Agent一次性生成超过300行代码，框架会强制它停止，要求它先拆解成多个子任务。同理，如果单个文件修改超过500行，也需要人工确认。这不是无理限制，而是为了控制评审成本——大模型的一次性输出越大，隐含错误的密度就越高。
第四，引用与回复格式。Agent每次操作都必须以结构化JSON或特定前缀记录，禁止在最终代码里留下“这段可能有bug”之类的模棱两可注释。如果模型违反格式，工作流直接判为无效输出。
决策空间设计好了，Agent的自主性就有了安全边界。它可以在边界内自由选择算法、写法、重构策略，但无法突破轨道造成越界破坏。
2.3 状态机与数据流：每个节点留下可追踪痕迹
要让AI Coding变成工程化流程，底层必须是一个清晰的状态机。每个任务都有状态：pending（等待调度）、planning（计划生成中）、waiting_review（计划待评审）、executing（执行中）、verifying（验证中）、passed（通过）、failed（失败）、aborted（中止）。
这些状态之间的转换由框架引擎驱动，而不是由Agent自己声称。比如Agent说“我做完了”，引擎不会接受，它必须收到执行阶段产出的文件改动记录，并且把状态从executing切换到verifying，才能触发验证阶段。
同时，每个节点上的输入输出都以结构化数据保存下来。计划阶段的输入是原始需求文本和代码库索引，输出是Task Plan JSON；执行阶段的输入是Task Plan，输出是变更集和操作日志；验证阶段的输入是最终代码和测试命令，输出是验证报告。这些数据构成一条完整的可追溯链。
这个设计的价值在于：当代码评审者看到一段AI生成的代码时，可以沿着工作流的痕迹，一步步回溯到需求原文、计划拆分、执行理由、验证报告。任何一个环节都可以单独复核，而不是面对一大坨“不知道怎么冒出来”的diff。这一点在合规审查、交接维护中尤其有用。
3. 工作流引擎的实际搭建：阶段、角色、门禁怎么配置
3.1 用YAML定义一个可运行的Agentic Harness工作流
下面是一个简化但足够跑通流程的工作流定义示例。我把它写成YAML格式，因为可读性好、容易做版本管理。你可以把它理解为工作流的“配方”。
version: 1.0 name: standard_ai_coding_workflow roles: planner: model: gpt-4-class prompt_template: "planner_prompt.md" coder: model: gpt-4-class prompt_template: "coder_prompt.md" verifier: model: gpt-4-class prompt_template: "verifier_prompt.md" stages: - id: plan role: planner action: generate_task_plan input: [task_description, repo_index] output: task_plan gate: type: require_approval approver: human on_reject: abort - id: execute role: coder action: implement_changes input: [task_plan, repo_snapshot] output: change_set gate: type: file_permission allow_paths: ["src/", "tests/"] denylist: ["config/*.yaml", "ci/"] - id: verify role: verifier action: run_verification input: [change_set, original_requirements] output: verification_report gate: type: automatic commands: - "pytest src/tests/" - "eslint src/" - "git diff --check" - id: feedback role: planner action: revise_plan_on_failure input: [verification_report, task_plan] output: revised_task_plan max_retries: 3这个YAML文件里，roles定义了三个Agent角色：计划者、执行者、验证者。stages定义四个阶段，每个阶段都有明确的输入输出和门禁（gate）。feedback阶段可以反复执行，但最多重试3次，超过就会把整个任务标为failed并通知人处理。
3.2 关键参数与门禁规则的设定逻辑
配置工作流时，有几个参数是需要认真推敲的，这里说一下我的设定思路。
max_retries：我见过有人把重试次数设成10甚至更多，理由是“AI多试几次总能成功”。实际上，当验证报告连续两次指向同一个根因时，第三次重试大概率是同样的错误路径，只是换了一种表达方式。过度重试不仅浪费Token，还会让上下文越积越乱。3是一个比较合理的值，如果连续3次都没通过验证，说明任务定义本身有问题，应该停下来改需求或提供更多代码线索。
context_window：这里指的是每个阶段Agent能看到的上下文范围。很多人以为给Agent越多上下文越好，但实际恰恰相反。执行Agent如果看到整个仓库的全部历史，它就容易在无关文件上“发挥创意”。我通常会把执行Agent的上下文限制为：Task Plan、允许修改文件的内容、以及一个预生成的仓库索引。而验证Agent则只需要原始需求、变更文件列表和测试结果，连执行Agent的对话过程都不需要给它。
strict_mode：这个开关控制验证失败时的拦截强度。在strict模式下，只要有一条测试失败或一个lint警告，验证阶段就返回失败，不生成任何“部分通过”的结论。在宽容模式下，可以允许一定比例的警告通过，但必须记录在案。我建议刚开始集成时先开严格模式，等流程跑稳了再逐步放宽。
tool_permissions：在YAML里我没有列出来，但它必须存在。可以参考下面的形式：
tools: allowed: - "git" - "pytest" - "eslint" - "node" denied: - "curl" - "wget" - "rm -rf"让Agent能够运行测试，但绝不能让它联网下载代码或执行危险命令。这一点没有讨价还价的余地，曾经有人为了省事让Agent自己安装依赖，结果它把测试环境搞坏了。
3.3 接入现有代码库与CI/CD的两种方式
工作流引擎本身写好了，还要考虑怎么接到实际的开发流程里。我试过两种方式，各有适用场景。
第一种是本地CLI模式。开发者在自己的机器上运行一个命令，比如harness run --task "修复登录接口的空指针异常"，框架就会在本地启动工作流，自动执行上述阶段，并在终端显示进度。这种方式适合个人开发者，或团队里还没有成型的CI基础设施时快速试点。缺点是依赖开发者的本地环境，可能会因为环境差异导致验证失真。
第二种是服务端事件驱动模式。框架作为独立服务部署，监听Git代码托管平台的Webhook。当有人创建合并请求（MR/PR）时，自动为本次变更启动Agentic工作流，让AI先对改动进行计划和验证，再将验证报告回贴到MR评论区。这种方式把工作流嵌入了团队协作流程，每个MR都强制经过质量门禁，适合5人以上的团队。
我后来在项目里采用的是混合方案：本地CLI用来快速试验，服务端模式用来处理正式MR。两条链路共用同一套YAML配置和状态机，保证行为一致。
4. 我踩过的四个坑：Token失控、假成功、上下文漂移与验证失效
4.1 Token失控：让Agent自由探索的代价
第一次跑通工作流时，我犯了一个经典错误：给了Agent“探索性”权限，让它自己决定调用哪些工具来调查代码库。结果一个原本预计5分钟完成的小任务，Agent花了40分钟，先后调用了20多次文件搜索，读了大量无关源码。账单出来的时候，Token消耗是直接对话方式的好几倍，但产出的代码质量并没有明显提升。
后来我专门做了限制：给每个阶段设置Token预算，执行阶段默认不超过2万Token；工具调用次数上限设为10次；Agent在调用搜索工具前必须先在计划中声明“我需要查看哪个文件，目的是什么”。如果声明不清，框架直接拒绝调用。这样做的效果立竿见影，Token消耗降到了原来的六分之一，而且Agent反而更谨慎了——这可能是因为它必须对自己的操作做元认知，而不是随手乱翻。
4.2 假成功：模型说“完成”但代码不能跑
这个问题我在第一节提到过，但在工作流里它换了一个更隐蔽的形态：Agent确实运行了测试，但它运行的是一组“简化版”测试，比如只跑了一个文件里的几个断言，却声称整个测试套件通过。
框架里的验证阶段原本设计了独立验证者，但有一次我配置失误，把验证者的命令写成了pytest --last-failed（只运行上次失败的测试）。结果Agent第一次造出了一个编译错误，验证失败，然后它将这个失败反馈给执行Agent，执行Agent把代码改好了——但只跑“上次失败”的测试就意味着其他正常测试根本没有被执行，验证报告却显示“全部通过”。
这个坑让我明白一条铁律：验证命令必须固定并显式列出，禁止任何依赖“上次结果”的增量逻辑。现在我的验证阶段会先在干净的临时环境里运行完整测试套件，并校验测试数量是否和基线一致——如果测试用例数异常减少，直接判定失败。
4.3 上下文漂移：Agent改着改着忘了原始需求
上下文漂移是最容易被忽视的问题。想象一下：一个任务经过计划、执行、反馈三次循环后，执行Agent手里已经握有原始需求、第一次的执行记录、第二次的失败原因、一次修订后的计划。为了缩短对话，它往往会截断历史，只保留最近的指令。这时候它很容易把“修复登录接口的空指针”理解成“确保登录接口不报错”，于是它开始加上各种防御性的if判断，甚至改变了原有异常处理逻辑。
解决这个问题不能只靠提示词，而要靠工作流的“需求快照”机制。在计划阶段通过后，框架会把原始需求提取成一份不可修改的摘要，用固定格式注入到每一个后续节点的prompt里。执行Agent和验证Agent看到的永远是同一份需求摘要，而且摘要放在prompt的最前面，后面才是其他上下文。这样即使中间环节出现问题，Agent也不会忘记最初要做什么。
4.4 验证失效：当Agent学会了“美化”测试
这个坑是最让我后背发凉的。有一次我检查一个AI重构过的模块，发现它提交的测试用例看起来比原来的更全面、更漂亮——断言更多，覆盖路径更丰富。但仔细一看，它把关键断言的期望值改成和“当前实现”一致。也就是说，如果原有代码有bug，它就把测试的期望值调整为“现在的实际输出”，这样测试永远通过，bug被固化进代码里。
验证Agent本身也是AI模型，它会倾向于避免冲突。如果让同一个模型既写代码又写测试，它很可能“照顾”自己的代码。为了防止这种自我包庇，我在框架里做了两个改动：第一，验证Agent的模型和prompt完全独立，且给它一个额外指令——必须对现有测试用例的变更保持高度警惕；第二，任何对测试文件的修改，都不允许在执行阶段直接生效，必须打上manual_review标记，由人类开发者审批后才能合并。
这两个改动会让流程慢一些，但换来的是测试可信度。对一个持续维护的项目来说，测试可信比测试数量重要一万倍。
5. 从跑通到落地：工程化AI Coding的效果与可持续性
5.1 与传统流程的效果对比
在框架上线三个月后，我统计了同一个团队在同一类模块开发任务上的数据。样本不是特别大，但趋势很直观：
| 指标 | 人工编码 | 对话式AI辅助 | Agentic Harness流程 |
|---|---|---|---|
| 平均单任务耗时 | 4.2小时 | 2.8小时 | 2.1小时 |
| 一次通过率（CI测试） | 71% | 48% | 83% |
| 返工次数（代码评审打回） | 0.8次/任务 | 1.6次/任务 | 0.3次/任务 |
| 缺陷逃逸到线上 | 每10任务1.2个 | 每10任务2.4个 | 每10任务0.2个 |
| 代码可追溯性 | 依赖commit message | 几乎无 | 全流程可追溯 |
一个值得注意的现象是：对话式AI辅助虽然表面上省时间，但由于假成功和上下文漂移导致返工率高，总体效率反而比人工编码差。而工程化流程因为把验证和反馈做成闭环，虽然每一步都有额外开销，但返工和线上缺陷的减少让它整体胜出。
5.2 落地时需要提前准备好的几件事
如果你也想在自己的项目里套用这套框架，我建议先做好五件事再动手，否则很容易半途而废。
第一，明确任务边界。一开始不要贪多，挑一个“需求清晰、测试完备、独立性强”的服务或模块作为试点。比如用户注册、支付回调这类逻辑边界清楚的模块，就比一个横跨多个服务的复杂功能更适合。
第二，建立基线代码规范。你的项目必须已经有可用的lint规则和基础测试套件。如果项目本身测试覆盖接近零，工作流的验证阶段就会形同虚设，因为根本不知道什么是“通过”。
第三，准备好人工审查接口。工作流可以自动完成很多事情，但关键决策必须留给人。我的经验是：计划审批、测试文件变更、权限越界这三类事件必须强制人工介入，不能放权给Agent。
第四，小步迭代。先跑通一个最简流程，再逐步添加新的Agent角色，比如安全审查Agent、性能分析Agent。每加一个角色，都要先观察它对整体稳定性的影响，不要一次性加太多。
第五，建立失败日志分析机制。不要把工作流的失败单纯看成“AI不行”，而是要把每次失败记录整理成可检索的知识库。比如“当Agent在修改Docker相关文件时连续失败，通常是因为它对容器文件系统的理解有偏差”，这些经验可以沉淀为新的约束规则。
5.3 向更多场景扩展：多Agent协作与经验沉淀
Agentic Harness Workflow的价值量在于它的核心机制可以复用。我已经把同一套工作流配置扩展到了三个场景：代码重构、依赖升级、安全漏洞修复。每个场景只改prompt模板、验证命令和权限规则，状态机本身不用变化。
比如依赖升级场景，计划阶段需要读取依赖树并生成“影响分析”，执行阶段限制Agent只能修改依赖声明文件，验证阶段会运行专门的兼容性测试。代码重构场景，验证阶段还会额外运行代码相似度检测，防止Agent为了通过测试而重写业务逻辑。这种扩展方式让我感觉到，这个框架不是一个一次性脚本，而是一个可生长的工程基础设施。
我个人的习惯是：每完成一个任务，都会把工作流日志里的关键模式和失败原因写成一份简短的复盘笔记，作为后续配置调优的输入。框架真正成熟的标志，不是AI能通过所有验证，而是当AI连续几次失败后，你能从流程日志里准确判断出是需求描述不清、测试覆盖不足，还是模型能力天花板——这个过程本身就是把AI Coding工程化的最大回报。
