Harness Engineering on 鬼哥的空间

harness 不再纸上谈兵：开源 harness-project-template，附完整工作流实战

Mon, 27 Apr 2026 00:00:00 +0000

模型已经够强了。接下来卡你的不是模型，是工作流。

Codex-5.5、Claude Opus 4.7、Gemini 3、Grok 4 这一代模型出来之后，“AI 写代码"的天花板被肉眼可见地抬高了一格。一句模糊的需求扔进去，500 行能跑的代码就出来了。

但稍微跑过几个真项目你就会发现：模型再强，也只能解决"写代码"这一段；从需求到上线之间的所有事情——怎么拆需求、怎么管上下文、怎么验证、什么时候让人接管——需要一套系统化的运行规范。

这就是 harness 要解决的问题。

最近半年，Anthropic、OpenAI、Google DeepMind、Stripe 一波接一波地讲 Harness Engineering；Addy Osmani 把 Google 14 年工程文化压缩成 19 个 agent skill 开源放出来；社区里"工作流第一、模型第二"几乎成了共识。理论分析和最佳实践讨论已经够多了。

但你打开 GitHub 想找一个能 clone 就用的脚手架，会发现极少。要么是 SaaS 公司的工作流截图（看不到代码），要么是某个 README 里散落的 CLAUDE.md（缺工具链衔接），要么是单个 skill 文件（没串成完整流水线）。理论已经足够，缺的是开箱即用的脚手架。

于是鬼哥我做了两件事：

整理出一个 GitHub Template：luoli523/harness-project-template —— Python + FastAPI 起步，clone 即用，30 秒装好。
用它从 0 跑了一个真实 v1 示例项目（多币种财务账本），39 个 atomic commit、253 个测试、93.79% 覆盖，从 SPEC 到 SHIP 一步没跳。

下面分两部分：先看模板长什么样、怎么用；再看那个 v1 项目是怎么从一句需求一步一步落到 39 个 commit 的，全程截图。

一、template：长什么样、怎么用

目录结构

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


harness-project-template/
├── .agent/prompts/ # 工具无关的 prompt 模板
├── .agents/skills/ # 6 个核心 skill（Claude Code + Codex 自动发现）
├── .claude/ # Claude Code 专属：slash commands + permissions
├── .github/workflows/ # CI 跑同一组门禁（ruff + mypy + pytest）
├── AGENTS.md # 项目规约（所有 agent 必读）
├── CLAUDE.md # 指向 AGENTS.md
├── src/<your_pkg>/ # FastAPI 脚手架（一个 /health 端点 + async 测试）
├── tests/
└── scripts/init-template.sh # 一键改名 + sync + 装 hooks

事实来源在 AGENTS.md + .agents/skills/，工具特定入口（slash command）只是包装。换 IDE 不用重新教 agent，这是设计上的关键。

6 个核心 skill

这 6 个 skill 不是我自己造的——它们摘选自 Google 资深工程师 Addy Osmani 开源的 addyosmani/agent-skills 项目（详细解读见 Agent Skills：当 Google 工程文化遇上 AI 编程代理）。Addy 把 Google 14 年工程文化压缩成 19 个 agent-executable skill，每个都是一份带"反合理化表"的 markdown 工作流。我没把 19 个全塞进模板，只放每个项目里最小化能把项目跑起来的 6 个：

Skill	何时调用	核心约束
`spec-driven-development`	新功能起步	先列假设清单 → 用户确认 → 写 spec
`planning-and-task-breakdown`	spec 通过后	拆成 ≤100 LOC 任务，每任务 2-5 条二元验收
`incremental-implementation`	单任务实现	RED → GREEN → REFACTOR → atomic commit
`test-driven-development`	任何业务逻辑	先写失败测试，看红，再写实现
`code-review-and-quality`	自审时	五轴顺序：correctness → readability → architecture → security → performance
`git-workflow-and-versioning`	提交时	一任务一 commit，message 引用 spec

剩下 13 个（staged rollout、deprecation migration、incident response 等）按需加，不在最小集合里。

三步起步

1
2
3
4
5
6
7
8
9


# 1. 拉模板（GitHub UI 用 "Use this template" 也行）
gh repo create my-service --template luoli523/harness-project-template --private --clone
cd my-service

