Agent = Model + Harness：这个公式，让我重新理解了 AI 工程

最近AI圈造新词的速度快得离谱，今天这篇聊聊一个刚刚火起来的概念：Harness Engineering。其实早就想写了，一直拖到现在——但赶早不如赶巧，2026年这个时间点上聊这个话题，正是时候。

朋友的 AI 项目，差点出了大事

上个月，一个做技术负责人的朋友找我吃饭，整个人状态不对。

他们公司年初引入了AI Coding Agent，跑了两个月效果不错，老板也满意。结果有一天安全团队找上门来——扫描发现，最近一批AI生成的代码里，有接口没做权限校验、有地方在日志里打印了用户ID、还有一处直接拼接了SQL。三个问题，没一个运行报错，测试也全过了，就这么悄无声息地进了代码库。

他第一反应是去改Prompt，加了一大段安全要求。跑了一周，好转了一些。再过一周，老问题又冒出来了。再改Prompt……就这么反复折腾，他说最近两个月光在调Prompt，感觉跟AI玩打地鼠。

当时问了他一句：你们有没有在CI里接安全检查？有没有一个规则文件让Agent每次启动都能读到？

他愣了一下：没有，我以为告诉它就行了。

这就是现在很多团队的缩影。Agent能跑，但跑不稳。单次表现不错，整体不可靠。问题不在模型本身，而在模型外面那一层。而那一层，现在有个专有名词了——Harness。

三代概念的演变

进入正题之前，先花一分钟搞清楚Harness Engineering从哪里来。AI工程方法论走到今天，大致经历了三个阶段。

三代工程实践，其实都在解决同一个问题：如何让AI的输出稳定符合预期。但要真正理解为什么需要Harness Engineering，得先弄清楚前两代做了什么、又在哪里碰了壁。

第一代：Prompt Engineering——从「把话说清楚」开始

如果你2023年用过ChatGPT，应该经历过这个过程：写一句话，AI给了一个不太对的答案。重新措辞，加几句说明，再试——好了一些，但还差点意思。继续改，继续试。这个循环，就是最朴素的Prompt Engineering。

严肃地说：Prompt Engineering是通过精心设计指令，引导AI给出更符合预期输出的工程实践。作用范围是单次交互，核心逻辑是——你能给AI多少有效信息，它就能给你多少有效输出。

一个真正管用的Prompt，通常由六个要素组成：任务描述、角色设定、上下文信息、输出格式、约束条件、示例参考。把这些要素搭配好，输出质量能明显提升。

几个被反复验证的技巧：

不要直接问"这个漏洞怎么修"，而是说"先分析所有可能的原因，再逐步排查，最后给出修复方案"。显式的推理步骤能有效减少AI跳步犯错。

"我想要结构清晰的注释风格"——这句话对每个人意味着不同的东西。直接给两个示例，AI读取描述的过程可以快十倍。

"你是一个有十年经验的FastAPI工程师，熟悉异步编程"——这不是客套，它引导AI调用特定领域的知识储备，而不是给出万金油式的通用回答。

"注意安全"太模糊。"禁止在日志里打印用户ID，所有数据库查询必须用参数化查询"才是具体的。约束越精确，AI的遵守率越高。

这些技巧在2023年确实很有效，也催生了"Prompt工程师"这个短暂的职业泡沫。但问题很快就来了。

局限一：跨会话遗忘。你在第一个会话里调好了Prompt，AI表现不错。开了新会话，所有约定归零。要保持一致，你得每次手动复制粘贴，这显然不现实。

局限二：软约束，靠"理解"，不可靠。Prompt只是"说了一遍"。AI理解了，大多数时候会遵守，但不会被强制执行。时间一长，指令在长上下文里被稀释，AI开始犯回之前的错误。改Prompt，暂时好了，另一个问题又冒出来——这就是"打地鼠"的根源。

局限三：只管单次交互，撑不住长任务。Prompt Engineering的假设是"一次对话解决一个问题"。但现实中，AI Coding Agent要跑几十步、修改十几个文件。一个Prompt撑不住这么长的任务链。

