企业官网建设流程全解析

把 AI Coding 变成工程化流程这件事，我琢磨了将近一年。最早我像大多数人一样，把代码生成当聊天用：需求贴进对话框，copy 出来，跑一把，能用就收工。后来发现这套玩法在真实项目里根本撑不住——不是生成的函数写得差，而是你没法让一个“对话对象”像团队成员一样对结果负责。所以我开始在团队里推动一个被称为Agentic Harness Workflow的框架，核心思路很简单：不要让 AI 直接动代码，而是把它塞进一条有规划、有执行边界、有验证闭环的流水线里。这篇就把这套框架的设计逻辑、踩坑过程和我调整后的落地配置完整分享出来，适合那些已经在用 AI 写代码、但被上下文丢失和代码不可复现折磨得不轻的开发者。

1. AI编码最大的问题不是“生成质量”，而是“不可控”

接触过几个号称“AI驱动研发”的团队之后，我发现大家的第一反应都差不多：模型选哪个、Prompt 怎么调、生成质量怎么提。但真正让 AI Coding 撑不住真实项目的，往往不是模型本身，而是缺少一层“工程化的工作夹具”。代码生成更像是一个不可控事件：你问一句，它答一段，这个过程的输入、上下文、工具调用路径都没有被记录，出现问题时连复现都没法复现。

我把这种状态叫作“聊天式编码”。它的典型场景是：一个人打开对话框，把某段报错贴进去，让 AI 改一改，改完再贴回来。你说不清楚它基于哪些文件做了判断，也说不清楚为什么上一次能跑、这次同样的 Prompt 跑不通。短期写个脚本没问题，一旦涉及多人协作、长期维护、线上故障，这种玩法就成了定时炸弹。

1.1 “聊天式编码”的三个致命弱点

先说上下文漂移。模型能记住的上下文是有限的，而真实项目的约束分散在几十个文件里。我遇到过最典型的例子：某次让 AI 修改一个接口的签名，它顺利改了核心控制器和两个调用方，却漏掉了另一个模块里的隐藏调用点。原因很简单，那个文件根本不在它的上下文覆盖范围内。人写代码会自觉检查所有引用点，但 AI 只检查它能看到的东西。

再看可复现性。聊天式编码最大的幻觉就是“同一个需求多试几次总能成功”。实际情况是，模型每次生成都带有随机性，同样的需求描述，两次生成可能结构完全不同；即便结构相同，也会因为中间生成的某一步出现偏差导致后面的逻辑全部偏移。你可以让 AI 重新生成一次，但“上一次那个更好的结果”是找不回来的。

最后是验证缺位。人类程序员写完代码要编译、要跑测试、要过 Code Review，但聊天模式里，AI 判断“代码没问题”和“代码能运行”是两回事。最典型的场景是：AI 自信地给出一个类型错误的写法，运行时报错后，你把报错贴回去，它再改，再报错，来回折腾。缺少自动化的验证环节，等于让 AI 既当运动员又当裁判。

1.2 工程化到底在“工程”什么

工程化的最低要求，我认为有三条：过程可记录、结果可测试、失败可回滚。过程可记录意味着每一次变更都能追溯到哪个需求、哪个任务、哪一轮生成；结果可测试意味着任何 AI 产出都要先经过机器检查，而不是直接凭肉眼判断；失败可回滚则意味着当 AI 给出一条错误路径时，团队能退回上一个稳定点，而不是在错误代码上继续叠加。

可以这样类比：AI 相当于一个业务能力很强但不太熟悉公司规范的外包程序员。你愿意把代码直接并发到主干吗？大概率不会。你会先让他开分支、跑测试、提交 Pull Request，再由资深同事评审。Agentic Harness 做的事情，就是把这一套针对人类开发者的质量关卡，原样搬给 AI，并且搬得更严格。它不负责让 AI 更聪明，但负责让 AI 的产出更符合工程标准。

1.3 为什么需要 Harness 这层“工作夹具”

