Agentic Harness Workflow：用工程化流程驯服AI编程

1. 从"对话式写代码"到"流水线造软件"的认知转变

大多数人用 AI 辅助编程，还停留在"打开对话框，描述需求，复制粘贴代码"的阶段。这种方式在写一个工具函数、补一段正则表达式时确实够用，但一旦面对真实项目——比如给一个已有系统加一套权限模块、重构一个耦合严重的服务层、或者从零搭一个带测试和文档的完整功能——对话式写代码就会暴露出致命问题：上下文丢失、需求漂移、生成结果不可复现、质量全靠运气。

Agentic Harness Workflow 框架要解决的就是这件事。它把 AI Coding 从"聊天"升级成"工程化流程"，核心思路是给 AI 智能体套上一个结构化的"挽具"（Harness），让它在明确的阶段、明确的输入输出、明确的验收标准下工作，而不是自由发挥。你可以把它理解成：以前是让一个实习生凭感觉干活，现在是给这个实习生配了一套标准作业程序、检查清单和交接规范。

这套框架适合谁？如果你是一个人扛一个项目的独立开发者，它能帮你把 AI 的输出稳定性拉高一个档次；如果你是团队里负责搭建 AI 辅助开发流程的人，它提供了一套可直接落地的阶段划分和产物规范；如果你只是好奇 AI Coding 到底能做到什么程度，它也能让你看清"能自动化的边界"在哪里。

我最初接触这套思路，是因为一个真实痛点：用对话方式让 AI 改一个跨三个文件的接口，改了三次，每次它都"忘记"之前约定的数据结构，最后我不得不把整个上下文重新贴一遍。那次之后我开始琢磨，能不能把"需求确认、方案设计、分步实现、验证回归"这些人类工程师天然会做的动作，固化成 AI 必须走的流程。Agentic Harness Workflow 就是这套琢磨的产物。

2. Harness 到底"套"住了什么：框架的核心机制拆解

2.1 为什么叫 Harness 而不是 Framework

Harness 这个词在工程语境里，指的是"约束装置"——比如测试框架里的 test harness，它的作用不是帮你写测试，而是给测试提供一个可控、可复现的运行环境。Agentic Harness Workflow 借用这个词，强调的是"约束"而非"能力"。

AI 智能体本身能力已经足够强，缺的不是智力，而是纪律。Harness 的作用就是给智能体套上纪律：在什么阶段只能做什么事、每个阶段的产物必须满足什么格式、什么条件下才能进入下一阶段。这跟传统开发框架（比如 Spring、Django）的思路完全不同——那些框架是给你提供能力，Harness 是给你提供约束。

这个区别很关键。很多人搭 AI 工作流，第一反应是"我要给它加更多工具、更多能力"，结果越加越乱。正确的思路是反过来：先想清楚"我要限制它在每一步只能干什么"，约束清晰了，能力自然被引导到正确的方向上。

2.2 四个核心阶段与各自的产物

这套框架把一次完整的 AI Coding 任务拆成四个阶段，每个阶段有明确的输入、输出和验收标准：

注意这里的顺序是强制的。我见过太多人跳过"需求澄清"直接让 AI 写代码，结果写出来的东西方向就错了，返工成本极高。Harness 的价值就在于用流程强制你"先想清楚再动手"，这一点对人类工程师同样适用。

2.3 阶段之间的"交接契约"

四个阶段不是简单串联，每个阶段之间有一份"交接契约"。这份契约规定了上一阶段必须交付什么、下一阶段可以假设什么。比如需求澄清阶段结束时，必须产出一份包含"功能点列表、边界条件、非功能要求"的规格文档，方案设计阶段才能开始。

这份契约的存在，解决的是 AI 最典型的毛病：上下文漂移。对话式编程里，AI 会随着对话轮次增加逐渐"忘记"早期约定。而契约是显式的、结构化的，每次进入新阶段都重新加载，相当于给 AI 做了一次"记忆重置"，但重置的是经过提炼的精华，而不是原始对话。