# 2. 一键改名 + sync + 装 hooks + 跑门禁
./scripts/init-template.sh my_service

# 3. 启动开发服务器，验证脚手架已绿
uv run uvicorn my_service.main:app --reload

标准使用顺序

之后任何新功能都走这个流程：

1
2
3
4
5
6


/spec <feature> # → 假设清单 → 你确认 → spec/<feature>.md
/plan spec/<feature>.md # → 拆成 ≤100 LOC 任务清单
/build spec/<feature>.md T1 # 一次一个任务，TDD + atomic commit
/build spec/<feature>.md T2
... (重复直到 T_n)
/review # 五轴自审，找 bug 修 bug

每个 slash command 包装一个 skill，跨工具一致。换到 Codex CLI 用 $spec-driven-development、换到 Cursor 直接打开 .agents/skills/<name>/SKILL.md 让 agent 跟着读。

二、实战：从一句需求到 39 个 commit

光看模板不够说服力。下面是我用它跑一个真实 v1（多币种财务账本）的完整过程，截图为证。

Step 1: `/spec` —— 一句话需求 → 假设清单

我扔进去的需求是这样：

我想做一个财务记账系统，自动按月生成资产负债表、利润表、现金流量表。日常货币是 SGD，CNY 消费、USD 投资、HKD 资产。

注意 AI 没有立即开始写 spec。skill 强制它先列出所有它正打算做的隐含假设，让我逐条确认：

四大类：A. 范围切分（最关键，先确认）、B. 业务模型假设、C. 技术假设、D. 验收边界。每条都是一个具体决定（“v1 不做权责发生制”、“HKD 折算并入而不单独成列”、“持久层用 SQLite”），等你 ✓。

这一步的真实价值：它把需求里所有模糊的地方拽到表面。你看到"v1 不做权责发生制"才会反应过来"等下，那利息预提怎么算？"——这才是真正要决定的事。

我逐条回 OK 之后，AI 才动手写 spec/<feature>.md。spec 写完，AI 主动停下：

“按规则停在这里，不进入 plan 阶段。请做以下两件事之一：1. 签字通过——回 approved 或 /plan，或 2. 打回修改…”

这就是 gated workflow 的实物体现：闸门写在 skill 里，AI 自己执行。它不会越权，也不会替你决定 spec 通过没。

Step 2: `/plan` —— 切成 27 个任务卡

spec 签字之后，/plan 命令把它拆成任务清单：

每个任务：≤100 LOC 估算、2-5 条二元验收清单、列出 blocker、依赖图无环。底部 AI 还会标注它自己拿不准的拆分点，建议我"扫一眼”——这种"主动暴露不确定性"也是 skill 引导出来的。

最终这个项目切成 27 个任务，覆盖基础设施 → 数据模型 → 纯函数业务逻辑 → 仓储 → 报表引擎 → HTTP 路由 → 横切错误处理 → E2E + 收尾。

Step 3: `/build T1, T2, ... T27` —— 每任务一个 TDD 红绿循环

/build T1 开始第一个任务。RED 阶段——先写失败测试，跑红：

GREEN 阶段——装依赖、写实现、跑测试转绿、跑全门禁：

ruff check ✅、ruff format --check ✅、mypy --strict ✅、pytest ✅ —— 四道门禁全过才算 GREEN。

最后 atomic commit，pre-commit hooks 再过一遍，commit message 引用 spec + task ID：

关键：单任务做完，AI 自动停下，等下一个 /build T2 或 approved：

“T1 完成，停在这里。等你说 /build 或 approved 我再开 T2…”

不会顺手做下一个任务，不会"图省事一次写完几个"。每个任务一个独立 commit、独立的 RED→GREEN→commit 循环。这种粒度对未来 git bisect 找 bug、git revert 回滚都是无可替代的。

T1 → T27 重复 27 次。

Step 4: `/review` —— 五轴自审

27 个任务全做完后，/review 走五轴自审（correctness → readability → architecture → security → performance），找出了 5 个真 bug + 2 个 spec 漂移。每个发现拆成独立 fix commit + 测试，又是 7 个 commit。

