Harness engineering 是什么：先看两组让人不太舒服的数据
你打开 Claude Code 让它改一个 bug，它在三个文件里来回兜圈子，最后改出来的 patch 把测试搞挂了。同事用同一个模型、同一个版本，给它配了一份 AGENTS.md、一个 typecheck hook、一组阶段权限，同样的活儿一次过。模型没变，结局完全不一样。这件事 2026 年的数据可以直接量出来。JavaGuide 援引的一项实验里，同一个模型只换掉文件编辑接口的调用方式，编码基准分数就从 6.7% 跳到 68.3%。Anthropic 内部对照里更夸张：一个单 agent、最少工具的 Solo Harness 跑 20 分钟、烧 9 美元，吐出来的是一个跑不起来的半成品；换成三 agent、完整工具链的 Full Harness 跑 6 小时、烧 200 美元，拿到的是一个能直接用的完整应用。同一个模型，外面那套系统不一样，产物从废品变成可用品。
这就是 harness engineering 在治的事，也是这篇文章的核心答案：harness engineering 就是在模型之外，给 agent 搭一整套可读、可控、可验证、可恢复的运行系统；它的一句话公式是 Agent = Model + Harness。这条公式由 Terraform 和 Ghostty 的作者 Mitchell Hashimoto 提炼，被 Martin Fowler 网站和 LangChain 沿用进英文工程圈，被 JavaGuide、腾讯云、cnblogs 一类中文社区沿用进中文圈，意思都一样：裸模型本身不是 agent，给它套上状态、工具调用、反馈回路和能强制执行的约束，它才变成 agent。Harness 在这里是"马具"的引申义，指那一整套套在模型外面、决定它怎么跑、跑偏了怎么纠的运行壳。
为什么"模型外的那一层"突然成了一个被命名的工程学科，而不是继续被叫"agent 框架代码"，是因为 2026 年这个行业终于形成了一条共识：模型再升级一档，也救不了一个 harness 拉胯的 agent。反过来，一个体面的模型配一套像样的 harness，能把绝大多数 agent 失败模式压下去。
如果你想把 harness 和 prompt engineering、context engineering、spec-driven development 这几个相邻概念的边界一刀切清楚，去看harness engineering 与 context engineering 的边界辨析。如果你想立刻动手在 Claude Code 上搭一个属于自己的个人 harness，了解 AGENTS.md 怎么写、hooks 怎么挂、permissions 怎么分阶段，去看Claude Code 上的 harness 实操教程。如果你的目标是把 harness 推到长任务和生产场景，处理 6 小时不崩、跨上下文窗口续接、三主体协作这类话题，去看长任务 agent 的进阶 harness 设计。
模型是 CPU，harness 是操作系统
Philipp Schmid 给过一个让工程师秒懂的类比：模型是原始处理能力，上下文窗口是有限的工作记忆，harness 是操作系统，负责管理上下文、初始化序列、标准工具驱动；agent 则是跑在这套操作系统上的应用。中文社区的 JavaGuide 把这个类比说得更狠：CPU 再强，操作系统天天崩，体验也不会好。这就是为什么"模型再升级也救不了 agent 拉胯"会成为 2026 年的共识。你换的是 CPU，崩的是 OS。
这个类比顺手解释了另一件让人疑惑的事：为什么模型已经是商品，harness 反而成了壁垒。Atlan 把 Agent = Model + Harness 拆成三句话：模型本身不是 agent；GPT-4o、Claude、Gemini 在 harness 层可以互换，是商品化的推理引擎；harness 才是护城河，它编码的是你的业务规则、数据上下文、安全约束和验证逻辑，换模型时这些东西不会自动跟过去。换句话说，模型是别人卖给你的发动机，harness 是你自己造的整辆车。
把 harness 和 framework 放在一起也常被搞混。Cobus Greyling 的区分干脆：framework 告诉开发者怎么搭应用，harness 告诉 agent 怎么安全运行。用 framework，编排逻辑是开发者自己写的；用 harness，计划是模型自己出的，harness 的活儿是不让它跑偏。这条边界对工程师选型很关键，你以为在选 framework，其实你需要的是 harness。
光看定义还是分不清自己手上写的到底是哪一边，落到代码层就直观了。同样让 agent 改一个 bug，纯 framework 方案（比如 LangChain 的 AgentExecutor）大致是这样的：你写一个 agent loop，注册 read_file、write_file、run_tests 几个工具，把用户提示喂进去，模型决定调哪个工具、什么时候停。代码长这样（伪代码）：
# Framework 风格：开发者写编排逻辑
agent = AgentExecutor(
llm=llm,
tools=[read_file, write_file, run_tests],
prompt="你是一个修 bug 的 agent，看到 bug 就改"
)
agent.invoke({"input": "修一下 login.tsx 的登录失效问题"})
# 模型自己决定：先读、再改、再跑测试；跑挂了怎么办它自己想
跑起来的样子：模型可能一上来就直接改代码、跑测试、挂了再改，三个文件来回兜圈子。可能在第 20 步开始幻觉出不存在的 API。测试挂了它还能继续返回"任务完成"，因为没人拦它。
加上 harness 的方案长这样，同样的工具集，外面套一层状态机加权限白名单加 sensor 回路：
# Harness 风格：开发者写约束，模型出计划
PHASE_PERMISSIONS = {
"RESEARCH": ["read_file", "search_code"],
"PLAN": ["read_file", "create_plan"],
"EXECUTE": ["read_file", "write_file"],
"VERIFY": ["run_tests", "run_lint", "run_typecheck"],
}
harness = Harness(
llm=llm,
tools=[read_file, write_file, run_tests, ...],
phase_permissions=PHASE_PERMISSIONS,
agents_md="AGENTS.md", # 启动注入的项目约定
hooks=[on_file_change_typecheck], # 改完文件强制 typecheck
sub_agent_for=["security_review"], # 安全检查走独立上下文
)
harness.run("修一下 login.tsx 的登录失效问题")
跑起来的样子：模型在 RESEARCH 阶段只能读不能写，它想直接改代码会被拒；进 EXECUTE 改完 login.tsx，hook 自动触发 typecheck，挂了把错误塞回循环让 agent 自己改；跑通了进 VERIFY 跑测试，测试也通过才算结束。模型出的计划没变，但每一步都被 harness 卡在轨道里。
两段代码的差别一句话：framework 那段，编排是开发者写死的"先 A 再 B"；harness 那段，编排是模型自己决定的，开发者写的是"不允许 X""做完 Y 必须接着 Z"这种约束。这就是 Greyling 那句"framework 告诉开发者怎么搭应用，harness 告诉 agent 怎么安全运行"在代码层的样子。想把 harness 和 prompt、context、spec-driven 这几个相邻概念彻底拉清楚，参考harness engineering vs context engineering 的边界辨析那篇做对照。
如果还需要更直观的证据，看一眼现在排在前面的 coding agent。Addy Osmani 观察到一个反直觉现象：Claude Code、Cursor、Codex、Aider、Cline 这几款顶级 coding agent 并排放，你会发现它们彼此之间比它们底层的模型彼此之间更像。底层模型差异很大，但 harness 模式在收敛，这不是巧合，是整个行业在慢慢摸清那些能把生成模型变成真正能交付东西的承重脚手架。这就是为什么 Agent = Model + Harness 不是一句口号，而是 2026 年这个工程学科真正立得住的那条线。
命名时间线：谁先谁后，词到底是谁造的
中文社区一个常见误会是把 harness engineering 算到 Karpathy 头上。不对。Karpathy 推的是 context engineering，这是 2025 年的故事；harness engineering 是另一拨人在 2026 年初接力做出来的命名。Epsilla 把这条主线整理成"三代论"，Prompt Engineering（2022，2024）到 Context Engineering（2025）到 Harness Engineering（2026），关注点从指令本身搬到了如何架构整个 agent 的工作流、约束、反馈回路、工具链和生命周期。
把 2026 年初这几周的关键节点按时间排开：
- 导火索：Ryan Lopopolo 的内部基础设施文章。Atlan 的考据指出，harness engineering 作为被命名的学科出现在 2026 年初，触发事件是 OpenAI 工程师 Ryan Lopopolo 发表的一篇讲内部 agent 基础设施怎么搭的文章。Lopopolo 后来用一句话把整件事压成口号，"Agents aren't hard; the Harness is hard"（智能体不难，难的是 harness）。
- 公式提炼者：Mitchell Hashimoto。Lopopolo 文章出来几天内，Terraform 和 Ghostty 的作者 Mitchell Hashimoto 把核心洞见压成了一条公式：Agent = Model + Harness。Hashimoto 还顺手给出了一个被反复引用的工作定义，每当你发现 agent 犯了错，就花时间设计一个解决方案，让它再也不会犯同样的错。如果想把 prompt、context、spec-driven、harness 这几个 2025，2026 年集中出现的概念边界一次理清，harness engineering vs context engineering 那篇做了系统对照。
- 造词人：HumanLayer 的 Viv Trivedy。"harness engineering"这个词本身，HumanLayer 在博客里写得很明确，是 Viv Trivedy 创造的，用来描述"利用配置点定制和提升 coding agent 输出质量与可靠性"的实践。公式归 Hashimoto，词归 Trivedy，两件事别再混。
- 词汇标准化：Birgitta Böckeler 在 Martin Fowler 网站上的扩展。Thoughtworks 工程师 Birgitta Böckeler 写的文章把组件分类做了进一步扩展，引入 guides 和 sensors 这两个分类，今天从业者讨论 harness 组件基本都按这套词汇说话。
- 架构层级定位：Cobus Greyling 的"第四种模式"。Greyling 把 harness 称为 2026 年浮现的第四种 agent 架构模式，位置在 SDK、framework、脚手架这三种方法之上一层；OpenAI 和 Anthropic 都开始正式用这个术语，arXiv 上也有论文在做形式化。
为什么是 2026 年走红，而不是更早或更晚？Atlan 引的一组现场观察可以解释：2026 年 4 月的 AI Engineer World's Fair 上，三位互不相关的演讲者不约而同把 agent harness 和 context engineering 列为下一阶段的第一优先级。背后的判断是同一句话，经过两年模型能力的猛涨却没换来生产可靠性，行业的注意力就这么挪过来了。
只看一句会议观察不够硬，把这几周里同时发生的工程实践拐点摆在一起看，行业拐点的信号就更明显。OpenAI Codex 团队披露：用 5 个月在一个空仓库里、由 3 名工程师（后扩到 7 名）驱动 Codex 生成了约 100 万行代码，期间合并了约 1,500 个 Pull Request，平均每位工程师每天处理 3.5 个 PR，整个过程中人类从未直接贡献过任何一行代码。Stripe 的 Minions 系统每周有超过 1300 个完全由 Minions 生产、没有人类手写代码的 PR 被合并，开发者只需发一条 Slack 消息，agent 从写代码、跑 CI 到提 PR 全部完成，人只在最后审查。Nicholas Carlini 用大约两周时间跑了 16 个并行 Claude Opus 实例、约 2,000 个 Claude Code 会话，做出了一个 GCC torture test 通过率 99% 的 C 编译器，约 10 万行 Rust 代码，可以编译 PostgreSQL、Redis、FFmpeg、CPython、Linux 6.9 内核等 150+ 项目，API 成本约 2 万美元。这三个项目共同的特征：模型还是同一批 Claude / GPT，跑出 5，6 位数代码量和 3，4 位数 PR 量的不是模型升级，而是外面那套 harness 终于撑得起几小时到几周的长任务。这就是 2026 年初行业突然给"模型外的那一层"起名字的硬拐点。
想看这套思路怎么落到 Claude Code 上动手搭一个最小可用 harness，参见 harness engineering for Claude Code；想把它推到几小时甚至几周的长任务和生产场景，参见 harness engineering for long running。
Harness 治的是 model 治不了的病
Model 再升一级也救不了 agent 拉胯，这话听起来像情绪宣泄，但拆到症状层就成了可证伪的判断。把行业里反复出现的失败归一下类，会发现四个互不重叠的故障带：跨会话失忆、上下文中毒（context rot）、自评偏差、配置错位。每一个都在模型权重之外，每一个都得靠 harness 这层去接。
跨会话失忆是最朴素的那个。Anthropic 工程团队对长任务 agent 给过一个很直白的类比：想象一个软件项目由轮班工程师开发，每个新工程师上工时都不记得上一班发生了什么，这就是 agent 在离散会话间的状态。每个新会话从零开始，权重里没有任何"上次到哪了"的痕迹。模型再聪明也没用，因为它根本看不见昨天写的代码为什么长那样。
**上下文中毒（context rot）**比失忆更阴。LangChain 把它定义成"模型在上下文窗口被填满的过程中，会越来越不擅长推理和完成任务"。Dex Horthy 在 168K token 的窗口上观测到一个具体阈值：用到 40% 左右，输出质量就开始明显下滑。他把 0，40% 区间叫 Smart Zone，40% 以上叫 Dumb Zone，特征是幻觉变多、兜圈子、格式混乱、代码变差。OpenAI 工程团队从另一个方向印证了这件事：上下文是稀缺资源，一个塞满规章的指令文件会把任务、代码、相关文档全挤出去，agent 不是错过关键约束，就是开始针对错误的约束做优化。这一层的对治手段（compaction、tool call offloading、skills 渐进式披露、context resets）属于运行时管线设计，模型本身搞不定；想把这一类技巧推到生产长任务场景，看harness engineering for long running那篇。
自评偏差最容易被忽略。腾讯云转述 Anthropic 团队的观察很扎人：让同一个 Claude 实例先写代码再审查代码，它几乎总会说"代码质量良好"。和这件事配套的是上下文窗口侵蚀，对话拖到第 50 轮时做出的架构决策，可能和第 5 轮的决策正面冲突，但模型自己看不出来。这两个失败模式的共同点是：单实例自洽永远成立，得靠外部第二只眼睛（另一个 agent、一组 eval、一条 lint 规则）才能戳破。
配置错位是症状最反直觉的那类。HumanLayer 在跑过几十个项目、上百次 agent 会话之后得出的核心判断只有一句："这不是模型问题，是配置问题。"他们给过一个最锋利的对照实验：Claude Opus 4.6 在 Claude Code 这个 harness 里，Terminal Bench 2.0 排名第 33；把同一个模型放进一个未在 post-training 阶段见过的 harness，名次升到第 5（上下浮动约 4 名）。模型权重一行没动。LangChain 自己做过类似事情：在 Terminal Bench 2.0 上，他们只优化运行环境（文档组织、验证回路、追踪系统），就把分数从 52.8% 推到 66.5%，全球排名从第 30 升到第 5。开篇那组 6.7% 到 68.3% 的编码基准跳变和 Solo Harness $9 半成品对照 Full Harness $200 完整应用的实验，落点也都在这一类。
| 症状归属 | 数据点 | 来源 | 采集时间 |
|---|---|---|---|
| 整体 agent 项目失败规模 | 88% 的 AI agent 项目从未进入生产环境（the 88% gap） | Atlan，《What Is Harness Engineering AI?》 | 截至 2026 年 |
| 整体 agent 项目失败规模 | 95% 的企业 AI 试点交付零可衡量 ROI，根因被识别为上下文缺口而非模型能力 | MIT 2025 年数据，由 Atlan 转述 | 2025 年 |
| 整体 agent 项目失败规模 | 27% 的 agent 项目失败可追溯到数据质量问题（仅次于 scope creep） | DigitalApplied 2026 数据，由 Atlan 转述 | 2026 年 |
| 整体 agent 项目失败规模 | 预测到 2027 年底，超过 40% 的 agentic AI 项目将因成本失控、商业价值不清晰或风险控制不足被取消 | Gartner，由 Atlan 转述 | 2026 年发布的预测 |
| 配置错位 | 同一个模型只换文件编辑接口，编码基准从 6.7% 跳到 68.3% | JavaGuide 转述实验数据 | 截至 2026 年 6 月 |
| 配置错位 | Claude Opus 4.6 在 Claude Code 排第 33，换一个未见过的 harness 升到第 5（±4 名） | HumanLayer 引 Terminal Bench 2.0 | 截至 2026 年 6 月 |
| 配置错位 | 只优化 harness（文档组织、验证回路、追踪），Terminal Bench 2.0 从第 30 升到第 5，分数 52.8% → 66.5% | LangChain 实测，由 JavaGuide 转述 | 截至 2026 年 6 月 |
| 配置错位 | Solo Harness 20 分钟 $9 跑出半成品 vs Full Harness 6 小时 $200 完整应用 | Anthropic 内部对比，由 JavaGuide 转述 | 截至 2026 年 6 月 |
| 配置错位（反例） | ETH Zurich 测试 138 个 agentfile：LLM 生成的反而伤性能且多花 20%+ 成本；人写的也只提升约 4%；agent 多花 14，22% 推理 token、走更多步、调更多工具，但解决率没提升 | ETH Zurich 研究，由 HumanLayer 引述 | 2026 年发布 |
| 上下文中毒 | 168K 上下文窗口用到约 40% 即进入 Dumb Zone：幻觉、兜圈子、格式混乱、代码变差 | Dex Horthy 观察，由 JavaGuide 转述 | 截至 2026 年 6 月 |
| 上下文中毒 | "上下文是稀缺资源，巨大指令文件会挤掉任务、代码和相关文档" | OpenAI 工程团队，《在智能体优先的世界中利用 Codex》 | 截至 2026 年 |
| 跨会话失忆 | 长任务 agent 在离散会话中工作，每个新会话从对此前发生的事毫无记忆开始 | Anthropic，《Effective harnesses for long-running agents》 | 截至 2026 年 |
| 自评偏差 + 上下文窗口侵蚀 | 同一 Claude 实例自写自审几乎总说"良好"；第 50 轮决策可能与第 5 轮架构决策正面矛盾 | Anthropic 工程团队观察，由腾讯云转述 | 截至 2026 年 |
注意 ETH Zurich 那一行。它反证的是"agentfile 越长越好"这个假设。138 个文件里 LLM 自动生成的版本同时拉低成功率和抬高成本，人写的也只多挤出 4%。这件事和上面其它数据点合起来读才有意义：harness 重要，但 harness 不等于"塞更多文字进 AGENTS.md"；真正起作用的是结构、约束和反馈回路，不是字数。
Mtrajan 在《Harness Engineering Is Not Context Engineering》里给过一个非常实用的二分法："错一次输出，多半是 context 问题；几周内缓慢退化，那是 harness 问题。"单点幻觉、单次格式错、单次工具调错，先查这次输入里塞了什么、缺了什么；要是 agent 上周还能正常推进，这周突然开始反复绕同一个坑、反复破坏同一类约定，模型并没有变笨，是你的 harness 在沉默地腐烂。想把这条边界讲到颗粒度更细，什么改 context、什么改 harness、什么改 spec，看harness engineering vs context engineering那篇。
一个 harness 由哪些组件构成
主线用 Martin Fowler 网站上的 guides / sensors 两分法：**Guides 是前馈控制，在 agent 行动之前引导它，让它第一次就尽量做对；Sensors 是反馈控制，在 agent 行动之后观察它，让它自我纠正。**这两类组件正好对应前面四类病的两条治法：行动前怎么不犯错，行动后怎么发现错并修。
Martin Fowler 还在 guides 和 sensors 之上叠了一个执行方式维度：computational（确定性、由 CPU 跑的测试 / linter / 类型检查器 / 结构分析，毫秒到秒级，结果可靠）vs inferential（语义分析、AI 代码评审、LLM as judge，由 GPU 或 NPU 跑，慢且结果不确定）。这一层在你设计反馈回路时很关键，能用 linter 解决的，别用模型去判；能用确定性测试拦的，别让模型去自评。
Guides 和 sensors 的组件归属
Atlan 把 guides 和 sensors 各自包含的具体组件整理得比较清楚，LangChain 的 harness 解剖又从基础设施角度补了一份原语清单。两份清单合起来，组件归属是这样：
| 类别 | 组件 | 治什么 |
|---|---|---|
| Guide（前馈） | 系统提示词、AGENTS.md、约束文件、上下文管道 | 行动前给方向、给约束、给上下文 |
| Guide（前馈） | 工具 / 技能 / MCP 服务器及其描述 | 限定 agent 能用什么手段 |
| Guide（前馈） | 文件系统 / 沙箱 / 浏览器 | 给 agent 工作空间和安全隔离 |
| Sensor（反馈） | evals、验证回路、输出解析器、漂移检测器 | 行动后发现问题 |
| Sensor（反馈） | hooks / 中间件（compaction、续接、lint 检查） | 行动后自动修或自动拦 |
| 编排（横跨两类） | 子代理生成、handoff、模型路由 | 把工作切片、把上下文隔离 |
LangChain 强调有几个原语是"harness 之所以是 harness"的最低门槛：filesystem 是最基础的原语，模型只能操作上下文窗口里的东西，文件系统让 agent 拥有工作空间、把中间产物持久化到会话之外；默认配 bash 工具，与其为每种可能的动作都预设工具，不如给 agent 一个通用工具让它自己写代码运行代码；沙箱让 agent 能扇出，按需创建、跑完销毁，没有沙箱就不可能做大规模并行。AGENTS.md 在 LangChain 那里被定位为一种"harness 级别的记忆原语"：启动时注入上下文，agent 编辑后又被加载回上下文，本质是把一次会话的知识存到下一次会话。
对长任务来说，光有 filesystem 还不够。Cobus Greyling 描述的多层记忆把这件事讲透：工作上下文、会话状态、长期记忆三层叠起来跨越单个上下文窗口持续存在，Anthropic 的做法是用进度文件加 git 历史来桥接多个会话。
LangChain 还点名了三种专门治 context rot 的 harness 级组件：compaction（窗口快满时智能卸载并摘要已有上下文）、tool call offloading（只保留工具输出的头尾 token，完整输出写入文件系统）、skills（渐进式披露，解决工具或 MCP 服务器一启动就把上下文挤爆的问题）。具体每种怎么写、阈值定在哪、什么时候用 context resets，是 harness engineering for long running 那篇的活。这些是 harness 层的标准原语，不属于模型层。
状态机加权限白名单：把约束写进代码
Guides 不止是写在 AGENTS.md 里的几句话，更硬的形式是用状态机锁住 agent 在每个阶段能调用什么工具。cnblogs 那篇文章给了一段最小可工作的代码，把四个阶段的工具权限白名单直接写死：
PHASE_PERMISSIONS = {
AgentPhase.RESEARCH: ["read_file", "search_code", "list_files"],
AgentPhase.PLAN: ["read_file", "create_plan"],
AgentPhase.EXECUTE: ["read_file", "write_file", "run_command"],
AgentPhase.VERIFY: ["run_tests", "run_lint", "run_typecheck"],
}
这段代码对应的运行时序大概是这样：harness 启动新会话、加载 AGENTS.md、初始化状态为 RESEARCH；agent 想直接改代码，harness 检查 RESEARCH 阶段不允许 write_file，拒绝；agent 转而请求进入 PLAN 阶段，harness 校验状态迁移合法后允许；agent 在 EXECUTE 阶段改完 login.tsx，harness 自动触发验证守卫，强制进入 VERIFY 跑 typecheck / lint / test；全通过任务完成，不通过把错误反馈给 agent 重试。
这就是 guides 和 sensors 在同一段代码里协作的样子：状态机本身是 guide（行动前限定能做什么），VERIFY 阶段的 typecheck / lint / test 是 sensor（行动后查错），失败时把错误注入循环让 agent 自己改也是 sensor。
Sensors 的两条经验
HumanLayer 总结的两条 sensor 经验在实战里特别管用。
第一条是 sub-agents 作为上下文防火墙：把一段离散任务封装到独立的上下文窗口里，父线程只看到自己写给 sub-agent 的提示和 sub-agent 的最终结果，所有中间工具调用、工具结果和噪声消息都不会回到父 agent 的上下文。这是治 context rot 的结构性解法，不是让模型自己注意别说太多，而是从架构上不让噪声进来。
第二条是 hooks 的"成功保持沉默，失败要详细"原则。如果 typecheck 通过，agent 什么都不会听到；如果失败，错误文本会被注入循环让 agent 自行修正。常态下反馈回路几乎零开销，出问题时直接可执行。这条原则把 Addy Osmani 的"失败可读"心态落到具体行为上：agent 不知道某个约定就加进 AGENTS.md，跑了破坏命令就加 hook 拦下，40 步任务里迷路就拆 planner 加 executor，把 typecheck 当反压信号接进循环。
Anthropic 在工程实践里提炼出的一条强杠杆配得上单独一句：把做工作的 agent 和评判工作的 agent 分离。让评估者变得更怀疑，远比让生成者变得更自我批判要容易。这条直接对应前面讲的"自评偏差"那一类病。
几份典范实现的取舍
把组件清单落到真实项目，会看到几种风格各异的实现：
Anthropic 的双 agent 加 feature list JSON。第一个会话用 initializer agent 跑特定提示设置初始环境（init.sh 脚本、claude-progress.txt 进度文件、初始 git commit），之后每个 coding agent 会话只做增量进展并留下结构化更新。配套的 feature list 是一份 JSON 文件（claude.ai 克隆案例里超过 200 条 feature，初始全部标记 failing），coding agent 只允许改 passes 字段。他们经过实验后特意选 JSON 而不是 Markdown，因为模型不会像改 Markdown 那样随意改 JSON。
OpenAI Codex 团队的"地图而非 1000 页说明书"。AGENTS.md 只有大约 100 行，定位是"内容目录"，指向 docs/ 目录下结构化的真实信息来源。架构约束不靠提示词去说，靠 linter 和结构测试机械执行：每个业务领域内代码只能"向前"依赖于 Types → Config → Repo → Service → Runtime → UI 这组固定层，横切关注点（认证 / 连接器 / 遥测 / 功能标志）只能通过单一显式接口 Providers 进入，其他依赖直接被拒绝。再往上一层是"黄金原则"加后台 Codex 任务定期扫描 / 更新质量等级 / 发起重构 PR，大多数能在一分钟内审完自动合并，这是把"AI 残渣"循环清理从每周五手动 20% 工时挪进自动化流程的关键。
OpenAI 还把可观测性当作组件做：让应用根据 git worktree 启动，Codex 为每次更改启动并驱动一个实例；把 Chrome DevTools 协议接入 agent 运行时，做 DOM 快照 / 截图 / 导航的技能；日志、指标、追踪通过本地可观测性栈对 Codex 可读，Codex 用 LogQL 查日志、PromQL 查指标。这让 Codex 能复现 bug、验证修复、直接推理 UI 行为。
腾讯云描述的六智能体流水线。Planner → Generator → Code Reviewer → Security Reviewer → QA Engineer → Debugger，每个智能体有独立的认知边界和评判标准，相互之间的张力构成了系统的质量保障。配套的状态持久化策略是三层：每个 agent 执行完成的瞬间写入磁盘的实时关键事件保存、每 30 秒一次的定时自动保存、退出前保存。目标是让一个运行 6 小时的流水线中途崩溃也不会丢 5 小时工作和 150 美元成本。
Mitchell Hashimoto 的 Ghostty AGENTS.md。这份文件里每一行都对应一次过去 agent 的具体失败，是一个持续积累的防错系统。Addy Osmani 把这件事提炼成纪律性原则：**只在看到真实失败时才加约束，只在能力足够强的模型让某条约束变得多余时才移除它；好的 AGENTS.md 每一行都能追溯到一件具体出错的事。**这条原则把"AGENTS.md 该写多少行"这种容易跑偏的问题压成了一个简单判据：写多少行不重要，每行都得有据可查。
最小起步态：L1 加 L6 第一天该配什么
这些清单不需要一上来全搭齐。JavaGuide 把 harness 拆成的六层架构（L1 信息边界 / L2 工具系统 / L3 执行编排 / L4 记忆与状态 / L5 评估与观测 / L6 约束校验恢复）给出了一条务实路径：先做 L1（让 agent 知道边界）加 L6（出错能拦能恢复）。cnblogs 把同一件事压成三根支柱：可读性（让 agent 读懂你的系统）、防御机制（让 agent 跑在轨道里而不是靠自觉）、反馈回路（让 agent 犯错后越来越稳）。三个维度切的是同一块蛋糕，没必要纠结哪套术语最对，抓住 guides / sensors 这条主线，其他清单都能挂上去。
L1 加 L6 起步态落到第一天的最小行动清单大概是这五件：
AGENTS.md（L1，~50，100 行）：项目目标一句话、目录地图（指向 docs/ 而不是把内容塞进来）、不要做什么的黑名单（比如"不准直接改 schema.sql""不准提交未跑过测试的 PR"）。Addy Osmani 的纪律性原则要从第一天就上：每条规则都对应一次真实失败，不写"以防万一"的空话。OpenAI 团队那份 100 行的 AGENTS.md 是上限参考，不是起步线。起步线更短，遇到一次失败加一条。docs/目录（L1，结构化真理来源）：把 README、架构说明、约定全放进来，让 AGENTS.md 当目录指过去。这样 agent 想看哪一块自己去拉，不会一次塞爆上下文。- 阶段权限白名单（L6，10，20 行 Python 或配置）：RESEARCH/PLAN/EXECUTE/VERIFY 四阶段最小版，工具按阶段分组。哪怕只配 EXECUTE 阶段不让动
db_migrate、VERIFY 阶段只跑pytest，也已经把"agent 在错的阶段做错的事"这一类大坑拦掉了。 - 一条
on_file_changehook（L6，sensor）：改完文件强制跑一次 typecheck 或 lint，按 HumanLayer 的"成功保持沉默，失败要详细"原则，通过零开销，失败把完整错误塞回循环。这是 sensor 回路的最低投入版本，比写一堆 eval 见效快得多。 - 一个进度文件（L1 加 L6 桥接，纯文本即可）：仿 Anthropic 的
claude-progress.txt，让 agent 每完成一步追加一行"做了什么、改了哪些文件"。跨会话失忆和"自己绕回起点"这两类病靠这一个文件就能拦住一大半，工作量比想象的小。
判断 L1 当前是缺还是够，有一个最直接的检验：把一个新 agent 会话冷启，丢一句"修一下 X 模块的 Y bug"，看它会不会去问目录在哪、约定是什么。如果它直接开始瞎猜文件路径、瞎调工具，L1 没建好。判断 L6 是缺还是够，看一次 agent 跑挂时它有没有自动停下来。如果它继续往下编、继续把破代码标记成"任务完成"，L6 那层 sensor 就是空的。
Claude Code 上 AGENTS.md 该写多少行、permissions / skills / plans 具体怎么配、最有用的几类 hook 长什么样，harness engineering for claude code 那篇会给到可以照着抄的范本。
工程师不再写代码，而是为 agent 搭运行系统
OpenAI Codex 团队把这次转变写成了一条信条：人类掌舵，agent 执行，团队规则是不手动编写代码。这是 5 个月里一百万行代码、1500 个 PR 走下来后留下的工作纪律。Epsilla 在复盘这段实验时把状态归纳得更直白，他们不再当 coder，而成为控制系统和反馈回路的架构师，这是 harness engineering 替换 prompting 成为 2026 年新主线学科的关键转折。工程师的工作重心从写函数转向了系统、架构和杠杆作用：事情卡住时，解决办法不再是"再努力一点写一段"，而是把每一次卡顿都翻译成一个新的问题，还缺哪种能力，怎么让这种能力对 agent 既清晰可读、又可强制执行。
最棘手的活儿因此换了一批。OpenAI 团队总结当前最难的挑战集中在设计环境、反馈回路和控制系统，目标是让 agent 大规模构建并维护复杂、可靠的软件。Nicholas Carlini 给这件事补了一句最刺耳的提醒："我必须不断提醒自己，我是在为 Claude 写这个测试框架，不是为自己写"。harness 的第一服务对象是 agent，不是人。代码注释、目录结构、类型签名、lint 规则、错误信息，所有这些过去为人类可读性服务的东西，现在首先要为 agent 可读性服务；这是工程审美层面的彻底反转。
Epsilla 把 OpenAI 那 5 个月的经验提炼成五条 harness 准则，可以直接当工程师每天的工作清单用：仓库是 agent 唯一的真理来源，不假设任何外部知识；代码必须对 agent 可读，结构清晰、注释详尽；架构约束靠 linter 而不是提示词强制执行，你不是在请求 agent 遵守规则，而是搭一套让它违反不了的系统；自主权要分阶段授予，harness 必须有阶段和闸门；一个 PR 如果需要大量人工介入，那不是 agent 的问题，是 harness 的问题。最后这条最值得贴在显示器边上：每次想骂 agent 的时候先问自己 harness 缺了什么。
OpenAI 的 agent 端到端能力链条已经包含验证仓库当前状态、复现已报告的 bug、录制故障演示视频、实施修复、运行验证、录制修复后视频、开 PR、回应人类和 agent 的反馈、检测并修复构建故障、仅在需要判断时交人、合并。工程师不再亲手做这条链上的任何一步，工作变成保证 agent 能稳定地走完这条链。每一次走不通都是一次 harness 缺口诊断：缺约束、缺 sensor、缺权限白名单、缺 sub-agent 隔离、缺持久化检查点。
工具链也正在往这个方向收敛。Addy Osmani 把这股趋势命名为 HaaS（harness as a service）：行业正在从基于 LLM API 转向基于 harness API。LLM API 给你的是"一次补全"，harness API 给你的是"一个运行时"。Claude Agent SDK、Codex SDK、OpenAI Agents SDK 都指向同一方向，开箱给你循环、工具调度、上下文管理、hooks、沙箱原语，你做的是定制。这件事的潜台词是：未来几年 harness 不会人人从零搭，而是像今天用云数据库一样订一份基础 harness，在上面叠自己的约束、sensors 和领域知识。
把这些转变落到自己的开发循环里，可以从下面三条路径切入。想立刻动手搭一个 Claude Code 个人 harness，看实操篇。想区分 prompt / context / spec-driven / harness 四个概念到底各管什么、彼此边界在哪，看辨析篇。当你的 agent 任务从 30 分钟拉长到 6 小时甚至几天，想把 harness 推向长任务和生产场景，看进阶篇，里面有 Ralph Loop、三主体、context rot 防御和生产 harness 的数据墙。
FAQ
Harness engineering 中文怎么翻译？硬翻成"马具工程"合适吗？
不合适。Harness 在这里是借喻，指套在模型外面的那整套驾驭系统，硬翻成"马具"没有任何传播价值，中文技术圈目前通行直接用 harness engineering 原词，或者说"agent 运行框架工程"、"agent 控制层工程"。这个词 2026 年才刚被命名，中文标准译法尚未形成；如果你在写内部文档，最稳的做法是第一次出现时加解释，"harness engineering（在模型之外为 agent 搭建可控运行系统的工程实践）"，之后直接用缩写 harness。
What does harness mean in engineering（harness 在工程里到底什么意思）？为什么这个旧词被借来描述 AI agent？
Harness 在工程领域的本义是"测试线束"，一整套把被测系统挂进测试环境的连接和控制装置，它不改变被测系统本身，只决定系统在什么条件下运行、出什么样的输出。AI agent 领域借这个词，是因为它的结构刚好一样：harness 不改动模型权重，只在模型外面决定它能调什么工具、看到什么上下文、出了错被怎么拦住。这比"框架"（framework）或"脚手架"（scaffold）更准确，框架通常指开发者写的代码结构，而 harness 强调的是"它首先是给 agent 用的，不是给人用的"。
Harness engineering 是 Karpathy 提出的吗？它和 context engineering 是同一回事吗？
不是，也不是。Karpathy 推的是 context engineering，核心问题是"该让 agent 看到什么信息"；harness engineering 关注的是"用什么结构和约束让 agent 在运行时不出轨"，两者处理的层次不同。"harness engineering"这个词是 HumanLayer 的 Viv Trivedy 创造的，Agent = Model + Harness 公式是 Mitchell Hashimoto 提炼的，这都发生在 2026 年初、Karpathy 推出 context engineering 的大约半年之后。把 harness engineering 算到 Karpathy 头上是中文社区的常见误会，本文第三节的时间线已专门厘清。
Harness engineering 有学术论文吗？arXiv 上能查到什么？
Cobus Greyling 指出 arXiv 上已有论文在对 harness 这一模式做形式化，但这个领域 2026 年初才被命名，学术存量目前有限，实践走在学术前面。ETH Zurich 那项研究（测试 138 个 agentfile 对 coding agent 成功率的影响）是目前少数严格受控实验之一，结论是 LLM 自动生成的 agentfile 反而伤性能且多花 20%+ 成本，人工写的也只提升约 4%；这条数据已在正文数据墙中引用（单一来源，结论仅代表该研究的测试条件）。学术论文层面的系统综述目前尚无可靠来源，如需追踪最新进展，搜索关键词"agent harness"在 arXiv 上做定期追踪比等综述更有效。
Harness engineering 和 framework / SDK 有什么区别？为什么说它是"第四种 agent 架构模式"？
Cobus Greyling 给出的层级是：SDK（最底层 API）到 framework（LangChain / LlamaIndex 这类编排工具）到脚手架（Cookiecutter 类项目模板）到 harness（最上层，告诉 agent 怎么安全运行）。Framework 的使用对象是开发者，告诉开发者怎么搭应用；harness 的使用对象是 agent，告诉 agent 怎么执行、边界在哪、出错怎么处理。一个具体区分：LangChain 本身是 framework，你在 LangChain 上给 agent 配的 AGENTS.md 加权限白名单加 typecheck hook 加 sub-agent 隔离策略，这整套是 harness。harness 通常构建在 framework 或 SDK 之上，但它解决的问题（agent 运行时的可控性和可恢复性）是 framework 本身不处理的。
What is a harness engineer（harness engineer 到底是干什么的）？工程师 title 真的要变成 harness engineer 吗？
Harness engineer 目前更接近一种角色描述，不是一个正式的职位头衔。按 OpenAI 团队的实践，harness engineer 的日常工作是：设计 agent 的工具权限边界、写 AGENTS.md 和约束文件、搭 eval 和 sensor 回路、诊断 agent 失败时 harness 缺了什么，工作重心从"写代码"转向"设计让 agent 能正确运行的环境"。Addy Osmani 提出的 HaaS（harness as a service）趋势意味着这个角色的底层工具链正在标准化，但具体落地方式（独立岗位、平台工程的一部分、还是每个工程师的必修能力）目前业界没有定论。可以确定的是：2026 年拿到过 agent 项目生产经验的工程师，多数人正在做的事已经是 harness engineering，只是没有这个名字。
ETH Zurich 那项研究里，LLM 自己写的 agentfile 为什么反而伤性能？根因是什么？
InfoQ 转述的研究分析给出了具体根因，LLM 生成的 agentfile 主要在重复 README 和 docs 已经写过的信息。研究者做了一个反向实验：把仓库里已有的 README 和 docs 删掉之后，LLM 生成的 agentfile 反而能把成功率提升约 2.7%，这反过来证明它们在原仓库里只是把已有信息又复述了一遍。机制上看，指令本身会被 agent 老老实实遵守，但内容是冗余的，结果是 agent 跑更多次测试、做更广泛探索（这也是为什么多花 14，22% 推理 token、调更多工具），但并没有得到一份有效的"仓库总览"。写 AGENTS.md 时这条结论的现实启示：让模型自动生成是最不划算的做法；写之前先问"docs/ 里有没有"，有就改成在 AGENTS.md 里指过去，没有就动手补 docs 而不是把内容塞进 AGENTS.md。
Anthropic 为什么选 JSON 而不是 Markdown 做 feature list？这条经验能推广到别的状态文件吗？
机制有两层。一层是 schema 约束：JSON 的字段名、类型、嵌套结构是显式的，模型改起来要么改进字段值、要么破坏结构（结构破了 schema 校验直接报错），中间态很少；Markdown 是自由文本，改一行、加一段、调整标题层级，每一步都"看起来还合法"，模型很容易顺手就把整个文件改写。另一层是模型行为偏置：TianPan 的观察是，把结构化 JSON 上下文喂给模型时，token 分布会被拉向 schema 一致的补全，它会去填字段而不是自由推理，这正是结构化输出有用的同一条机制；Markdown 则鼓励层次化综合，给模型更多自由发挥的空间。这条经验推广到其他状态文件的判据是：你希望模型只在固定字段里做受限更新（进度状态、测试通过列表、待办状态）就用 JSON；你希望模型自由组织内容（思考过程、设计草稿、AGENTS.md 这种叙事文档）就用 Markdown。错配的代价就是 Anthropic 那条原始观察，状态文件用 Markdown，模型会随手把它改成另一个文件。