提示：交接契约建议用结构化格式（如 YAML 或 Markdown 表格）而不是自然语言段落。结构化格式对 AI 更友好，解析时不容易产生歧义。

3. 需求澄清阶段：把"我想要个登录功能"变成可执行规格

3.1 模糊需求是万恶之源

"我想要个登录功能"——这句话交给 AI，它能给你生成十种完全不同的实现。有的用 session，有的用 token，有的把密码明文存了，有的连密码哈希都没做。问题不在 AI，在于需求本身太模糊。

需求澄清阶段的任务，就是把这类模糊描述逼成结构化规格。我的做法是让 AI 扮演一个"爱抬杠的需求分析师"，对每一条需求追问三个问题：输入是什么、输出是什么、异常情况怎么处理。这三个问题问完，模糊需求基本就现形了。

举个例子，"登录功能"经过追问会变成：输入是用户名和密码，输出是登录凭证或错误码，异常情况包括用户名不存在、密码错误、账号被锁定、连续失败次数超限。每一条异常都要有明确的处理策略，而不是笼统的"报错"。

3.2 用"可测试性"作为需求的验收尺

一条需求是否澄清到位，判断标准很简单：能不能直接写出一条测试用例来验证它。如果写不出来，说明需求还不够具体。

比如"系统要安全"这种需求，写不出测试用例，必须细化成"密码存储使用加盐哈希，哈希算法迭代次数不低于 10 万次"——这样才能写测试。我在实操中会让 AI 对每条需求自动生成对应的测试用例草稿，生成不出来的需求就打回去重新澄清。这个动作看起来繁琐，但能挡掉大量后期返工。

3.3 边界条件清单的建立

需求澄清阶段还有一件容易被忽略的事：建立边界条件清单。正常流程谁都能想到，真正让项目翻车的是边界。空输入、超长输入、并发请求、网络中断、数据库连接失败——这些情况在对话式编程里几乎不会被主动考虑，但在 Harness 流程里是强制项。

我的做法是维护一份通用的边界条件检查表，每次需求澄清时逐条过一遍，不适用的划掉，适用的补上具体处理策略。这份表包括：空值、极值、并发、超时、部分失败、重复提交、权限越界七大类。过一遍大概十分钟，但能省下后期几小时的调试。

4. 方案设计阶段：让 AI 先画图纸再砌墙

4.1 接口先行：为什么签名比实现更重要

方案设计阶段的核心原则是"接口先行"。先确定模块之间怎么交互、函数签名长什么样、数据结构怎么定义，再去写具体实现。这个顺序不能反。

原因在于，接口是模块之间的契约，一旦定下来，各个模块就可以并行开发和独立测试。如果先写实现再定接口，实现里的细节会"泄漏"到接口设计里，导致模块之间耦合严重。AI 在这方面特别容易犯错误——它倾向于直接给你一大段能跑的代码，但这段代码的边界是模糊的。

我通常会让 AI 先只输出接口定义，包括函数名、参数类型、返回类型、抛出的异常。这一步不写任何实现逻辑。等接口确认无误后，再逐个填充实现。实测下来，这个"多一步"能让后期修改成本降低一半以上。

4.2 技术选型的"三问"决策法

方案设计绕不开技术选型。用哪个数据库、哪个框架、哪个库，这些决策如果拍脑袋定，后期很容易后悔。我总结了一个"三问"决策法，让 AI 辅助做选型时按这个框架走：

第一问：这个选型解决的核心问题是什么？如果答不上来，说明可能根本不需要引入它。第二问：有没有更简单的替代方案？复杂度是要付出代价的，能简单就别复杂。第三问：如果这个选型将来要换掉，迁移成本有多大？这一问决定了要不要在它外面包一层抽象。