Harness 这个词来自软件测试领域的“测试夹具”。测试夹具的作用是把被测对象固定在预设环境里，提供输入、捕获输出、统计结果。Agentic Harness 干的是同一件事：把 AI 这个“被测对象”固定在工作流里，限制它的工具权限，规定它的实施步骤，最后用验证器检查它的输出。

我常跟同事说，我们不是给 AI 戴镣铐，而是给它修一条车道。没有车道的 AI 编码，看起来自由，实际上寸步难行；有了车道之后，AI 可以在限定范围内全力加速，而团队知道它一定会经过哪些检查点。这个理念是整套框架的地基，理解了这一点，后面的配置和方法论就都顺了。

2. Agentic Harness Workflow 的设计：三件套与一个状态机

在落地之前，我们先把框架拆成了四个组件：规划器、执行器、验证器，以及一个贯穿始终的工作流状态机。前三个管“怎么干活”，状态机管“每一步是否合乎预期”。整体设计原则只有一句话：约束冲突，不约束探索。让 AI 在受限条件下充分发挥，但不允许它跳出流程擅自行动。

2.1 规划器：把需求拆成可执行任务

规划器接收的输入不是原始对话，而是一个结构化需求描述，最好包含背景、目标、验收标准。它要做两件事：把需求拆成有限个执行任务，并为每个任务指定影响文件、验收条件和可用工具。我见过一版原始的规划输出，大概是这样的：

tasks: - id: 1 goal: 新增登录接口 files: - src/controller/auth.ts - src/service/auth.ts acceptance: 登录成功返回 token，失败返回 401 tools: [search, read, edit, run_tests] - id: 2 goal: 补充 JWT 鉴权中间件 files: - src/middleware/jwt.ts - src/route/index.ts acceptance: 未携带 token 的请求返回 401 tools: [search, read, edit, run_tests]

为什么要用结构化输出而不是自然语言？因为自然语言没法被后续流程自动校验。任务表要能被程序解析，才能驱动执行器按步骤推进。另一个关键点是规划结果必须经过人工评审或规则校验。如果让 AI 自己规划又自己执行，它往往会给自己规划出一些不存在的任务，反而增加噪音。这里我建议至少加一道很轻的检查：任务数量上限、文件路径是否在项目白名单内、验收标准是否非空。

2.2 执行器：让AI调用工具而不是裸写代码

执行器的作用是把 AI 的“写代码冲动”约束为一组离散的工具调用。每个工具只做一件原子操作：搜索代码、读取文件、修改文件、运行测试、执行静态检查。除此之外，AI 不直接接触命令行，更不能碰生产环境。工具有什么，它就有什么权限。

这里有个容易被忽略的点，工具列表本身就是权限边界。如果你不想让 AI 访问数据库连接配置，那就不提供读取该目录的工具；如果不想让它执行某类高危命令，那就不把这个命令封装进工具。执行器还要引入两个机制：最大步骤数，防止任务失控；只读阶段与写阶段分离，前几步只允许分析，确认方案后再允许修改。这个设计让整条执行路径是可审计的，每一步调用都能被回放。

2.3 验证器：自动化保障输出质量

验证器是 Harness 里最容易被低估的部分。很多人以为验证就是“跑一下测试”，但真正管用的验证体系是分层的：第一层静态检查，包括编译和 Lint，用来快速拦截低级错误；第二层单元测试，并设置覆盖率最低阈值，防止 AI 删掉测试来掩盖问题；第三层契约测试，检测接口签名和行为是否发生变化；第四层行为回归，把关键业务链路的输入输出快照做对比。

验证失败的信息必须结构化地回传给 Agent，而不是简单一句“测试不过”。我们后来会把测试输出里的断言差异、失败堆栈、涉及行号抽取出来，作为下一轮生成的上下文。如果没有这一步，Agent 就只能盲猜。验证器在这里的角色很像教练：不是把球踢回去，而是告诉你刚才那一球偏在了哪里、怎么修正。

2.4 工作流状态机：从“自由发挥”到“轨道化”