第二代：Context Engineering——从「给够信息」到「管好信息」

2024年，随着模型的上下文窗口从4k、8k扩展到128k甚至更长，工程师们开始换一个思路：既然AI能看到的信息变多了，与其纠结"怎么说"，不如认真想"让AI看到什么"。

Context Engineering的核心：精心管理AI在生成回答时能访问的全部信息。这里的"上下文"不只是你打的那几行字。AI在回答时能"看到"的全部内容，是一个复杂的组合：系统指令、用户输入、检索到的文档片段、对话历史、工具调用结果、外部API返回数据。

这个阶段的最佳实践包括：

把产品文档、代码库、历史案例存进向量数据库，每次AI需要时检索最相关的片段注入上下文。既避免超出token限制，也能让AI基于实际资料作答，而不是凭"感觉"编造。

一个典型的使用场景：让AI帮忙修一个复杂模块，RAG自动把相关的接口文档、历史PR的改动说明、相似漏洞的修复记录一并注入——AI能做到的事就完全不同了。

不要把整段历史都保留。当对话超过一定长度，把早期内容压缩成摘要，只保留最近几轮的完整记录。既维持了连续性，又不让token费用失控。

系统级规范放最前面，当前任务描述放中间，具体参考资料放后面。AI读上下文的注意力不是均匀分布的——开头和结尾被记住的概率远高于中间（"Lost in the Middle"现象有专门的研究）。

Context Engineering把AI的有效工作范围从"单次对话"扩展到了"跨多轮的复杂任务"，这是真正的进步。但有一个问题，它解决不了：AI看到了规则，不等于AI会执行规则。

朋友的团队把规范写进了系统Prompt，把RAG接好了，上下文管理也做得不错。但那三个安全漏洞，是在上下文一切正常的情况下出现的——AI看到了"不要拼接SQL"的规范，但它就是生成了拼接SQL的代码。

Context Engineering的本质是信息层面的工程——给AI更好的信息。但没有在行为层面加装护栏。随着任务越来越长，早期注入的规范还会被后来涌入的大量上下文"稀释"，AI在任务后期对早期约束的遵守程度会明显下降。这不是靠精心设计Prompt能解决的，而是上下文机制的结构性问题。

这就是为什么需要Harness Engineering——不是再给AI更多信息，而是在行为层面加上结构性的硬约束。

Harness Engineering 到底是什么

2026年2月，OpenAI工程师Ryan Lopopolo发了一篇文章，描述他们的内部Agent基础设施。几天后，Terraform和Ghostty的作者Mitchell Hashimoto把这篇文章的核心提炼成了一个公式：Agent = Model + Harness。

Model是AI模型本身，负责推理和生成。Harness是包裹在模型外面的一切——规则文件、约束层、反馈回路、权限管控、Safety护栏……Harness Engineering就是构建这个外层系统的工程实践。

Harness的作用不是让AI更聪明，而是让它更可靠。不管AI有没有"理解"规范，结构上的约束都会生效。这就是朋友反复调Prompt却始终不稳定的根本原因——他在靠AI的"记忆"，而不是靠系统的结构。

Harness 的三个关键组件

Harness层里有很多东西，但核心可以归为三类（以Coding Agent为例）：

在AI生成之前，缩小它的解空间。规则文件就是典型——让AI一开始就不进入错误区域，而不是生成完再来纠错。

AI的输出不符合要求时，把错误信息结构化地反馈给它，让它能自我修正。把linter报错直接发给AI让它改，比你用自然语言描述"哪里有问题"要精准得多。

最终的输出要过一道硬性检查，不管AI怎么说。CI里的安全扫描就是典型的质量门控——不通过就是不通过，不依赖AI的"理解"。

这三类核心组件不只适用于Coding Agent。无论是客服机器人、内容创作、研究分析，还是金融合规Agent，都可以从同样三个维度构建Harness——约束前馈限定行为边界，反馈回路驱动自我修正，质量门控强制终态验证。具体工具不同，结构相同。