最终交付

39 个 atomic commit、253 个测试、93.79% 覆盖。ruff + ruff format + mypy --strict + pytest 四道门禁全程绿。

从一句需求到能跑的 v1，全程留痕、可审计、可回滚。每个设计抉择有 spec 锚点；每个 commit 可独立 revert；每个 bug 修复有测试。短期看慢一点，长期少欠一笔技术债。

三、Takeaway：现在去 clone

理论文章已经读够多了。这一周我把工作流物化成模板 + 用它跑通一个真实项目，证明这套不是镜中水月。

仓库地址：luoli523/harness-project-template —— Python + FastAPI 起步，30 秒装好，欢迎试用。

这套模板我会持续维护：

你用它跑了项目、发现 skill 该改进、想加新 skill —— 提 issue 或 PR
你跑出来的项目踩了模板没覆盖的坑 —— 提 issue，我把教训沉淀回模板
你想要不同技术栈的类似脚手架（Go、Rust、TypeScript）—— 留言说明诉求，我考虑分仓维护

模型还会变强、context window 还会变大，但让模型按工作流出活这个能力不会自动到来。希望这个仓库帮你省掉前两天的摸索成本。

参考链接

上篇 1：Harness Engineering：当模型够强，系统设计成为胜负手
上篇 2：Agent Skills：当 Google 工程文化遇上 AI 编程代理
模板仓库：luoli523/harness-project-template
原始 skills 项目：addyosmani/agent-skills

Harness Engineering：当模型够强，系统设计成为胜负手

Wed, 01 Apr 2026 00:00:00 +0000

2026 年上半年，AI 工程领域出现了一个升温极快的概念：Harness Engineering。

如果你现在还停留在"怎么写一条更好的 prompt"这个层面去构建 Agent，那你可能正在用 2024 年的方法论解决 2026 年的问题。Anthropic、OpenAI、Google DeepMind、Stripe 这些公司几乎同时开始公开传达一个信号——决定 Agent 能否上线的，不是你给模型喂了什么 prompt，甚至不是你选了什么模型，而是你给模型搭了一套什么样的运行系统。

这套运行系统，就是他们说的 harness。

一匹不知道往哪跑的马

先聊词源。Harness 的原始含义是马具——缰绳、马鞍、胸带，一整套控制马匹的装备。这个隐喻是刻意选择的：马（模型）强大且快速，但自己不知道该往哪跑；骑手（人类工程师）提供方向；而马具（harness）则是将这匹马的原始力量导向有用工作的那层工程结构。

翻译成技术语言：Harness Engineering 不是在教模型怎么回答，而是在设计模型怎么工作。

它处理的是模型外部的那一整层东西：任务怎么拆解、上下文怎么管理、工具怎么编排、权限怎么设定、状态怎么在会话间交接、做完了怎么验证、失败了怎么恢复、什么时候该把控制权交回给人类。这不是一条 prompt 能搞定的事情，这是一个完整的运行时系统设计问题。

三代范式：从 Prompt 到 Harness

要理解 Harness Engineering 的位置，需要把它放进一条更长的演进链里看。

第一代：Prompt Engineering（2022–2024）

核心问题：怎么问？

这是大语言模型进入公众视野后的第一个工程范式。工程师们发现，同一个模型面对不同措辞的提问，输出质量天差地别。于是 few-shot prompting、chain-of-thought、role-playing、self-consistency 等技巧快速涌现。

Prompt Engineering 的本质是单轮、文本层面的优化。你精心措辞一段指令，模型给你一个回复，交互结束。它在问答、文本生成、简单推理等场景下效果显著，但天花板也很明显——当任务复杂到需要多步执行、外部信息检索、跨会话状态维持时，单条 prompt 无论写得多精巧，都无能为力。

第二代：Context Engineering（2025）

核心问题：给模型看什么？

2025 年年中，Shopify CEO Tobi Lütke 在公开场合表示"context engineering 比 prompt engineering 重要得多"。几乎同一时期，Anthropic 工程团队提出了一个精彩的类比：把大语言模型看作 CPU，上下文窗口看作 RAM，那么 Context Engineering 就是操作系统层面管理工作内存的技术。