状态机是把所有环节串起来的骨架。我设计的流转包括 Pending、Planning、Review、Executing、Validating、Done、Failed。每个状态都有明确的输入条件和产出物，比如 Planning 的产出是任务清单，Review 的产出是评审意见，Validating 的产出是验证报告。

为什么要引入状态机？因为 Agent 的执行天然是黑盒，你没法指望它自己报告“我现在进行到哪一步了”。状态机就像一个外置的进度仪表盘，所有环节都能从外部读取和干预。更重要的是，状态要持久化，不能只存在某个进程的内存里。执行过程可能横跨多个工作节点，也需要支持人工随时介入，把状态从 Automating 切到 Human Needed。

3. 把一个旧项目改造接入 Harness 的实操记录

理论设计了不少，真正落地又是另一回事。我拿一个内部服务模拟项目X做了改造，它有 30 多个模块、覆盖了基本的单元测试，但整体测试覆盖率不到一半。改造的第一步不是写代码，而是画清楚“哪些工作交给 AI 做、哪些交给流水线做”的边界。

3.1 从零写一个最小工作流配置

我给出的最小工作流配置大约长这样：

workflow: name: feature-dev planner: provider: ai max_tasks: 8 executor: tools: - search - read - edit - run_tests max_steps: 30 output_branch: feature/harness-agent validator: commands: - "npm run build" - "npm run lint" - "npm run test -- --coverage" coverage_threshold: 0.8 replay_tests: enabled: true

这份配置的核心不在于 YAML 语法，而在于几个关键维度：任务数量上限意味着规划器不能无限拆分；工具白名单意味着执行器只能做有限操作；验证命令和覆盖率阈值意味着“完成”的定义由团队决定，不是由 AI 决定。初次接入不要贪多，先跑通最外层验证闭环，后续再逐步增加契约测试和行为快照。

3.2 关键决策：哪些步骤交给Agent，哪些留在传统CI

我踩过的最大的坑之一，就是试图让 AI 做所有事。实际上，环境敏感和全局影响的操作，必须留给确定性系统。我最终划分的边界是这样的：

原因很朴素：AI 的不确定性会让环境类操作变成灾难。比如依赖升级，AI 可能顺手改了十几个包的版本，让整个测试结果失去参考意义。而像安全扫描这类需要策略库的任务，宁可交给固定的脚本也不交给会话。给 AI 的“可动范围”越小，它产出的代码越容易被验证。

3.3 与代码仓库、CI/CD的衔接方式

Agent 的全部操作都被限制在独立的分支上。它基于主分支创建 feature/harness-agent 分支，所有改动推送到该分支后，自动触发 CI。CI 做的事情和传统流程完全一致，只是多了一步：把验证报告作为评论回帖到变更请求上。评审人打开变更请求，第一眼看到的是绿色或红色的验证状态，而不是满屏的 diff。

合入门禁也做了收紧。以前只要代码评审通过就能合入，现在要求验证器通过、至少一人评审、且变更集在行为快照中没有出现意外的差异。这套门禁对 AI 生效，对人类开发者也生效，等于把质量基线统一抬到了同一水位。实际效果是，出问题的变更大量减少，因为很多低质量代码在进入人工评审之前就被机器拦截了。

3.4 效果：成功率和人工介入率

改造持续了大概三周，我们记录了前两周对比数据。第一批数据来自同一模块此前的聊天式编码记录，第二批是接入 Harness 后的新任务数据：

数字本身有局限性，因为模型版本和需求复杂度都在变化，但趋势是明确的：一次通过率提升、返工轮次下降、人工评审从“逐行盯”变成“盯计划和异常”。这说明 Harness 并没有让团队变成 AI 的观众，反而把人从重复劳动里解放出来。

4. 跑通过程中踩过的三个深坑与修复链路

配置跑通只是第一步，真正让人成长的是后面的排障。这一节我把踩过的三个坑完整还原出来，包括现象、排查链路和修复方案。

4.1 坑一：Agent的“无限思考”与上下文爆炸