一个让你秒懂的类比

招聘的时候，写一份JD告诉候选人岗位职责——这是Prompt Engineering，你在精心设计"提问"。

入职之后，给新员工提供背景资料、项目文档、现有代码库——这是Context Engineering，你在给AI补充信息。

但是，一个人能不能在公司里稳定输出，真正依赖的是公司的制度：代码review流程、安全扫描、部署审批、团队规范……这套制度让他即使某天状态不好，也不会出大问题。这是Harness Engineering。

Mitchell Hashimoto的核心理念是：Don't trust the model. Trust the harness. 朋友的AI写了不安全的代码，他去改Prompt，本质上是靠AI的"记忆"。而接入安全扫描到CI，是靠系统的结构——这才是Harness Engineering的思路。

为什么偏偏在 2026 年火起来

这个概念其实不算新鲜，工程师一直在做类似的事情，只是以前没有统一的名字。2026年突然爆发，是因为几件事撞在了一起：

模型能力到了临界点。GPT-4o、Claude、Gemini都已经能真正跑长任务的Coding Agent了，不是玩具，是生产工具。Agent真的在大规模跑，harness的问题才真正浮出水面。

大量团队踩坑之后开始反思。统计数字很扎心：88%的企业AI Agent项目上不了生产，65%的失败原因不是模型不行，是harness层的问题——上下文管理混乱、没有约束机制、没有反馈回路。

有人给这件事起了名字。Mitchell Hashimoto那个公式一出来，大家发现这正是自己一直想说但说不清楚的东西，于是迅速传播开了。

普通开发者能立刻上手的三件套

概念讲完了，接下来是实操。不需要大厂背景，个人开发者或小团队今天就能上手——三件事，做完立刻有效。

第一件：写一个 AGENTS.md

原理：AI工具（Claude Code、Cursor、Copilot）每次运行，会自动读项目根目录的AGENTS.md或CLAUDE.md。把规范写进去，它每次都遵守——不需要你在每个Prompt里重复说。这就是约束前馈。

第一步，创建文件：在项目根目录执行touch AGENTS.md（Windows用户直接在编辑器里新建同名文件）。

第二步，填入内容，把下面的模板复制进去，改成自己的技术栈：

# AGENTS.md ## 代码规范 - Python 文件遵循 PEP8，格式化用 black - 函数命名 snake_case，类命名 PascalCase - 所有公共函数必须有类型注解 ## 安全红线（必须遵守，不得违反） - 禁止在日志里打印用户 ID、手机号、密码等敏感信息 - 数据库查询必须用参数化查询，禁止字符串拼接 SQL - 所有 API 接口必须有权限校验 ## 架构约束 - 数据库操作只能写在 repository 层 - 不引入新的第三方依赖，除非在 PR 里说明原因 ## 不确定时的处理方式 - 涉及安全实现：先列方案让我确认，不要直接写 - 需要改动超过 3 个文件：先制定计划，确认后再执行 ## 技术栈 - 语言：Python 3.11 / FastAPI / PostgreSQL

效果对比：没有AGENTS.md时，你说加权限，AI加了但下次又忘。有了AGENTS.md之后，AI每次都直接写带权限校验的版本——因为每次启动都读到了规范，不靠记忆。

第二件：Linter 接进 CI，做成硬门控

原理：Prompt是软约束，CI是硬约束。代码不通过检查，合不了主干，这是结构上的限制，和AI有没有"记住"规范无关。

CI拦截本身是质量门控——输出端的硬检查，与AI是否理解规范无关；而把报错结构化地传回给AI驱动修正，是反馈回路。两个机制时序上相连，逻辑角色不同。

具体操作（Python项目，5分钟完成）：

第一步，安装工具：pip install ruff bandit pre-commit

第二步，在项目根目录新建.pre-commit-config.yaml：