Context Engineering 涵盖了 RAG（检索增强生成）、记忆注入、工具定义、对话历史管理、动态上下文组装等一系列技术。它的核心贡献是认识到：模型的输出质量不仅取决于你怎么问，更取决于你让它看到了什么。

这是一个重要的认知跃迁——从优化"提问方式"到优化"信息供给"。但 Context Engineering 仍然主要关注模型的输入侧，对模型执行过程中的行为约束、状态管理、失败恢复等问题触及有限。

第三代：Harness Engineering（2026）

核心问题：模型在什么系统里干活，如何确保它真的把活干成？

Harness Engineering 不仅管模型看到什么，还管模型能用什么工具、拥有什么权限、怎么保持跨会话状态、必须通过什么验证、产生什么日志、失败了怎么重试、什么时候该暂停等人介入。

三者之间是清晰的包含关系：

1

Harness Engineering ⊃ Context Engineering ⊃ Prompt Engineering

用一个驾驶类比来说：Prompt 是一句"右转"的语音指令；Context 是给驾驶员一张地图，让它理解右转意味着什么；而 Harness 是整辆车——方向盘、刹车、车道边界、仪表盘、安全气囊、维护计划，以及确保车辆不会在高速公路上失控的所有工程设计。

Anthropic 在 2026 年 3 月的工程博客中直接挑明了一个判断：Prompt 和 Context 层面的优化都能显著提升效果，但都会碰到天花板。前沿的性能差异越来越落在 harness design 上。

为什么偏偏是 2026 年？

Harness Engineering 作为一个显式概念在 2026 年初集中爆发，并非偶然，背后至少有四个结构性因素在同时发力。

第一，模型能力越过了"够用"的临界点，系统设计成为主要瓶颈。

2025 年到 2026 年初，Claude Opus 4.5、GPT-5、Gemini 2.5 等模型相继发布。单论推理能力，这些模型在大多数孤立任务上已经表现优秀。但当你试图让它们完成一个需要数十步、跨多个会话、涉及外部工具调用的真实生产任务时，失败率仍然惊人。Anthropic 给出了一个具体的描述：即使是 Opus 4.5，在收到"构建一个完整的 Web 应用"这样的高层级指令时，如果不配备系统化的 harness，它要么试图一口气完成所有事情导致上下文耗尽，要么在下一个 session 中看到一部分进展就提前宣布完成而跳过验证。这类问题换一个更强的模型并不会自动消失——它们是系统层面的问题，需要系统层面的解决方案。

第二，串联衰减让"每一步都还行"变成了"整体不可用"。

这里有一个被广泛引用的数学直觉：假设一个多步 Agent 流水线中每一步的成功率是 95%——听起来很高。但如果串联 20 步，端到端的任务完成率只剩下 0.95²⁰ ≈ 36%。

这就是为什么团队经常报告"Agent 95% 的时间都在正常工作"，但真实任务的失败率却接近三分之一。这个问题不是靠更聪明的模型能解决的，必须靠系统层面的验证、重试、检查点机制来应对——而这些恰恰是 harness 的核心职责。

第三，模型正在商品化，harness 成为新的差异化因素。

GPT 系列、Claude 系列、Gemini 系列在核心能力上的差距正在缩小。当模型本身不再是竞争壁垒时，围绕模型的系统设计——也就是 harness——就成了新的护城河。这个趋势类似于云计算早期：当计算资源本身变成商品，AWS 之所以领先不是因为它的服务器更快，而是因为它构建了更好的编排、监控和管理系统。

第四，Agent 从 demo 走向生产，工程实践倒逼方法论。

2025 年的 Agent 大多停留在演示阶段——跑一个令人印象深刻的 demo，然后在真实场景中悄悄失败。到了 2026 年初，越来越多的团队开始认真地把 Agent 推向生产环境。生产环境对可靠性、可观测性、失败恢复的要求远高于 demo，这些需求天然指向了 harness 层面的工程投入。Devin（Cognition 的自主编程 Agent）在 harness 达到生产就绪之前，经历了六个月、五次完整的架构重写——没有人是一次就做对的。

关键时间线

这个概念的浮现并非一蹴而就，而是实践先行、命名随后、推广跟进：