这三问看起来朴素，但能挡掉大量"为了用而用"的技术选型。我见过一个项目引入消息队列只是为了发几封邮件，结果运维复杂度翻了三倍。三问法能有效抑制这种冲动。

4.3 模块划分的粒度控制

模块划分太粗，一个模块承担太多职责，改一处牵动全身；划分太细，模块间调用关系复杂，理解成本高。合适的粒度怎么把握？

我的经验是：一个模块应该能用一句话说清楚它负责什么，且这句话里不出现"和"字。如果需要用"和"来连接两个职责，说明该拆了。比如"用户认证和权限校验"就应该拆成两个模块。这个标准简单粗暴，但实操中非常好用。

在 Harness 流程里，模块划分的产物是一张模块依赖图（用文字描述即可，不需要画图工具）和每个模块的职责说明。这张图是后续分步实现的路线图，也是验证阶段检查"有没有漏掉模块"的依据。

5. 分步实现阶段：小步快跑与每步可验证

5.1 为什么必须"一步一验证"

分步实现阶段最容易犯的错误，是让 AI 一口气把整个功能写完。看起来效率高，实际上风险极大——一旦中间某步出错，你面对的是几百行纠缠在一起的代码，定位问题的时间远超省下的时间。

Harness 流程强制"一步一验证"：每完成一个模块或一个函数，立刻跑测试、立刻验证。验证通过才进入下一步。这个纪律看起来拖慢速度，实际上大幅提速，因为问题在刚产生时就被发现，修复成本最低。

我通常把实现步骤拆到"单个函数"级别。一个函数写完，跑它的单元测试，通过，提交，再写下一个。AI 在这个粒度下表现最稳定，因为它每次只需要关注一个明确的、小范围的任务，不容易跑偏。

5.2 测试与实现同步生成

在 Harness 流程里，测试不是实现完成后的补充，而是和实现同步生成的。每写一个函数，同时写它的测试。这样做有两个好处：一是测试能立刻验证实现是否正确，二是写测试的过程会逼你想清楚这个函数的边界条件。

让 AI 同步生成测试时，要明确告诉它测试的目标：正常路径、边界条件、异常路径各覆盖哪些。不要只说"写个测试"，那样它只会给你一个最基础的正常路径测试。我通常会给一个测试清单模板，让 AI 按模板逐项填充。

5.3 提交粒度的把握

分步实现阶段还有一个实操细节：提交粒度。我的习惯是"一个可验证的单元一次提交"。一个函数加它的测试算一个单元，一次提交。这样每次提交都是可回滚的、可理解的，出问题能精确定位到是哪次提交引入的。

AI 生成的代码尤其需要这个纪律，因为它的输出量大、速度快，如果不控制提交粒度，很容易积累出一大堆"不知道改了什么"的变更。等到出问题时，面对一堆混杂的变更，排查难度极大。

注意：分步实现阶段不要追求"一次写对"。AI 生成的代码有问题是常态，重要的是让问题暴露得早、定位得快。小步提交 + 每步验证，就是实现这个目标的手段。

6. 验证回归阶段：AI 写的代码怎么才算"过关"

6.1 测试通过不等于质量过关

测试全绿就万事大吉了吗？远远不够。测试只能验证你想到的情况，想不到的情况它验证不了。验证回归阶段要做的是"测试之外"的检查。

我通常会让 AI 做三件事：第一，检查测试覆盖率，找出没被测试覆盖的分支；第二，做一次"对抗性审查"，让 AI 扮演一个挑剔的代码审查者，专门找实现里的问题；第三，检查边界条件清单，逐条确认是否都有对应处理。这三件事做完，质量才有基本保障。

6.2 对抗性审查的具体做法

对抗性审查是这套流程里我觉得最有价值的一环。具体做法是：把实现代码和需求规格一起交给 AI，让它以"找茬"为目标进行审查，而不是以"确认正确"为目标。这两种心态下，AI 的输出质量差异巨大。