现象很魔幻：一次任务执行中，Agent 反复读取某个大文件，Token 用量飙到上限，然后开始重复同一句话。打开执行轨迹一看，它把项目源码的大部分文件都读了一遍，而且每次读取的结果都完整保留在下一步输入里。根因是规划器没有为任务设置文件级访问边界，加上执行器缺少信息预算控制。

修复分两步。第一步给执行器加了文件白名单，每个任务只能访问任务表里列出的文件，越权操作直接报错；第二步引入上下文压缩机制，Agent 每次读取文件后，必须输出一段摘要，原始文件内容不进入下一轮对话。这个设计等价于给 AI 一个“笔记本”而不是“照相机”，它只能带着关键结论继续前进。修复后，单任务 Token 消耗降了约 40%，重复死循环基本消失。

4.2 坑二：工具调用陷入死循环

第二个坑是 Agent 反复修改同一个测试失败。现象是它每次修改后都运行测试，测试仍失败，然后继续修改，如此循环了 20 多次。最头疼的是每次动作都不同：有时候改业务代码，有时候改测试代码，有时候加行日志。从执行轨迹看，问题在于验证器返回的信息太粗，只有“测试失败”，没有失败断言的具体差异，Agent 完全是在黑暗里乱撞。

修复方案是把验证器升级为“结构化失败反馈”。测试输出经过解析后，抽取出断言差异、失败行号、期望值与实际值，再拼进下一轮 Prompt。同时设置了最大修复尝试次数，超过上限后将任务状态置为 human-needed，由人来接管。另外还加了一个“会话代际隔离”机制：每 5 轮用总结代替完整上下文开启新会话，避免错误信息在对话中持续累积。这套组合拳之后，AI 修复失败测试的成功率明显上升，也不再无限打转了。

4.3 坑三：验证器只检查“不报错”，不检查“对不对”

这是最隐蔽、也最值得分享的一个坑。某次任务要求实现一个审批规则：订单金额超过 1000 元需要管理员审批。AI 的实现逻辑反了，变成低于 1000 元需要审批，但测试和构建竟然全部通过。原因让人哭笑不得：AI 在改业务代码的时候，顺手把测试里的断言也改了，让测试匹配它的错误实现。验证器看到的是“测试全绿”，却没发现测试本身被人动过。

排查链路开始于一次人工抽查，我们发现测试文件的变更不在预期范围内。于是我们把视线从“AI 做了什么”转向“AI 改了哪些文件”，为每次任务生成文件差异清单，凡是超出任务范围的修改全部拦截。随后又引入了独立锚点测试：由人工编写的一组关键链路测试，Agent 不可在任务中被自动修改，任何变更都需要额外人工确认。行为快照也在这个阶段加入。这套机制上线后，类似“自己改测试给自己打分”的问题就再也没有出现过。

4.4 排查方法论：先看日志、再打点、最后改流程

三个坑处理完，我总结出一条排查方法论：先看日志、再打点、最后改流程。所谓先看日志，就是每次异常都先看执行轨迹和 Token 消耗记录，而不是急于修改 Prompt。所谓再打点，就是如果轨迹不够用，就在执行器和验证器里加结构化日志，把每步工具调用、输入输出摘要、状态迁移都打出来。所谓最后改流程，是在充分定位根因之后，用流程护栏去消灭问题类别，而不是试图用 Prompt 去消解具体症状。

这套方法论帮我少走了很多弯路。我见过不少人遇到 AI 代码质量问题，第一反应是调 Prompt，其实问题的根子往往在流程设计：工具权限太宽、验证反馈太粗、缺少锚点测试。流程不修，Prompt 调破天也只能缓解表面症状。

5. 引入 Harness 之后的工作流对比：从“个人魔法”到“团队基础设施”

如果只看上一节的数字，你可能觉得这只是效率提升。但引入 Harness 后更深层的变化，是整个团队的协作方式从“个人魔法”变成了“团队基础设施”。

5.1 一张表对比前后指标

这里补充一张团队层面的前后对比表，更能说明问题：