2025 年 11 月，Anthropic 发布工程博客 Effective Harnesses for Long-Running Agents，将 Claude Agent SDK 定义为通用型 Agent Harness。这是"harness"一词在 Agent 工程语境中最早的正式使用之一。
2026 年 2 月 5 日，Anthropic 联合创始人在博客中写了一句被广泛引用的话：“每当你发现 Agent 犯了一个错误，就花时间工程化一个解决方案，让它永远不再犯同样的错。”
2026 年 2 月中旬，OpenAI 在官方博客发布了标题直接叫 Harness Engineering 的文章，正式把这个术语推到台前。
2026 年 3 月，Anthropic 发布了更新的工程博客，系统阐述了 harness design 的方法论演进。

所以本质上：Anthropic 是实践者，命名者，OpenAI 是推广者。

头部公司怎么做的？

概念层面讲清楚了，接下来看最硬核的部分：这些公司到底是怎么构建 harness 的？

Anthropic：从双 Agent 到三 Agent 架构

Anthropic 的实践集中体现在两篇工程博客中（2025 年 11 月和 2026 年 3 月），两篇文章之间能看到方法论的明显演进。

第一版：双 Agent 架构。 他们将长任务拆成两种角色——初始化 Agent 和编码 Agent。初始化 Agent 只在第一个 session 运行，负责搭建环境、创建脚手架、写入进度追踪文件，并且——这是关键——将用户的高层级指令扩展成数百条具体的、可测试的功能需求清单（JSON 格式）。编码 Agent 在后续 session 中逐个推进功能，每次启动先读取进度文件、审查功能清单、运行已有测试。

这里有一个重要的设计思想：外部制品成为 Agent 的记忆。 进度文件、Git 历史、结构化需求清单，这些都是跨 session 持久化的。每个 Agent session 在动手之前先从这些制品重建上下文。这本质上是用文件系统解决了 LLM 无状态的核心问题。

一个值得注意的技术细节：Anthropic 自己透露，这两个 Agent 其实共享相同的系统提示和工具集，区别仅在于初始用户提示不同。换句话说，仅通过 prompt 差异就能在同一个 harness 内创造专门化行为。

第二版：三 Agent 架构（Planner-Generator-Evaluator）。 Planner 负责需求扩展和任务规划，Generator 负责代码实现，Evaluator 负责用 Playwright 等工具做交互式验证和打分。

这个演进中最关键的发现是评估器分离。Anthropic 发现，当你让模型评估自己的工作时，它会倾向于自信地表扬自己——即使在人类看来质量明显平庸。这不是某个特定模型的问题，而是自评估的系统性缺陷。他们的结论是：工程化一个独立的、严格的评估器 Agent，远比教会生成器 Agent 自我批评要容易得多。

另一个重要发现与模型迭代有关：早期 harness 基于 Sonnet 4.5 设计，该模型有明显的"上下文焦虑"倾向——随着上下文增长，模型行为会变得不稳定。因此 harness 设计了上下文重置机制。但换成 Opus 4.5 后，模型自行消除了这一行为，上下文重置机制反而变成了多余的复杂度。

这说明一个重要原则：Harness 不是越复杂越好，它必须与模型当前的能力边界相匹配。模型变强了，某些 harness 模块反而应该撤掉。

OpenAI：Codex 团队的百万行实验

OpenAI 的案例更具传播力，因为他们给出了非常具体的数字。

一个起初只有三人、后来扩展到七人的工程团队，用 GPT-5 驱动的 Codex Agent，在大约五个月里生成了约一百万行代码，合并了约 1500 个 PR，构建了一个有内部日活用户的生产级产品。团队人均日吞吐量约 3.5 个 PR，而且随着团队扩大，吞吐量反而上升了。

他们甚至给自己加了一个极端约束：零手写代码。 所有应用逻辑、测试、CI、文档、可观测性、内部工具全部由 Codex 生成。他们坦诚构建速度大约是手写的十分之一，但认为这是一种可接受的权衡——目的是验证 Agent 驱动开发的极限在哪里。

Martin Fowler 网站上的技术分析将 OpenAI 的 harness 方法论归纳为三大支柱：