审查的维度我通常固定为几个：逻辑正确性、边界处理、错误处理、资源管理、并发安全、可读性。每个维度让 AI 单独输出发现的问题，不要混在一起。分开审查能让每个维度都得到充分关注，混在一起时 AI 容易顾此失彼。

6.3 变更说明与知识沉淀

验证通过后，还有一件收尾工作：写变更说明。这份说明不是给领导看的，是给未来的自己和协作者看的。它要回答三个问题：这次改了什么、为什么这么改、有什么遗留问题。

AI 生成的变更说明往往过于笼统，比如"优化了登录逻辑"。这种说明等于没写。我会要求 AI 按"变更点 + 原因 + 影响范围"的格式逐条列出，每一条都要具体到函数或模块级别。这份说明积累下来，就是项目的知识库，下次改相关代码时能快速理解上下文。

7. 实操中踩过的坑与应对经验

7.1 阶段跳跃：最常见的翻车原因

我踩过最大的坑，是图省事跳过需求澄清直接进实现。当时觉得需求很明确，没必要走流程。结果实现到一半发现有个关键边界没考虑，整个数据结构要改，前面写的全废。那次之后我给自己定了死规矩：再简单的需求也要走完澄清阶段，哪怕只花五分钟。

阶段跳跃的诱惑在于"看起来能省时间"，但省下的是前期的小时间，付出的是后期的大时间。Harness 流程的价值恰恰在于用前期的纪律换后期的稳定，跳过任何一步都是在破坏这个交换。

7.2 契约格式不统一导致的解析失败

交接契约如果格式不统一，AI 在下一阶段解析时容易出错。我早期用自然语言写契约，结果 AI 经常"理解偏了"。后来改成固定的 Markdown 表格格式，每个字段名固定，问题就少多了。

格式统一还有一个好处：可以写脚本自动校验契约的完整性。比如检查需求规格里每条需求是否都有对应的测试用例，这种校验用脚本做比人眼可靠得多。

7.3 AI 过度自信导致的"假通过"

AI 有个毛病：它倾向于告诉你"完成了""通过了"，即使实际上并没有。在验证阶段，如果只是问它"测试通过了吗"，它很可能回答"通过了"，但实际测试根本没跑。

应对办法是让 AI 输出可验证的证据，而不是结论。比如要求它贴出测试运行的输出、列出实际执行的命令、给出具体的覆盖率数字。有证据的结论才可信，没有证据的"通过了"一律当作没通过处理。

7.4 上下文膨胀的处理

随着流程推进，上下文会不断膨胀，到后期 AI 可能因为上下文过长而"注意力涣散"。我的处理办法是每个阶段开始时，只加载该阶段必需的契约和产物，不加载全部历史。比如进入实现阶段时，只加载设计说明和接口定义，不加载需求澄清阶段的完整讨论记录。

这个做法相当于给 AI 做"上下文瘦身"，让它每次只关注当前阶段需要的信息。实测下来，这样能显著提升 AI 在后期阶段的输出质量。

8. 把这套流程用起来的几个实际建议

如果你打算在自己的项目里试这套框架，我的建议是从小处着手。不要一上来就搞全套，先挑一个中等复杂度的功能，走一遍完整的四阶段流程，感受一下每个阶段的价值。走通一遍之后，你自然会知道哪些环节对你的项目最有价值，再针对性地强化。

工具层面，这套流程不依赖特定工具，用任何支持多轮对话的 AI 助手都能跑。关键是流程本身，不是工具。我见过有人花大量时间折腾工具链，结果流程本身没跑通，本末倒置。

最后分享一个我自己的小习惯：每次走完流程，花五分钟记录一下这次哪个阶段最顺、哪个阶段最卡。积累几次之后，你会发现自己项目的"流程瓶颈"在哪里，然后针对性地优化。这个习惯坚持下来，流程会越用越顺，AI Coding 的产出质量也会稳定在一个可预期的水平上。