AI编程工程化：Harness Engineering从入门到实战

AI 编程工具已经铺天盖地但大部分人的用法还停留在开个对话框让 AI 写一段复制粘贴跑不通就再让它改。说实话这么用不是不行但离工程化差了十万八千里。我今天想聊的 Harness Engineering核心就是把 AI 编程从碰运气变成可预期、可复现、可验收的事情标题写着傻子可懂不是噱头——我自己就是从完全没头绪的状态摸过来的这篇教程会把最朴素的那套方法论掰开揉碎讲清楚再带你完整跑一个项目实战。适合用过 Cursor、Copilot 或 Codex 这类工具但总觉得不踏实的人也适合想把 AI 编程正经纳入团队工作流的工程负责人。1. Harness Engineering 是什么从AI 能写代码到AI 能交付代码的鸿沟1.1 先看一个几乎每个人都会遇到的场景你让 AI 写一个带分页的用户列表接口它十秒钟给你一段看起来非常完整的代码。你复制进项目跑起来确实能返回数据。这时候你心里其实有三个问题说不出口这段代码有没有考虑数据库连接池耗尽的情况分页参数边界有没有校验如果明天需求改成按部门过滤这段代码还能不能优雅扩展这些问题在传统开发里是基本功但在 AI 编程的场景下大多数人直接跳过了。因为 AI 生成代码的过程太顺畅、太像一个正确答案了你会下意识降低警惕。我见过一个真实案例一个小团队让 AI 生成了一套用户认证逻辑本地测试全部通过结果部署到生产第二天就出了问题——AI 把密码重置的 token 存到了 Redis但没有设置过期时间。代码是能跑的但业务逻辑有明显漏洞。这不是 AI 的错是使用流程里压根没有让 AI 输出之前先想清楚安全边界这个环节。1.2 Harness 的本质给 AI 装上一副缰绳Harness 这个英文词本身的意思是马具、挽具引申出来就是驾驭工具的工具。放到 AI 编程领域Harness Engineering 就是一套围绕 AI 编程工具建立的流程、约束和验证机制目的是让 AI 的输出可预期、可审计、可回滚。它不是某个具体的软件也不是某条神奇的提示词。它是一套你自己定义的工作协议。最简单的形态包含四个要素任务来源需求是明确地、结构化地传给 AI 的不是模糊的一句帮我做个登录执行边界AI 知道哪些文件能碰、哪些不能碰知道验收标准是什么验证关卡AI 的输出必须通过测试、lint、安全检查才能被接受人工兜底每一步都有一个人你在关键节点做判断这四个要素拆开看大家都很熟悉但放进 AI 编程的语境里它们构成了一个完整的工程闭环。1.3 为什么现在这个概念突然变得重要2026 年的 AI 编程工具已经不只是补全代码的水准了。以 Codex、Claude Code 为代表的智能体型工具可以自主读仓库、改多个文件、跑测试、甚至提交 PR。能力上限提高了风险面也同步变大。一个能自主改代码的 AI在没有约束的情况下就像一匹没戴缰绳的马——跑得快但方向不可控。我见过有人让代理型 AI 重构整个模块结果它改了 40 个文件其中 15 个是无关的格式调整PR 根本没法审。这不是 AI 笨是我们没给它缰绳。Harness Engineering 要解决的问题恰好在这个层面让 AI 的自主性被装在流程里而不是裸奔。2. 搭建最小 Harness 的五个组件从需求到验收的完整闭环我不喜欢一上来就讲宏大理论直接从最小可用的 Harness 说起。一个能跑的 Harness 至少需要五个组件而且每个组件都有明确的目的。2.1 组件一需求上下文固化需求是整个链路的起点。你给 AI 的需求写得越像伪代码验收标准AI 的产出就越可预期。以给项目加一个 CSV 导出功能为例写法结果加个导出功能AI 自由发挥可能做前端、可能做后端、可能用你不想用的库在 /api/reports 新增 GET 接口接受 formatcsv 参数将当前筛选条件下的报告数据按模板导出列字段固定为 date, amount, category需处理 10 万行以下数据时不超时参考现有 auth 中间件鉴权AI 能精确定位改动范围产出符合预期的代码需求固化的目的不是限制 AI而是把模糊地带在开工前解决掉。你在需求里写得越具体后面需要返工的概率就越低。2.2 组件二提示词模板沉淀很多人认为提示词工程就是把话说清楚一点这没错但太浅了。在 Harness 的框架里提示词模板是可复用的、经过验证的、持续迭代的老物件。一个相对成熟的提示词模板至少包含这几段角色定位你是什么级别的工程师遵循什么编码规范任务背景仓库结构、技术栈、本次需求相关的模块路径执行约束不要动哪些文件、不能用哪些依赖、优先复用哪些已有工具函数输出要求必须补充测试、必须跑 lint、按什么格式汇报改动验收标准想要的结果和可量化的指标我习惯把模板拆成两块。一块是项目级模板每个项目一套写清楚技术栈和约定一块是任务级模板每次在项目级模板基础上追加本次需求的具体说明。两级模板在 Harness 中分别承担稳定的基准和可变的任务描述两个职责缺一不可。2.3 组件三人工检查清单AI 的盲区和人性的惰性这是整个 Harness 里最容易被忽略、也是最值钱的一环。AI 生成代码最常见的盲区有三个安全边界权限校验、输入校验、敏感信息泄露异常处理AI 倾向于写happy path代码对异常分支覆盖不足非功能性需求性能、可观测性、日志规范AI 很少主动考虑对于这些问题你不可能指望 AI 自觉所以要用人工检查清单来补位。我推荐的做法是在需求模板里预置一栏本次改动必须审查的点每次 AI 完成后你拿着这个清单逐项对照而不是泛泛地看代码。清单可以非常简单比如新增接口是否继承现有的鉴权装饰器是否处理了空数据和边界值是否补充了对应的单元测试日志是否包含足够的上下文别小看这几条。我在这套体系里发现有清单和没清单审查效率差三倍以上。没有清单的时候你会被 AI 输出的流畅感带着走有了清单你只做黑盒验收反而更快。2.4 组件四自动化验证闸门人工检查解决方向对错自动化验证解决代码能不能跑、质量过不过关。Harness 的第四个组件是在你的项目里预设一套自动化闸门AI 的改动必须通过闸门才能进入下一步。这些闸门可以包括静态检查ESLint / Ruff / golangci-lint单元测试Pytest / JUnit视项目而异构建验证能完整地打包成部署产物而不是只在编辑器里编译通过类型检查TypeScript / mypy值得注意一点这些闸门不应该由 AI 自己来开。在很多工具里AI 可以自动跑测试甚至修改测试来让它通过——这在调试阶段是好事在验收阶段就是隐患。闸门的运行命令、判定逻辑和记录结果应该由你或 CI来掌控并由你来认定是否通过。这不是对 AI 不信任而是职责分离的基本要求。2.5 组件五变更记录与回滚预案最后一个组件是让 Harness 这个系统本身能持续演进的东西。每次 AI 完成一次任务建议顺手记录三件事需求描述和所用提示词模板的版本AI 产出的核心改动摘要以及过程中发现的反复项失败点哪些地方 AI 第一次没做对它是如何被纠正的这些记录会沉淀成两个输出一个是你的提示词模板的迭代依据另一个是你的典型坑位清单——比如这个项目里 AI 经常漏掉 Redis 的 key 过期时间审查时必须重点盯。同时建议在需求接入 AI 之前就确认回滚方案。对于改动范围大的任务提前给 Git 打好标签或者在功能级别上确保可下线。AI 写代码再快也不该让你的发布流程为此承担额外风险。3. 实战演示用免费的 Codex CLI 从零跑通一个 Harness 流程理论基础说了一堆接下来用一个真实的例子把它串起来。我用的是 OpenAI 的 Codex CLI当前很多团队都在用的能自由配置的 AI 编程工具浏览器搜索 codex 就能找到入口安装方式在官方文档里写得很清楚这里不赘述而且以下流程用的不是复杂的团队级系统而是一个单人也能跑通的最小 Harness。3.1 项目目标与需求定义为了演示而不涉及任何具体的业务代码授权问题我拿一个本地环境就能完整的项目来说事。目标仓库结构my-report-service/ ├── main.py ├── config.py ├── requirements.txt └── README.md需求描述直接作为任务级提示词的主体在 main.py 中新增一个 FastAPI 接口GET /api/reports/export接口读取查询参数 start_date 与 end_date日期格式为 YYYY-MM-DD如果参数缺失或时间范围超过 90 天返回 400 错误和 JSON 提示模拟数据从 config.py 中读取一个简单的 Python 字典常量导出为 CSV 并作为响应返回下载文件的文件名建议为 reports_YYYYMMDD.csv必须使用 FastAPI 自带的 Response 类来实现下载头不能引入新的第三方依赖这个需求里包含了接口形态、参数规格、边界条件、依赖约束、输出格式五个层面的要求AI 没有太多自由发挥空间。让 AI 少自由发挥不是要扼杀它的能力而是把创造力留给真正需要的地方。3.2 项目级模板与任务级模板的拼接先用项目级模板交代背景你是这个 Python 服务的高级开发。项目结构main.py 是入口config.py 放配置项和模拟数据。代码风格遵循 PEP 8。 在每次任务中保持现有模块最小改动按需补充类型标注。新增代码后必须自己先检查一遍是否有明显错误。 执行前先说明你的计划执行后报告改动摘要。然后接任务级模板即上面的需求定义拼成完整的提示词。我不主张把提示词写得像八股文能自然衔接就好。关键是让 AI 在动手前先复述计划而不是直接丢代码——这个动作能提前暴露它对需求的理解偏差。3.3 Codex CLI 运行链路与人工关卡设计打开 Codex CLI 进入项目目录把上面拼接好的提示词一次性发给它。注意观察两点它有没有在动手前给出执行计划它是不是只改了描述中提到的文件有没有顺手动别的东西实测中Codex CLI 在大多数情况下会先描述方案再动手。如果它跳过了计划直接写代码我一般会停下来追加一条先把执行计划列出来等确认后再写代码让整个流程回到 Harness 规定的节奏上。AI 改完代码后进入验证阶段。我在本地跑三个命令# 检查语法与基础风格 python -m py_compile main.py config.py # 启动服务并测试正常链路 uvicorn main:app --port 8000 curl http://127.0.0.1:8000/api/reports/export?start_date2026-08-01end_date2026-08-31_0 # 测试异常链路 curl http://127.0.0.1:8000/api/reports/export?start_dateinvalidend_date2026-08-31_0第一行命令是最基础的 Python 编译校验确保没有语法错误。第二行验证正常链路返回 CSV。第三行验证异常参数能否返回 400。这种绿路红路双验证的思路很简单也容易被跳过。很多人只测试正常链路看到 CSV 出来了就结束但 AI 工程化的重点恰恰在于负向路径。在 Harness 里红路测试是卡口的一部分跟绿路同等重要。3.4 审查清单在执行中的实际运用AI 输出代码和测试结果后拿审查清单逐项过接口有没有按需求使用 FastAPI 的 Response 或 StreamingResponse还是用了其他方式start_date / end_date 的缺失、格式错误、范围超限是否都走统一的 400 响应CSV 的列头和数据内容是否是从 config.py 读出来的实测中Codex CLI 实现的接口基本符合需求但有一个细节它差点漏掉当 start_date 缺失时它返回的是 422FastAPI 默认校验错误而不是需求要求的 400。这个差异如果不拿清单去对很容易被忽略。修正方式也很简单在需求里加一句无论参数缺失还是格式错误都必须返回 400 和业务错误码AI 就能改对。这个案例很有代表性——AI 会默认遵从框架本身的规则而不是你心里的业务规则而 Harness 的检查清单恰恰补上了业务规则的定义与验证。通过上面这一节你可以看到把 Harness Engineering 落到一个真实项目里其实不需要平台、不需要什么高级基建只要一套可重复的流程以及你在关键节点的把关。流程跑得顺了AI 编程的效率优势才能真正变成工程效率。4. 团队落地 Harness Engineering 的三种模式个人跑通以后下一步通常就是把这一套推到团队里去。但不是所有团队都需要同一个重量的 Harness不同阶段有不同方案。4.1 模式一个人工作流适合个人开发者、自由职业者这个模式最简单就是按照第 2 节的内容把五个组件动手做出来并且坚持用三个迭代周期以上。关键点在你的主线仓库和实验仓库分离不要让 AI 直接修改你依赖的主仓库。自由职业者最容易犯的错误是在真实客户项目上急急忙忙用 AI 改代码改错了连回滚都手忙脚乱。建议用私人实验仓库反复跑需求到验收的循环流程稳定了再戴着 Harness 去碰客户项目。4.2 模式二小团队轻量模式适合 2-10 人团队小团队的第一个诉求通常是要让 AI 高效率地写代码同时不造成混乱最适合的方向是把 Harness 的组件固化到流程文档和仓库配置里。具体做法可以是在仓库目录下放一个 AGENTS.md 或类似文件写明项目技术栈、目录约定、禁止改动的模块、以及代码风格要求用普适的格式搞一个 issue template里面预置需求描述、验收标准、检查清单等字段把 CI 配置好AI 分支的改动必须通过 lint、typecheck、test 才能合并这个阶段的核心是规则写进仓库因为文件就是契约AI 每次动手前也会先读仓库内的规则。4.3 模式三团队级 Harness 平台适合中大型组织、规范要求高的团队当地规模到了数十人AI 的使用密度很高以后靠文档约束会显得不够。这时候可以在已有工程基础设施GitLab 或 GitHub之上做三层补充。流程设施层统一的需求模板、评审模板、AI 使用流程工具设施层统一的 Agent 配置公共的 prompt 模板库按业务域维护统一 Code Review Bot 配置度量设施层统计 AI 辅助产生的 PR 的缺陷率、返工率、合并耗时等度量这层很多团队没做但这恰恰是 Harness Engineering 里最有价值的部分——只有度量了你才知道这套缰绳到底是在提升效率还是拖慢节奏。我见过一个团队在推行时的主要争论是要不要让 AI 直接提交 PR。有人觉得这是效率最大化有人觉得不可控。我的看法是在 Harness 成熟之前让 AI 只负责生成改动和建议提交动作必须由人工完成。等运行一两个月、返工率稳定可控了再逐步开放更高级别的自主权。护城河不是限制 AI而是知道怎么一点一点放权。4.4 从个人到团队的常见过渡误区推 Harness 时最常出现的问题是把工具当流程。团队负责人下载了一个很酷的 Agent配好了一堆参数但需求不写清楚、检查清单形同虚设、测试跑不跑全看心情——那 Harness 就是一张虎皮实际没有任何作用。反过来说如果你的工具一般但需求、审查、验证三个环节都严格执行了流程的有效性是远超前者的。5. 我把 Harness 用在真实项目里之后踩过的几个坑从会用 AI 编程到有 Harness 地使用 AI 编程中间有一段必经的适应期。这里挑几个我身上发生过的典型问题你可以当成提前预警。5.1 坑一AI过度自信造成的假阳性该怎么防有次我让 Codex CLI 给一个模块补测试它跑完报告全部通过。我没复查直接合并了。后来才发现它把某个断言参数写错了压根没测到目标函数。从那以后我定了一条铁律测试类改动必须由人来看测试代码本身而不仅仅是看结果表格。AI 报绿的时候我们要意识到这个绿有多少可信度。可以试着让 AI 在测试文件里明确给出为什么这个测试能抓到目标 bug的解释解释不清楚就退回重写。5.2 坑二上下文太长之后AI 会选择性失忆有一次需求涉及多个文件的修改我把所有相关文件内容都贴进了提示词。结果 AI 前期还很听话改到一半突然开始用错误的旧变量名后面越改越乱。后来我在 Harness 里增加了一条进度回调规则如果一个任务的改动预计超过三个文件就让 AI 每完成一个阶段报告一次中间状态我来确认是否继续。这样上下文被拆散到多轮对话里AI 反而在每轮都表现得更稳。5.3 坑三提示词模板变成了噪音需要定期断电清理我的提示词模板一开始写得非常全面加了很多项目专属的约定。但用了几周后发现AI 每次通读模板都会产生大量无效考虑响应速度变慢、重点模糊。后来我把模板做了一次减法只保留会直接改变 AI 行为的内容。哪些内容会改变行为规则条目、约束清单、验收标准。哪些不会关于项目价值的大段背景描述。背景信息只保留在需求正文里模板里干干净净反而效果好很多。5.4 坑四拿代码通过率当 KPI有一个普遍倾向团队推进 AI 编程时喜欢统计AI 生成的代码有没有一次通过。这个指标其实没太大意义——因为你可以通过疯狂写冗余测试来刷高通过率或者通过让 AI 只做简单任务来保证指标好看。更值得度量的是单位交付时间的下降幅度和缺陷逃逸率的变化。换句话说看整个链路的产出质量而不是某个工序的一次成功率。6. 我个人的实际体会以及一套可以直接抄的起步建议AI 编程工程化这件事我现在的理解可以浓缩成一句话它不是为了限制 AI而是为了保护你使用 AI 的勇气。没有 Harness 的时候你每次让 AI 改代码都是一次赌博而有了 Harness变成了一个你可以放心托付的执行者——即使出问题也能快速定位、快速兜底。给刚开始走这条路的人一个务实的起步建议第一周不要追求完美模板先用第 2 节的最小五件套把一次需求从提报到验收完整地走下来第二周记录所有返工的根因并把高频坑位写进检查清单第三周以后逐步增加验证关卡把可自动化的部分交给检测工具我现在的 Harness 已经跑了几个月最大的收获不是代码写得快了多少而是让 AI 干活这件事本身变得很有底气。今天周五下午我让 Codex 改了一个跨 12 个文件的依赖升级中间它自己跑了两轮测试、提交了报告我在关键节点做了三次确认六点多就合入主干。放在一年前这是我周五忙到深夜才能完成的工作量。最后分享一个我一直在用的小习惯给自己准备一个Harness 复盘笔记每次 AI 的改动出了幺蛾子就记录失败点、提示词版本、修复方式。这几个月下来它已经成了我最重要的个人资产之一——比任何提示词模板都值钱。因为 AI 的工具会一直更新模型会越来越强但你对如何驾驭它这件事的理解才是真正随着经验增长的复利。这篇日志就是你的 Harness 从版本 0.1 走向 v1.0 的轨迹。