Context Engineering：持续增强代码库中的知识文档（如 AGENTS.md），加上 Agent 对可观测性数据和浏览器的动态访问。
架构约束：不靠 Agent 自觉遵守，而是用确定性的自定义 linter 和结构测试来强制执行——这是硬性规则，不依赖 LLM 的判断。
垃圾回收：定期运行后台 Agent 扫描不一致和架构违规，对抗系统的熵增。

OpenAI 团队还发现了一个值得铭记的核心模式：当 Agent 遇到困难时，不要让它更努力地尝试，而是评估它缺少什么能力，把这个能力以可读、可执行的形式提供给它，然后让 Agent 自己编写修复代码。 这形成了一个 harness 自我改进的闭环。

不过，必须加一个诚实度提醒。OpenAI 在呈现这个案例时存在明显的利益关联——他们希望说服市场相信 AI 可以承担大规模代码维护。而且有分析者指出，这篇文章标题虽然叫 Harness Engineering，但正文中 “harness” 一词只出现了一次，标题很可能是后来受到 Anthropic 概念的启发才加上去的。

Google DeepMind：独立收敛到同一模式

Google DeepMind 没有像前两家那样发布专门的 harness 方法论文章，但他们用产品说话。

2026 年 2 月发布的 Elythia 是一个面向数学研究的自主 Agent，核心架构是三组件的 Agent harness：Generator 负责提出候选解法和证明策略，Verifier 用自然语言检查逻辑缺陷和幻觉，Revisor 负责修正验证器发现的错误。三个组件循环迭代，直到输出通过验证。

注意这里的结构：Generator → Verifier → Revisor，与 Anthropic 的 Planner → Generator → Evaluator 高度对应。两家公司独立走到了同一个设计模式——这不是巧合，这说明生成-评估分离正在成为 Agent harness 设计的行业共识。这个模式的灵感可以追溯到 GAN（生成对抗网络）的对抗训练思想，但在 Agent 系统中被重新发现并赋予了新的工程意义。

Google 在工具层面也有布局：Agent Development Kit（ADK）作为开源框架，内置了 evaluation harness 做场景驱动测试。2026 年 3 月发布的 ADK Python 2.0 Alpha 还加入了基于图的工作流编排能力。

另一个值得关注的技术细节：Gemini 2.5 引入了一个叫 thinking signatures 的机制——模型在调用工具之前生成一个加密的推理状态表示，传回对话历史后可以恢复精确的推理链路。这本质上是在模型层面解决跨步骤的状态持久性问题。Anthropic 用 harness 层面的外部制品（进度文件、Git 历史）保持记忆，Google 则尝试在模型内部解决同样的问题——两条技术路线的有效性值得持续观察。

一个反直觉的案例：Voxel 的"工具减法"

除了三大巨头，Voxel 提供了一个完全反直觉的经验。

他们最初给 Agent 配备了一个非常全面的工具库——搜索、文件操作、API 调用、代码分析，应有尽有。结果效果很差：Agent 变得困惑，进行冗余调用，执行不必要的步骤。然后 Voxel 做了一件看似倒退的事：移除了 80% 的工具。

结果反而获得了全面提升——更少的步骤、更少的 token 消耗、更快的响应、更高的成功率。

这个案例揭示了一个深层原则：约束 Agent 的解决空间反而能提升它的表现。 这与传统软件工程中"给工程师更多工具和自由度"的理念完全相反。对于概率性推理系统来说，更多选择意味着更大的决策空间，而更大的决策空间意味着更高的出错概率。精心策划的工具集（curated toolset）比大而全的工具库更有效。

Stripe 的实践也佐证了这一点：他们的 Agent 运行在隔离的、预热好的沙箱环境里，通过 MCP 协议访问超过 400 个内部工具——但这些工具经过了严格的权限分级和场景适配，而非全部平铺给 Agent。

一个成熟 Harness 的六大模块

综合以上公司的实践，一个生产级的 Agent harness 通常包含六个核心模块：

1. 上下文工程与知识管理

这是 harness 的基础层，负责确保 Agent 在每个执行步骤中都能访问到正确的信息。

