1. 为什么“会写提示词”不等于“会做 AI 编程工程化”很多人第一次接触 AI 编程都是从聊天框里敲一句“帮我写个函数”开始的。用久了就会发现一个尴尬的事实单次对话里模型表现惊艳一旦放进真实项目让它连续改十几个文件、跑测试、处理依赖冲突它就开始胡言乱语改着改着把不相干的模块也顺手重构了。这不是模型变笨了而是我们一直在用“对话”的方式做“工程”。Harness Engineering 要解决的就是这件事。这里的 harness 直译是“马具、挽具”在软件测试领域它指“测试夹具”——那套把被测对象固定住、给它喂输入、收集输出的脚手架。放到 AI 编程语境里harness 就是围绕大模型搭建的一整套约束、工具、上下文供给和验证机制让模型从“随口聊”变成“在轨道上干活”。你可以把它理解成给一匹力气很大但方向感很差的马套上缰绳和车架它的力气才能真正用来拉货。这套东西能做什么简单说三件事第一把项目规范、目录结构、编码约定固化成模型每次都能读到的上下文第二把模型的动作限制在可控范围内比如只能改指定文件、必须走测试第三把模型的输出接进真实的构建、测试、部署流程形成闭环。适合谁来参考如果你已经在用各类 AI 编程工具写代码但总觉得“它帮倒忙的时候比帮忙多”或者你是一个团队的技术负责人想让 AI 编程在团队里真正落地而不是沦为玩具那这套思路就是给你准备的。我踩过的最大一个坑就是早期迷信“提示词写得够好模型就能自己搞定一切”。实测下来提示词的作用被严重高估了真正决定成败的是上下文工程和验证回路。一个平庸的提示词配上一套好的 harness产出质量远高于一个精心雕琢的提示词配上裸奔的模型。这也是为什么 AGENTS.md、MCP 这些概念最近会被反复提起——它们本质上都是 harness 的组成部分。2. Harness Engineering 的整体设计与思路拆解2.1 核心思路把“一次性对话”改造成“可重复的流水线”传统用 AI 写代码的流程是人描述需求 → 模型输出代码 → 人复制粘贴 → 人手动调试。这个流程里人承担了所有的上下文搬运和验证工作模型只是个高级自动补全。Harness Engineering 的核心思路是把这条链路反过来让模型自己去读上下文、自己去调工具、自己去验证结果人只负责定义边界和验收标准。这个转变背后有个关键认知大模型的能力上限其实很高但它有两个致命短板——上下文窗口有限和没有真实世界的反馈。harness 的设计就是围绕这两个短板做文章。上下文有限那就用 AGENTS.md 这类约定文件把最重要的信息压缩后常驻没有反馈那就用 MCP 把编译器、测试框架、数据库这些真实工具接进来让模型能“看到”自己改动的后果。我个人的判断是未来 AI 编程的竞争力不在于你用哪个模型而在于你的 harness 搭得多好。模型会不断迭代但一套设计良好的工程化框架是可以跨模型复用的。这就像换发动机不影响底盘设计一样。2.2 方案选型为什么是 AGENTS.md MCP 这套组合市面上做 AI 编程工程化的方案不少有靠超长系统提示词的有靠微调专属模型的也有靠复杂工作流编排的。我最终倾向于AGENTS.md 做静态上下文 MCP 做动态工具接入这套组合理由有三。第一AGENTS.md 是纯文本、零依赖的。它就是一个放在项目根目录的 Markdown 文件里面写清楚项目是干什么的、目录怎么组织、代码风格是什么、哪些文件不能动、测试怎么跑。任何支持读取项目文件的 AI 工具都能直接吃进去不需要额外配置。相比把规范塞进系统提示词它的优势是可版本控制、可随项目演进、团队共享。第二MCPModel Context Protocol解决的是“模型够不着真实工具”的问题。MCP 本质上是一套标准协议让模型能以统一的方式调用外部能力——读文件、查数据库、跑命令、调 API。没有 MCP 的时候模型只能“想象”代码运行的结果有了 MCP它能真的去执行、真的拿到报错、真的根据报错再改。这个反馈闭环是质的差别。第三两者职责清晰、互不干扰。AGENTS.md 管“你应该知道什么”MCP 管“你能做什么”。这种分离让调试变得简单模型行为不对先看 AGENTS.md 是不是写漏了模型调不动工具先查 MCP 配置。如果全塞在一起出问题根本无从下手。2.3 要避免的坑别把 harness 做成“过度约束”新手搭 harness 最容易犯的错是约束过头。我见过有人在 AGENTS.md 里写了三千字规范结果模型每次读上下文就消耗大量 token真正干活的空间被挤没了。还有人给模型配了二十个 MCP 工具模型在“该用哪个工具”上反复纠结效率反而下降。合理的做法是分层约束核心红线比如禁止改动的目录、必须通过的测试写死在 AGENTS.md 里次要偏好比如命名风格用简短条目列出探索性内容交给模型自己判断。工具也是同理先接最常用的三五个跑顺了再逐步加。harness 的目标是让模型跑得更稳不是把它捆死。3. 核心细节解析与实操要点3.1 AGENTS.md 到底该写什么一份可抄的模板AGENTS.md 不是越长越好关键是信息密度。我总结下来一份好用的 AGENTS.md 应该覆盖五个板块每个板块控制在几句话到十几行。# AGENTS.md ## 项目概述 这是一个基于 Python 的数据处理服务负责从消息队列消费数据、 清洗后写入 PostgreSQL。核心入口是 src/main.py。 ## 目录结构 - src/ 核心业务代码 - tests/ 单元测试用 pytest - migrations/ 数据库迁移用 alembic - scripts/ 一次性运维脚本不要在这里写业务逻辑 ## 编码约定 - 所有函数必须有类型注解 - 日志统一用 src/utils/logger.py 里的 logger不要用 print - 数据库操作必须走 src/db/session.py 的 session 工厂 ## 禁止事项 - 不要修改 migrations/ 下已有的迁移文件 - 不要引入新的第三方依赖除非在 PR 描述里说明理由 - 不要改动 .env 和任何密钥相关文件 ## 验证方式 - 改完代码必须跑 pytest tests/ -x - 涉及数据库的改动先跑 alembic upgrade head这份模板的关键在于具体。“用 pytest”比“写测试”有用一百倍“不要改 migrations”比“谨慎修改”有用一百倍。模型不需要你告诉它“要写好代码”它需要的是可执行的指令。提示AGENTS.md 里每多一条模糊描述模型就多一次自由发挥的机会。凡是能用“做 X”或“不做 Y”表达的就不要用“注意”“尽量”“建议”这类词。3.2 MCP 是什么用生活化类比讲清楚MCP 这个词最近被提得很多但很多人第一次听到会懵。我用一个类比解释模型本身是一个很聪明但被关在房间里的人它只能靠你递给它的纸条提示词了解外面的世界。MCP 就是给这个房间装上了一排对讲机和机械臂——它能通过标准接口去问外面的人查数据库、去操作外面的东西跑命令、去拿外面的资料读文件。技术上MCP 定义了一套客户端-服务端的通信规范。模型所在的工具比如各类 AI 编程软件是客户端具体提供能力的一方是服务端。一个 MCP 服务端可以暴露若干“工具”tools和“资源”resources客户端把这些能力转成模型能理解的格式模型决定调用哪个、传什么参数客户端负责实际执行并把结果回传。这套设计的好处是解耦。你写一个 PostgreSQL 的 MCP 服务端所有支持 MCP 的 AI 工具都能用你换一个 AI 工具之前配好的 MCP 服务端不用重写。这就是为什么最近各种“XX 的 MCP 插件”层出不穷——大家都在往这个标准上靠。3.3 工具选型哪些 MCP 值得先接MCP 生态现在很热闹但没必要全都接。我的建议是按项目实际需要从高频刚需开始。下面这张表是我实测下来优先级最高的几类。工具类型典型能力适用场景优先级文件系统读写、搜索、列目录几乎所有项目必接命令执行跑 shell、构建、测试需要验证结果的项目必接数据库查询、schema 读取后端、数据类项目高版本控制查看 diff、提交历史团队协作项目高文档检索查官方文档、API 参考用新框架时中设计工具读设计稿、导出资源前端、UI 项目按需接工具的顺序很重要。我一般先接文件系统和命令执行把“读代码-改代码-跑测试”这个最小闭环跑通确认稳定后再加数据库和版本控制。一次性全接上出问题的时候你根本不知道是哪个环节的锅。注意命令执行类 MCP 权限很大务必在配置里限制可执行的命令白名单或者至少限制工作目录。让模型能随便跑任意命令等于把服务器钥匙交出去了。4. 实操过程与核心环节实现4.1 从零搭一个最小可用的 harness假设你有一个中等规模的 Python 项目想让它能被 AI 工具稳定地辅助开发。下面是我实际走过一遍的流程按顺序做就行。第一步写 AGENTS.md。不要一上来就写全先写项目概述、目录结构、验证方式这三块。跑几天发现模型老在某个地方犯错就把对应的约定补进去。AGENTS.md 是长出来的不是设计出来的。第二步配置文件系统 MCP。大多数 AI 编程工具内置了文件读写但显式配置一个文件系统 MCP 能让你控制访问范围。配置里指定项目根目录禁止访问上级目录和敏感路径。这一步的目的是划定模型的活动边界。第三步配置命令执行 MCP。这是最关键的一步。配置里要明确允许执行哪些命令比如 pytest、alembic、npm、工作目录是哪里、超时多久。我一般会准备一个allowed_commands.txt把允许的命令前缀列进去MCP 服务端启动时加载。第四步跑一个真实任务验证。别用“写个 hello world”这种玩具任务验证直接拿一个真实的小需求比如“给用户列表接口加一个按注册时间排序的参数”。观察模型有没有先读 AGENTS.md、有没有按约定改代码、改完有没有主动跑测试、测试失败有没有自己修。这四个问题就是 harness 是否生效的检验标准。第五步根据观察结果迭代。模型没读 AGENTS.md说明你的工具没把文件内容喂给它检查配置模型改了不该改的文件说明 AGENTS.md 的禁止事项不够明确模型不跑测试说明验证方式写得不够硬。每一轮迭代都让 harness 更贴合你的项目。4.2 参数计算上下文预算怎么分配harness 里有个容易被忽略的细节上下文预算。模型的上下文窗口是有限的AGENTS.md、工具定义、对话历史、代码内容都要占地方。如果 AGENTS.md 写得太长留给实际代码的空间就少了。我的经验值是AGENTS.md 控制在 500 到 1500 token 之间工具定义控制在 1000 token 以内剩下的留给对话和代码。一个 128K 上下文的模型实际能用来处理代码的可能只有 60K 到 80K因为工具调用和中间结果也会占用。怎么估算一个中文字大约 1.5 到 2 个 token一个英文单词大约 1.3 个 token。你写完 AGENTS.md 后用工具的 token 计数功能看一眼超过 2000 就该精简了。精简的原则是能删的例子删掉能合并的条目合并能移到外部文档的移到外部。AGENTS.md 只留模型每次都必须知道的东西。4.3 实操现场一次完整的 AI 辅助改动记录我拿一个真实任务走一遍让你看到 harness 是怎么起作用的。任务是“给订单查询接口加分页”。模型先读了 AGENTS.md知道项目用 FastAPI、数据库走 SQLAlchemy、测试用 pytest。然后它读了src/api/orders.py和src/db/models.py确认了现有的查询写法。接着它改了接口函数加了page和page_size参数用 SQLAlchemy 的offset和limit实现分页。改完后模型主动调用了命令执行 MCP跑pytest tests/test_orders.py -x。测试报错说返回结构里少了total字段。模型读了测试文件发现测试期望返回{items, total, page, page_size}于是回头改了接口加了一个 count 查询。再跑测试通过。整个过程我只做了一件事在开头说了一句“给订单查询接口加分页参考现有接口的风格”。剩下的读代码、改代码、跑测试、修 bug 全是模型自己完成的。这就是 harness 生效的样子——人定义目标模型负责执行和验证。对比一下没有 harness 的情况模型可能不知道项目用 SQLAlchemy写了个原生 SQL可能不知道测试文件在哪改完不验证可能改了接口但没改返回结构测试挂了也不知道。差别就在这里。5. 常见问题与排查技巧实录5.1 模型不读 AGENTS.md 怎么办这是最高频的问题。原因通常有三个一是工具根本没配置读取项目文件模型看不到 AGENTS.md二是 AGENTS.md 文件名或位置不对有些工具要求放在特定目录三是 AGENTS.md 内容太长被工具截断了。排查顺序先确认工具的文件读取功能是否开启再确认文件名和路径是否符合工具要求最后检查文件大小。如果都正常但模型还是不读可以在对话开头显式提醒一句“先读 AGENTS.md”跑几次后模型会形成习惯。5.2 MCP 工具调用失败怎么定位MCP 调用失败的表现是模型说“我要调用 XX 工具”但没结果或者直接报错。定位方法是从外到内逐层排查。现象可能原因排查方法模型不知道有这工具MCP 服务端没启动或没注册检查客户端工具列表调用报连接错误服务端进程挂了或端口不对手动启动服务端看日志调用成功但结果为空参数传错或权限不足看服务端收到的实际参数结果返回但模型不用返回格式模型看不懂检查返回结构是否符合协议我遇到最多的是服务端进程悄悄挂了。MCP 服务端一般是个独立进程如果它崩了客户端不一定能立刻发现。建议给关键 MCP 服务端加个健康检查或者用进程管理工具保活。5.3 模型改代码改出“连锁反应”怎么防模型改一个文件顺手把依赖它的其他文件也改了结果引入新 bug。这是上下文理解不足导致的。防范手段有两个一是在 AGENTS.md 里明确“改动范围”比如“只改 src/api/ 下的文件”二是用版本控制 MCP让模型每次改动前先看 diff改完再 review 一遍自己的改动。我个人的习惯是让模型每完成一个改动就git diff一次把 diff 内容作为下一步的输入。这样模型能清楚看到自己改了什么减少“改着改着跑偏”的概率。5.4 测试跑得太慢拖垮整个流程如果项目测试套件很大模型每改一次就跑全量测试效率会很低。解决办法是分级验证AGENTS.md 里规定小改动只跑相关测试文件大改动才跑全量。模型可以根据改动范围自己判断也可以由你在任务描述里指定。另一个技巧是给测试加缓存。很多测试框架支持只跑上次失败的用例或者按文件变更范围选择测试。把这些命令写进 AGENTS.md 的验证方式里模型就会照着用。5.5 独家避坑别让 harness 变成“黑盒”搭 harness 的过程中最危险的状态是你不知道模型为什么这么做。它调了工具、改了代码、跑了测试但你完全看不懂它的决策逻辑。这时候一旦出问题你连从哪查起都不知道。我的做法是强制模型输出决策理由。在 AGENTS.md 里加一条“每次改动前用一句话说明你为什么这么改。”这条规则看起来简单但效果显著——模型被迫把隐性的推理显性化你一眼就能看出它是不是理解错了需求。如果它的理由离谱你可以在它动手前就打断省下大量返工时间。6. 把 harness 用起来之后我的真实体会搭完这套东西跑了几个月最大的感受是AI 编程的门槛从“会写提示词”变成了“会设计约束”。以前我花大量时间琢磨怎么把需求描述得更清楚现在我花时间琢磨怎么把项目规范写得更可执行。前者是玄学后者是工程。另一个体会是harness 的价值会随着项目复杂度上升而放大。小项目里模型裸奔也能跑得不错但项目一旦超过几十个文件、涉及多个模块协作没有 harness 的模型基本就是灾难。这也是为什么团队越大、项目越老越需要这套东西。最后分享一个我一直在用的小技巧把 harness 本身也当成一个项目来维护。AGENTS.md 用 git 管理每次模型犯错就提一个 issue修完就提交。MCP 配置写成代码能版本控制、能 review。这样你的 harness 会随着项目一起成长而不是搭完就烂在那里。这套东西没有终点只有持续迭代。