核心结论
Harness Engineering 不是“写更好的提示词”，而是把 Coding Agent 外围的工程系统做成可执行、可观测、可约束、可评测、可持续改进的控制面。LangChain 用一句话概括为 Agent = Model + Harness：模型提供推理能力，harness 提供状态、工具、执行环境、权限、反馈循环和验证机制。OpenAI 的 2026 年案例则把这个概念推到软件生产层面：团队让 Codex 在数月内生成应用代码、测试、CI、文档、观测配置和内部工具，人类不直接手写代码，而是设计环境、约束和反馈回路。
对 AI 全栈架构师来说，重点不是照搬“0 行人工代码”的极端约束，而是理解背后的工程迁移：人的工作从写函数下沉为写系统规则，从单次 review 转为建设可重复触发的 sensors，从口头经验转为 repo-local 的 guides。越想提高 Agent 自主性，就越需要更强的结构化约束，而不是更少约束。
概念边界
Prompt Engineering 解决单次交互怎么表达意图；Context Engineering 解决把哪些信息放进模型上下文；Harness Engineering 则覆盖更完整的运行系统。它包括指令、文件系统、代码执行、沙箱、浏览器、日志、测试、CI、评测、权限、记忆、计划文件、工具描述、MCP、hooks、compaction、subagent handoff 和质量清理流程。
Martin Fowler / Thoughtworks 的拆法很实用：harness 由 guides 和 sensors 共同构成。Guides 是前馈控制，在 Agent 动手前提高它做对的概率，例如 AGENTS.md、架构文档、技能、服务模板、设计原则、API 参考和任务规格。Sensors 是反馈控制，在 Agent 动手后让它发现并纠正错误，例如类型检查、lint、单元测试、结构测试、浏览器自动化、日志查询、trace、AI code review 和人工验收。
这也解释了为什么单纯“多塞上下文”不是答案。上下文会占用窗口，会过期，会互相矛盾。真正能长期复利的是把上下文变成可索引的文档、可执行的脚本、可失败的测试和可阻断的结构规则。
OpenAI 案例给出的工程信号
OpenAI 的 Harness Engineering 文章里，几个数字值得拆开看。第一，代码库从空仓库开始，初始 scaffold、CI、格式化、包管理、应用框架和 AGENTS.md 都由 Codex 生成。第二，五个月后代码库达到百万行量级，约 1500 个 PR 被合并。第三，三名工程师驱动 Codex 时平均每人每天 3.5 个 PR，团队扩大后吞吐还继续提升。第四，产品已经有内部日常用户和外部 alpha 用户，说明这不是一次 demo 生成实验，而是在真实产品压力下验证工程方法。
但更重要的是组织方式变化。人类不再把时间花在“这段代码我来补一下”，而是问：“Agent 为什么反复失败？缺少的是工具、文档、测试、架构约束，还是可观测信号？”如果缺的是规则，就让 Agent 把规则写进 repo；如果缺的是检查，就补 linter、结构测试或评测；如果缺的是运行视角，就让 Agent 能启动应用、看 DOM、看截图、查日志、查指标和 trace。
这个模式和传统平台工程非常接近：中心化定义边界、本地允许自治。差别在于，过去这些规则主要服务人类协作；现在它们还要服务 Agent 的机器可读性和自我修复能力。
Harness 的六层结构
第一层是 任务规格层。它回答 Agent 到底要完成什么、哪些行为算完成、哪些行为必须拒绝。Anthropic 的长任务 harness 会让 initializer agent 把用户的一句话扩展成 feature list，并把每项功能初始化为 failing，后续 coding agent 只能逐项完成和更新状态。这个设计的价值是减少“快到上下文末尾就自称完成”的早停问题。
第二层是 知识与上下文层。OpenAI 的做法是让短 AGENTS.md 像目录，不像百科全书。真正的系统知识放在版本化的 docs/、产品规格、执行计划、架构文档、质量评分和技术债清单里。原则是：Google Docs、聊天记录和人脑里的 tacit knowledge 对 Agent 来说都等于不存在，必须沉淀到 repo-local artifact。
第三层是 工具与执行环境层。Agent 需要文件系统、shell、包管理器、浏览器、测试 runner、日志查询、云端或本地沙箱。LangChain 把文件系统、bash、沙箱、浏览器和测试工具都视为 harness primitive，因为它们让模型从“输出文本”变成“执行并观察结果”。
第四层是 架构约束层。对 Agent 友好的代码库通常有明确模块边界、强类型、schema 边界校验、依赖方向规则、文件大小限制、日志规范和命名规范。OpenAI 案例中，业务域被拆成固定层次，跨层依赖由自定义 linter 和结构测试强制执行。这样的规则在人类团队里有时显得繁琐，但在 Agent 高吞吐环境里是防止架构漂移的基础设施。
第五层是 反馈与评测层。快速 sensors 包括 typecheck、lint、unit test、coverage、dependency rules；较慢 sensors 包括 E2E、Playwright、mutation testing、AI review、架构审查和安全扫描；生产 sensors 包括 SLO、错误率、延迟、成本、用户反馈和抽样质量评测。Anthropic 的 agent evals 文章强调，Agent 评测不能只看最终回答，还要记录完整 transcript、tool calls、intermediate results 和最终环境状态。
第六层是 持续清理层。高吞吐 Agent 会复制仓库里已有模式，包括坏模式。OpenAI 一开始用每周清理处理“AI slop”，后来改成把 golden principles 写入 repo，并让后台 Codex 任务定期扫描漂移、更新质量分、开小型重构 PR。这里的关键不是大清理，而是高频、可审查、低成本的质量回收。
Guides 与 Sensors 矩阵
| 目标 | Guides | Sensors |
|---|---|---|
| 维护性 | 编码规范、文件边界、命名规则、共享工具库约定 | lint、typecheck、重复代码扫描、复杂度、覆盖率 |
| 架构适配 | 分层架构图、依赖方向、服务模板、接口契约 | 结构测试、dependency-cruiser、ArchUnit、schema 校验 |
| 行为正确性 | 产品规格、验收场景、golden fixture、失败样例 | E2E、浏览器自动化、契约测试、人工验收、mutation testing |
| 运行可靠性 | SLO、日志规范、trace 规范、降级策略 | Prometheus 指标、日志查询、trace、告警演练 |
| 安全治理 | 最小权限、审批策略、工具分级、密钥策略 | Semgrep、secret scan、权限审计、红队样例、策略回放 |
| 长任务连续性 | 计划文件、进度文件、handoff artifact、git commit 约定 | 状态恢复测试、任务回放、未完成项检查、上下文重启实验 |
这张表的实用性在于：任何重复出现的问题，都应该被归类为某一类 guide 缺失或 sensor 缺失。如果 Agent 总是误解业务目标，优先补规格和验收样例；如果总是破坏模块边界，补结构规则；如果总是声称完成但页面不可用，补浏览器级 E2E；如果总是生成安全风险代码，补工具权限、静态扫描和红队样例。
和现有 Agent 架构的关系
convee.cn 之前讨论过 Agent Runtime 事件总线 和 Agent 安全治理。Harness Engineering 可以理解为它们之上的工程操作系统。
Agent Runtime 事件总线解决“运行过程如何表达”：token、tool call、handoff、subagent、审批、中断、恢复和 trace。安全治理解决“哪些动作可以发生”：权限、密钥、审批、审计和风险策略。Harness Engineering 解决“如何让 Agent 长期稳定参与软件生产”：它把运行事件、安全规则、测试反馈、代码结构、文档知识和人类 judgment 都放进同一套可迭代控制系统。
所以，真正的 Coding Agent 平台不应该只卖“模型更强”或“工具更多”。它应当能回答这些问题：Agent 当前任务状态在哪里？依据哪份规格行动？能访问哪些工具？每次工具调用谁授权？失败后如何恢复？哪些测试证明它没有破坏系统？哪些规则防止它把坏模式扩散到整个仓库？
最小落地方案
第一步，建立 repo 入口。保留一个短 AGENTS.md，只放工作流入口、常用命令、重要目录和禁止事项。把长文档拆到 docs/architecture.md、docs/testing.md、docs/security.md、docs/product/、docs/runbooks/，并保证这些文档能被测试或 CI 检查基本新鲜度。
第二步，定义可执行验证命令。至少包括格式化、lint、typecheck、单元测试、内容或 schema 校验、构建。不要只告诉 Agent “保持质量”，而要告诉它“运行哪个命令，什么输出才算通过”。
第三步，补足浏览器和观测视角。Web 应用要让 Agent 能启动本地服务、打开页面、截图、读取 DOM、触发用户路径；后端服务要让 Agent 能看请求日志、错误日志、metrics 和 trace。没有运行视角的 Agent 很容易停在“代码看起来对”。
第四步，把 review 意见固化。凡是同一类意见出现两次以上，就不要只在 PR 里继续评论，而是转成规则、测试、脚本、模板或文档。对 Agent 来说，一次性口头反馈不会自然变成组织记忆。
第五步，建立低成本清理循环。每周或每日运行 dead code、重复代码、测试质量、依赖漂移、文档漂移、安全规则扫描。让 Agent 开小 PR 修复，而不是等技术债累积成一次大型重构。
风险边界
Harness 不能替代清晰目标。Martin Fowler 特别指出，维护性和架构类 harness 相对容易，因为已有大量确定性工具；行为正确性最难，因为如果人类没有明确说明想要什么，任何 sensor 都无法可靠判断“做错了需求”。因此，产品规格、验收样例和人工 judgment 仍然是最高杠杆。
Harness 也不能保证所有模型都一样可控。Anthropic 的长任务文章反复强调，compaction、context reset、handoff artifact、planner/generator/evaluator 分离都会影响最终表现；这些设计和模型能力共同演化。换模型、换工具、换沙箱，都可能改变原有 harness 的有效性。
最后，低阻塞 merge 不是默认最佳实践。OpenAI 的案例能减少阻塞，是因为它同时有强测试、结构约束、持续清理和可回滚机制。对普通团队来说，应先把 fast sensors 和关键行为验收补齐，再逐步降低人工 gate，而不是一开始就让 Agent 自动合并。
面试与团队能力考察
如果用 Harness Engineering 考察 AI 后端、Agent 工程或 AI Infra 候选人，可以重点看四类能力。
第一，是否能区分 prompt、context、harness。优秀候选人不会把所有问题都归因于“提示词没写好”，而会主动讨论工具、状态、权限、测试和反馈信号。
第二，是否能把抽象原则落成工程控件。例如“不要破坏架构”应落成依赖方向测试；“要可观测”应落成 trace schema、日志字段和查询路径；“要安全”应落成工具分级、短期凭据、审批和审计。
第三，是否理解 Agent 自评的局限。强候选人会把生成者和评估者分开，组合确定性检查和 AI review，并用人工校准高风险语义判断。
第四，是否能设计持续改进循环。Harness Engineering 的成熟度不在第一版规则多完整，而在团队能不能把失败样本、review 意见、线上事故和重复缺陷持续转化为 guides 与 sensors。
判断标准
一个团队是否真的具备 Harness Engineering 能力，可以看三个结果：Agent 能否在没有大量人工复制粘贴上下文的情况下理解仓库；Agent 能否在提交前自己发现并修复大部分机械性错误；团队能否把重复错误沉淀成可执行控制，而不是只靠人类记忆和口头约定。
如果答案是肯定的，Coding Agent 就不再只是“更快写代码的助手”，而开始成为软件生产系统的一部分。真正的竞争力也不再只是选哪个模型，而是组织能否持续建设这套让模型可靠工作的 harness。