包括：项目指令文件（如 CLAUDE.md、AGENTS.md，Agent 启动时自动读取）、动态上下文注入（从日志、监控指标中获取实时信息）、上下文隔离（用子 Agent 作为"上下文防火墙"，让不同子任务在各自的上下文窗口中运行）、上下文压缩（随着窗口被填满，自动摘要或丢弃无关信息）。

OpenAI 有一个精辟的观察：从 Agent 的视角看，它在运行时无法访问的任何东西都等同于不存在。 所以越来越多的知识需要被显式地推送到代码库内部，成为版本化的、Agent 可读的制品。

2. 工具编排与权限设计

Voxel 的经验已经说明，工具不是越多越好。成熟的 harness 需要精心策划工具集、移除冗余选项、设计清晰的权限边界。

具体包括：MCP（Model Context Protocol）协议集成实现工具标准化、文件系统的读写权限分级、网络访问的白名单控制、沙箱隔离确保 Agent 不会意外影响生产环境。一个好的工具编排层应该让 Agent 只看到它当前任务需要的工具，而非所有可用工具。

3. 验证机制与约束执行

这是 harness 区别于简单 scaffold（脚手架）的核心特征。

两种约束类型需要协同工作：确定性约束——自定义 linter、结构测试、pre-commit hooks，这些不依赖 LLM 判断，Agent 无法绕过；评估性约束——独立的评估器 Agent，用 Playwright 等工具做交互式验证和打分。

Anthropic 已经用实验证明了为什么需要这两层：确定性约束兜底确保"不可接受的事情绝对不会发生"，评估性约束则处理那些无法用硬规则覆盖的质量判断。

4. 状态管理与记忆持久性

大语言模型是无状态的——每个新 session 从零开始。这是长任务场景中最核心的工程挑战。

解决方案是外部化记忆：进度追踪文件记录"做到哪了"、结构化功能清单定义"还剩什么要做"、增量 Git 提交提供"做了什么"的完整审计链、检查点机制支持失败后从最近的成功状态恢复。

这里有一个有趣的类比：这套机制本质上就是操作系统中进程管理的变体——上下文保存与恢复、持久化存储、崩溃恢复。只不过被管理的"进程"是一个概率性的推理系统，而非确定性的程序。

5. 可观测性与反馈闭环

包括：执行追踪（每一步做了什么、用了什么工具、消耗了多少 token）、质量分级（输出结果的自动评分）、异常检测（识别 Agent 进入循环、产生幻觉等异常模式）。

最关键的是反馈归因：把 Agent 在生产中的失败模式追溯到 harness 的具体缺陷，驱动持续改进。OpenAI 的"垃圾回收"机制（定期用后台 Agent 扫描不一致和架构违规）就是这个模块的一种实现。

6. 人类接管与生命周期管理

在关键决策点暂停执行——要删数据库？要扣费？要发客户邮件？必须让人类确认。

还包括：升级路径（Agent 无法解决时如何优雅地交还控制权）、失败重试策略、完整的生命周期钩子（启动前检查、执行中监控、完成后清理）。这个模块的设计原则是：Agent 的自主性应该与任务的可逆性成正比。 可逆操作（如编辑代码）可以高度自主；不可逆操作（如部署到生产、发送外部通知）必须有人类审批环节。

新瓶装旧酒？一个诚实的定位

讲到这里，可能有人想问：这不就是换了个名字的软件工程吗？

坦率地说，Harness Engineering 里确实有很大一部分不是新发明。Test harness 在软件工程中已有几十年历史；CI/CD 流水线、linter、pre-commit hooks 是成熟的 DevOps 实践；任务分解与编排在分布式系统中早就被充分研究；沙箱隔离是安全工程的基础概念；可观测性在 SRE 领域已经高度成熟。

如果有人说 Harness Engineering 全是新东西，那是在夸大。但如果有人说它纯粹是旧酒，那也不准确。

它在几个维度上确实产生了新的方法论贡献：

约束对象发生了根本变化。 传统软件工程约束的是确定性代码执行——给定相同输入，程序总是产生相同输出。而 Harness Engineering 约束的是概率性推理系统——相同的 prompt 可能产生不同的输出，模型可能产生幻觉，可能在多步推理中逐渐偏离。这要求在验证、重试、恢复等方面采用根本不同的设计策略。

