HARNESS ENGINEERING · 中文导读

Harness Engineering 入门导读

walkinglabs · 12.3K⭐ · 14 讲 + 8 项目 · 有官方中文版

一句话：这门课讲的不是「怎么让 AI 更聪明」，而是「怎么让最聪明的 AI 变得靠谱」。模型权重之外的一切工程基础设施——指令、工具、环境、状态、反馈——决定了模型能力能被发挥多少。

🎯 先记住一个核心结论

「同一匹马，两种命运」

Anthropic 做过一个对照实验：同一个模型 Opus 4.5，同一个任务「做 2D 复古游戏编辑器」。裸跑 20 分钟花 $9，功能跑不起来；配上完整 harness（planner/generator/evaluator 三 agent）6 小时花 $200，游戏正常游玩。模型没换，换的是「马具」。

🧩 Harness 到底是什么

一个 prompt 文件不是 harness。Harness 由五个子系统组成，每个都有明确职责：

📋 指令

AGENTS.md 等结构化指令文件，约束行为

🔧 工具

shell、测试、lint 等 agent 能调用的能力

🌍 环境

隔离的执行环境、依赖、目录组织

💾 状态

跨会话的进度持久化与恢复

🔄 反馈

测试结果、验证命令，让 agent 知道自己对不对

✅ 完成定义

可验证的「做完」标准，否则 agent 自己编一个

📚 14 讲内容拆解

第 1 讲 · 模型能力强，不等于执行可靠

SWE-bench 50-60% 通过率是「精选任务」，真实需求更低。失败模式就那么几种：需求模糊、隐性约定没写、环境缺配置、无验证手段、跨会话状态丢失。

→ 核心名词：能力鸿沟、Harness 诱导失败、验证缺口、诊断循环

第 2 讲 · Harness 到底是什么

给出可操作定义。核心原则「仓库即规范」「给地图不给说明书」（AGENTS.md 100 行就够，拆到 docs/ 按需读）。

→ 五子系统模型 + 约束而非微操

第 3 讲 · 仓库必须成为记录系统

agent 看不到的东西对它不存在。所有必要上下文必须在仓库里，结构化呈现。

→ 单文件 vs 多文件的分层组织

第 4 讲 · 一个巨大指令文件会失败

指令越堆越多，agent 反而抓不住重点。要分层、要精简、要按需加载。

→ 指令的「地图化」而非「百科全书化」

第 5 讲 · 长任务为什么会失去连续性

超过 30 分钟的任务，失败率随状态丢失急剧上升。

→ 持久化进度，别让每个新会话重新探索

第 6 讲 · 初始化需要独立阶段

把「搞清楚项目是怎么回事」和「解决问题」分开，用 init 脚本统一环境检查。

→ 环境配置自动化，别让 agent 修环境

第 7 讲 · agent 为什么会过度又没做完

「上下文焦虑」：agent 感觉上下文快满了，会匆忙收尾、跳过验证。

→ 用功能清单约束范围

第 8 讲 · 功能清单是 harness 原语

feature_list.json 把「做什么」结构化，agent 逐项执行、逐项勾掉。

→ 范围管理的基础设施

第 9 讲 · agent 为什么过早宣告胜利

最最常见的失败模式：agent 说「做完了」但没做完。

→ 把「干活的人」和「检查的人」分开

第 10 讲 · 端到端测试改变结果

有测试和没测试，agent 的表现天差地别。

→ 验证命令必须明确告诉 agent

第 11 讲 · 可观测性属于 harness 内部

日志、指标、追踪，让 agent 的运行过程可调试。

→ 不是事后加，而是内置

第 12 讲 · 每个会话留下干净状态

claude-progress.md 交接，下个会话接得上。

→ 显式恢复路径

第 13 讲 · Loop Engineering（循环工程）

把「按按钮」也交给系统。/goal 命令：给目标、验证方式、停止条件，agent 自己循环到达成。

→ 你的位置从循环里面移到外面

第 14 讲 · Graph Engineering（图工程）

单循环之后必然长出图：多个 agent、loop、工具、评估者如何协作。节点、边、共享状态、路由规则。

→ 一旦需要专业化、并行、共享状态，就不再是 loop，是一张图

🚀 四层演进：Prompt → Context → Loop → Graph

阶段	塑造什么	回答的问题
Prompt	指令	怎么告诉模型做什么？
Context	信息	模型做决定前该知道什么？
Loop	运行时	怎么让模型自己循环到达成？
Graph	系统	多个 agent/loop/工具如何协作？

每层不是取代上一层，而是叠加。到了 graph，每个节点都带着自己的 prompt、context、loop——图决定的是节点之间怎么连。

🛠️ 8 个项目（动手实践）

P01

裸跑 vs 最小 harness

提示词 vs 规则驱动，量化差距

P02

Agent 可读工作区

搭一个 agent 能读懂的仓库

P03

多会话连续性

状态持久化，跨会话接得上

P04

增量索引

让 agent 按需加载上下文

P05

基于验证的 QA

可验证的完成定义

P06

运行时可观测

日志、调试

P07

第一个自动循环

/goal 式 loop

P08

第一张图

多 agent 协作

📖 建议学习路径

新手建议：先看第 1、2 讲建立框架 → 做 P01 亲手感受「裸跑 vs harness」的差距 → 再按 3-12 讲逐步搭自己的 harness → 最后学 13、14 讲的 loop/graph 进阶。

什么时候真需要它：如果你只是「用 AI 干活」（Hermes/Claude Code 现成的），不用自己造 harness。如果你要「让 AI 可靠地完成真实工程任务」——比如让 agent 自主开发、修 bug、跑测试——这门课是必修。

🔗 资源

GitHub 仓库

walkinglabs/learn-harness-engineering · 12.3K⭐

中文 README

docs-readme/zh-CN/README.md

中文模板

AGENTS.md、feature_list.json 可直接复制

前沿 Harness 拆解

逐层拆 Pi / Claude Code / Codex / DeepSeek 的真实设计