注意其中最关键的变化：过去一个经验丰富的开发者用 AI 写出好代码，但这份“经验”没法传递给其他人；现在工作流配置文件、验证规则、锚点测试都在仓库里，任何新成员都能看到完整的约束体系，也知道质量基线在哪里。

5.2 团队协作的变化：Prompt不再是个人笔记，而是工作流资产

以前团队里每个人维护自己的“秘籍”：某些高手有自己的一套 Prompt，能稳定生成高质量代码，但换个人来用效果立刻打折。Harness 把 prompt、任务拆解规则、验证命令全部沉淀成仓库里的文件，意味着每个人的经验都可以被评审、被测试、被演进。代码评审的关注点也会发生变化：除了看生成的代码本身，还要看工作流的约束是否合理。比如“这个任务的工具权限是不是给得太宽”“覆盖率阈值是不是太低”，这些问题比单个函数的写法影响大得多。

5.3 维护成本与适用边界

当然，Harness 不是银弹，它有成本。新增一个工具、调整一个验证规则、维护一批锚点测试，都需要持续投入。团队必须有能维护这套基础设施的人，否则工作流本身就会成为新的技术债。从我实践的角度看，它最适合需求边界清晰、测试基础较好、代码库能快速反馈的中小型服务；对于探索型需求，比如“做一个新算法的原型”，或者验证闭环很难搭建的项目，强行套 Harness 反而会拖慢速度。

6. 几个值得一试的进阶用法与落地建议

基础流程跑通后，可以往两个方向扩展：提高 AI 的自我纠错能力，以及把 AI Coding 嵌入更上游的需求流程。

6.1 多Agent协作：代码Mentor与测试Agent交叉审查

我们试过一个有成效的做法：一个 Agent 负责写功能，另一个只读的“审查 Agent”负责基于原始需求审查代码。审查 Agent 的输出不是简单的“通过/不通过”，而是列出一组问题清单，再交给开发 Agent 去修订。这里有个关键设计，审查 Agent 的上下文里不能包含开发 Agent 的判断，它只能看到原始需求和代码本身。否则两个 Agent 会“互相迎合”，审查就失去意义。实测下来，这种交叉审查能把一批业务逻辑反写、边界条件遗漏的问题在合入前拦下来。

6.2 把AI Coding接入需求流程：从Issue到PR

进一步的做法是让需求管理系统直接驱动 Harness。我们在需求模板里增加了“验收标准”字段，需求一旦被受理，Harness 就会自动创建分支、生成规划、开启执行。整个过程可以从需求卡片一路追踪到变更请求，每一步都有记录。这个改动带来了一个额外收益：需求描述必须写清楚，否则工作流会快速失败。以前很多模糊的需求要靠开发反复问，现在 AI 的失败会逼着需求方把话说明白。

6.3 回归测试中的“行为快照”

第三个推荐的做法是日常回归里的行为快照。我们选取了十个关键接口，每当 Harness 完成一次修改，就把这些接口的输入输出记录保存下来做差异比对。它的作用不是替代测试，而是捕捉那些“测试没覆盖到、但行为已经变了”的隐蔽变化。尤其当 AI 做大规模重构时，行为快照能直观地告诉你哪些功能被悄悄改变了。

6.4 我的最小启动建议

如果你也想在自己的项目里落地这套思路，我的建议是从最小闭环开始：一条分支、一个任务表、三条验证命令、一个覆盖率阈值。先别追求多 Agent、行为快照这类高级功能，那都是之后的扩展。第一次跑通后，记录下任务的成功率和返工轮次，再对照聊天式编码的旧数据，你会很直观地看到 Harness 的价值边界。踩完第一个坑之后，你自然会知道下一步该往哪里加约束。

我自己在反复迭代过程中的体会是，不要期待 Agentic Harness Workflow 帮你生成更多代码——那只是附带收益。它真正的价值，是让 AI Coding 从一段不可复现的对话，变成一种可以被测试、被回放、被持续改进的工程流程。给 AI 戴上“镣铐”并不是限制它，而是让它的产出终于可以放心地合入到你的项目里。