“约束即提升"的反直觉原则。 Voxel 的案例证明，约束 Agent 的解决空间——减少工具、限定模式、强制架构边界——反而提升了它的生产力和可靠性。传统工程思维倾向于给工程师更多工具和自由度，但对概率性推理系统，逻辑恰好相反。

代码库本身成为 harness 的一部分。 代码结构、命名约定、模块边界，不仅服务于人类可读性，更服务于 Agent 的"可推理性”。OpenAI 的 Codex 代码库甚至首先为 Agent 的可读性优化，而非人类的阅读偏好。这是一个全新的代码设计维度。

我个人认为最准确的定位是：Harness Engineering 类似于 DevOps。 DevOps 也不是发明了全新的技术，而是在持续交付的压力下，将开发、测试、运维等多个成熟领域的实践重新组合，形成了统一的方法论。Harness Engineering 正在做类似的事——在 Agent 生产化的压力下，将系统设计、测试工程、可观测性等成熟实践重新组合，并补充针对概率性推理系统的新模式。这种重组本身就是有价值的创新。

风险与清醒认知

最后聊聊风险。任何新概念在上升期都容易被过度包装，Harness Engineering 也不例外。

概念膨胀。 当一个术语从一个 agent.md 文件到完整的生产运维系统都能涵盖时，它的精确性就会被稀释。“Harness Engineering"正在变成一个什么都能往里装的筐，这对概念的长期生命力是危险的。

过度工程化。 Anthropic 自己的经验已经证明了这一点：Opus 4.5 自行消除了 Sonnet 4.5 的上下文焦虑行为，harness 中的上下文重置机制随之变成了多余的复杂度。随着模型快速进步，今天精心设计的 harness 模块明天可能就成了不必要的包袱。OpenAI 也强调 harness 必须是"可撕裂的”（tearable）——能够随时移除不再需要的模块。

证据基础偏弱。 这是我认为最需要警惕的问题。目前支持 Harness Engineering 价值的大多数证据来自 AI 工具厂商自身——OpenAI 报告 Codex 有多厉害、Anthropic 报告 Claude Agent SDK 改进了多少。这些来源都存在利益冲突。独立的、定量的、可复现的 benchmark 验证目前仍然缺乏。Anthropic 自己都在文章中承认，他们的案例缺少"显著的定量成功指标"。

可复现性存疑。 OpenAI 的百万行代码案例是在极其特定的条件下完成的：从空仓库开始、用自家的 Codex 工具、团队本身就是 AI 系统专家。这个经验对普通工程团队的可复现性完全没有被验证过。

Harness 也是风险放大器。 Anthropic 在 biosafety 评测中发现了一个令人警醒的数据：单 Agent 配置下非预期解法的发生率是 0.24%，多 Agent 配置下上升到 0.87%。更强的 harness 并不一定改变模型想走捷径的倾向，但因为更高的 token 使用量和更多并行搜索路径，反而提高了意外行为的概率。Harness 不只是性能放大器，也可能是风险放大器。

给 Agent 开发者的行动路径

与其纠结于概念定义，不如从务实的角度看看现在能做什么。

立即能做： 在项目根目录创建一个 AGENTS.md（或 CLAUDE.md），把 Agent 的工作约束写进去。每次 Agent 犯重复性错误，就在文件中加一条规则。这是最小化的 harness，成本几乎为零，效果立竿见影。

中期投入： 构建确定性验证层。自定义 linter 检查 Agent 输出的代码结构、pre-commit hooks 拦截明显的质量问题、结构测试验证架构约束没有被破坏。再加上基本的可观测性——至少记录每次 Agent 执行的步骤数、token 消耗和成功/失败状态。

长期方向： 设计模块化的、可替换的 harness 架构。每个模块应该能独立启用或禁用，支持模型升级时平滑迁移。记住 Anthropic 的教训：今天为弱模型设计的补偿机制，明天可能因为模型变强而需要拆除。

引用 OpenAI Codex 团队工程师的一句话来结尾：

Agent 不难，harness 才难。

当模型能力不再是瓶颈，你为模型搭建的运行系统，就是你真正的竞争力。