repos: - repo: https://github.com/astral-sh/ruff-pre-commit rev: v0.4.0 hooks: - id: ruff - id: ruff-format - repo: https://github.com/PyCQA/bandit rev: 1.7.8 hooks: - id: bandit args: ["-r", ".", "-ll"]

第三步，激活：pre-commit install。之后每次git commit，检查自动运行。AI写的代码有安全问题，commit直接被拦住。

关键一步：把报错反馈给AI。直接把报错复制给AI——"你刚才写的代码，pre-commit检查报了这个：bandit B608: Possible SQL injection via string-based query，在user_repository.py第42行，请修复。"AI会读取错误信息、定位问题、改成参数化查询。这比说"那个SQL有安全问题"精准十倍。

如果你用的是Claude Code，有个补充说明。Claude Code内置了Hooks机制：在~/.claude/settings.json里配置后，每次AI编辑文件会自动触发ruff、mypy等检查，报错直接反馈给AI修正。这是会话内的轻量级反馈回路，不用额外安装pre-commit。

但它替代不了CI质量门控，两者作用层面不同。Claude Code Hooks作用范围是当前会话内，可关闭或忽略，适合个人项目快速迭代。CI是所有人、所有提交，不通过则无法合并，适合多人协作和生产部署。实用建议：个人项目先把Claude Code Hooks配好，作为日常反馈回路；一旦涉及多人协作或代码进生产，CI是必须做的硬门控。两者不互斥，可以同时用。

第三件：复杂任务强制走 Plan → Review → Execute

原理：涉及多个文件、有架构影响的任务，先让AI出方案，你确认了再执行。把人工判断放在执行之前，而不是收拾残局的时候。本质上是人工审批门的体现——在高风险节点把约束前置，让问题在计划阶段暴露，而不是执行完再返工。

一个真实的对话示范：

不推荐的方式——你说"帮我把用户模块的同步改成异步"，AI改了8个文件，你要一个个review，发现问题又要重来。

推荐的方式——你说"我想把用户模块的同步调用改成异步。先不要改代码，告诉我需要改哪些文件、每个文件大概改什么、有什么需要注意的。"AI会告诉你需要修改4个文件，并列出每个文件的变化和潜在风险点。你可以根据这个计划决定执行方案。

这个模式表面上多了一步，实际上省时间：在计划阶段发现问题，比执行完再发现便宜得多。

最佳实践

理解了三件套，再给几个从实际踩坑中总结出来的原则：

AGENTS.md是持久化的，Prompt是一次性的。只要更新了AGENTS.md，Agent下次启动就会遵守新规范——不需要每次都重新说。

这是Mitchell Hashimoto的原话。不要只想"这次怎么修"，要思考"下次怎么防"。能接进CI的就接进CI，能写进规则文件的就写进规则文件，而不是靠Prompt里多加一句话。

越靠工具强制执行的越可靠，越靠AI"理解"的越容易失效。能用工具强制执行的部分，就不要依赖AI的自觉。

不是每一步都需要你确认，那样效率太低。审批门适合放在不可逆的操作前、影响多个文件的重构前、不确定性高的技术决策前。其他的让Agent自己跑，不要变成AI的手动执行器。

AGENTS.md要随着项目演进定期更新，CI检查也要随着规范变化调整。这不是一次性的工作，是需要持续维护的基础设施——就像写完CI配置之后不会永远不管它一样。

回到开头那个朋友

后来帮他做了两件事：在AGENTS.md里加了专门的安全规范章节，然后把bandit接入了他们的CI，安全等级MEDIUM以上的问题直接卡住合并。

一周后他发消息，说安全团队那边没有新的问题了，他自己也不用再花时间盯着AI生成的代码逐行检查安全问题了。

他说了一句话挺准的：以前我在跟AI打地鼠，现在我在建护栏。

这大概就是Prompt Engineering和Harness Engineering最本质的区别。

模型会越来越强，但能让Agent在生产环境里稳定跑起来的，永远是那一层外壳——Harness。

如果你现在正在用AI Coding Agent，不妨先从写一个AGENTS.md开始——10分钟，立刻有效。