这是 Learn Harness Engineering 第二讲的学习笔记。
第一讲讲的是一个基本判断：模型能力强，不等于执行可靠。
第二讲往前走了一步：如果可靠性不只来自模型，那模型外面的东西到底是什么？
课程给了一个很直接的答案：那套东西就是 harness。
但这里最重要的一句话不是“我们要有 harness”，而是：一个 prompt 文件不是 harness。
这句话很关键。因为现在很多人一说给 agent 搭 harness，实际做的事情只是写一个 AGENTS.md、CLAUDE.md 或 .cursorrules。这些文件当然重要，但它们只是 harness 里的一个子系统，不是全部。
第二讲真正想建立的是一套可操作的定义：
Harness = 指令 + 工具 + 环境 + 状态 + 反馈。
只有把这五个子系统放在一起看，agent 为什么稳定、为什么失败、为什么同一个模型在不同仓库里表现差很多，才会变得可诊断。
Prompt 文件为什么不够
课程开头用了一个类比。
想象你是一个刚入职的工程师，被丢进一个完全没有文档的项目里。没有 README，代码没有注释，没人告诉你怎么跑测试，CI 配置藏在某个角落。
你能写代码吗？也许能。
但你会把大量时间花在“这个项目到底怎么回事”上，而不是“解决真正的问题”上。
AI agent 的处境更难。人至少可以问同事，agent 只能看到你放到它面前的文件，以及它被允许执行的命令。
这就是为什么只写一个很长的 prompt 不够。Prompt 可以告诉 agent “请认真”“请遵守项目规范”“请先跑测试”，但如果仓库里没有测试命令、环境跑不起来、状态没有记录、失败结果没有反馈回来，agent 仍然无法可靠工作。
Prompt 文件解决的是“指令”问题，不解决全部工程问题。
这一节可以拆成三个判断：
所以第二讲给 harness 下的定义，不是一个抽象概念，而是一个可以拿来审计自己项目的框架。
仓库是事实来源
第二讲里引用了 OpenAI 对 harness engineering 的一个核心表述：仓库就是规范，或者说仓库是系统记录。
这句话翻译成日常开发语言就是：agent 看不到的东西，对它来说就不存在。
对 agent 来说，真正稳定的上下文应该在仓库里：
团队约定如果只在人的脑子里，agent 看不到。
部署方式如果只在 Slack、飞书、Confluence 里，agent 看不到。
测试命令如果只靠老员工口口相传，agent 看不到。
上一次会话为什么这么改、还差什么、哪里被阻塞，如果没有写进仓库，下一次会话也看不到。
所以 harness engineering 的第一层工作，就是把必要上下文沉淀到仓库里。不是把所有东西都堆进一个巨大的说明书，而是用结构化文件、清晰目录、明确验证命令，让 agent 能按需读取。
这里有一个很实用的判断：AGENTS.md 或 CLAUDE.md 应该更像目录页，而不是百科全书。
100 行左右通常就够了。放不下的细节，应该拆到 docs/ 里，让入口文件负责指路，而不是负责承载全部知识。
五个子系统
第二讲把 harness 拆成五个子系统：指令、工具、环境、状态、反馈。
五个子系统各自回答一个问题：
第一，指令子系统。
它的典型载体是 AGENTS.md、CLAUDE.md、.cursorrules。这里应该写项目目的、技术栈、版本、首次运行命令、硬约束，以及更详细文档的链接。
指令子系统的目标不是把 agent 每一步都管死，而是给它一张地图。告诉它这个仓库是什么，边界在哪里，遇到具体问题应该去哪里找资料。
第二，工具子系统。
Agent 和普通聊天模型的关键差别，是它能行动。它需要读文件、搜代码、改文件、跑命令、执行测试、访问浏览器或调用 API。
这里的平衡点是最小权限，而不是零权限。为了安全把 shell 全禁掉，agent 连依赖都装不了，测试都跑不了，那它就只能靠猜。反过来，什么权限都开放也不合理。好的 harness 要明确哪些工具可以用，哪些操作必须确认，哪些边界不能越过。
第三，环境子系统。
真实项目里，环境问题经常比代码问题更消耗 agent。包管理器用 npm 还是 yarn？Node 版本是多少？Python 版本是多少？依赖怎么锁？服务怎么启动？测试需要数据库吗？
如果这些没有写清楚，agent 很容易把时间浪费在环境探索上。
环境子系统的目标是让环境自描述、可复现。比如用 package.json、pyproject.toml 锁依赖，用 .nvmrc、.python-version 指定运行时，用 Docker 或 devcontainer 固化开发环境。
第四，状态子系统。
长任务不可能永远在一个会话里完成。上一轮做了什么，为什么这么做，还剩什么，哪些方案试过失败了，如果没有状态记录，下一轮就要重新探索。
第二讲建议用简单的 PROGRESS.md 记录完成项、进行中、阻塞项。它不一定复杂，但必须稳定更新。每次会话结束前写入，每次新会话开始时读取。
第五，反馈子系统。
这是第二讲最强调投入产出比的部分。
反馈子系统就是明确告诉 agent：什么叫做做对了。
比如：
验证命令： - 测试：pytest tests/ -x - 类型检查：mypy src/ --strict - Lint：ruff check src/ - 完整验证：make check
没有反馈，agent 就只能靠“看起来差不多了”判断完成。
有反馈，agent 才能把失败结果重新纳入下一轮行动。
这也是为什么很多仓库最值得先补的不是更长的 prompt，而是清晰的验证命令。
反馈通常最划算
第二讲有一个很实际的判断：五个子系统里，反馈子系统通常投入最少、回报最高。
原因很简单。
指令、工具、环境、状态都重要，但它们的改造可能需要更多设计。反馈命令往往可以先补。
你可以先不重构整个文档体系，也可以先不设计复杂的状态机，但至少要告诉 agent：改完以后跑什么命令，什么结果算通过，失败时应该看哪里。
这件事对 agent 的行为影响非常大。
反馈子系统最值得先补，因为它直接改变完成判断：
- • 完成由外部证据确认，而不是由 agent 自评。
没有验证命令时，agent 会倾向于提前宣布完成。它会说“我已经实现了”，但这只是主观判断。
有验证命令时，完成不再由 agent 自己宣布，而由外部证据确认。
这和第一讲的 Definition of Done 是同一条线：可靠性来自可执行证据，不来自语言上的自信。
不要凭感觉判断哪个组件最有用
第二讲还讲了一个方法：控制变量排除法。
保持模型不变，任务不变，然后逐个移除 harness 子系统，看哪个移除后性能下降最多。
比如：
这个方法的价值在于，它逼你停止凭感觉讨论。
你可能以为最重要的是更完整的文档，结果发现没有验证命令时成功率掉得最多。
你可能以为状态文件没用，结果长任务一跨会话就崩。
不过课程也提醒了一个边界：移除实验只能告诉你“当前任务里哪个组件边际贡献最大”，不能单独证明“真正瓶颈在哪里”。
要定位瓶颈，还要看失败记录和归因。
任务是不是没说清楚？上下文是不是不足？环境是不是不可复现？验证反馈是不是缺失？状态管理是不是断裂？
没有这一步，只看性能下降，很容易得出过度简化的结论。
一个团队的案例
第二讲里有一个团队案例，很适合说明 harness 的价值。
一个团队用 GPT-4o 开发一个 TypeScript + React 前端应用，大约 2 万行代码。他们不是换模型，而是逐步补 harness。
第一阶段，只有 README 里的基本项目描述。5 次运行成功 1 次，成功率大约 20%。主要问题是选错包管理器、没有遵循组件命名约定、跑不了测试。
第二阶段，加入 AGENTS.md，写清技术栈版本、命名约定、关键架构决策。成功率升到 60%。
第三阶段，在 AGENTS.md 里列出验证命令：yarn test && yarn lint && yarn build。成功率升到 80%。
第四阶段，引入进度文件模板，让 agent 每次运行都记录完成和未完成的工作。成功率稳定到 80% 到 100%。
模型没有变。
变化的是模型周围的工程系统。
这个案例把第二讲的观点讲得很清楚：agent 的能力不是只由模型决定，也由它所处的工作环境决定。
我对第二课的理解
第二课最有价值的地方，是把“harness”这个容易被讲虚的词，拆成了可以审计的五个问题。
你的项目有没有清晰指令？
Agent 有没有足够但不过度的工具权限？
环境能不能稳定复现？
长任务有没有状态记录？
完成有没有外部反馈？
这五个问题比“我是不是该换一个更强模型”更具体，也更可操作。
如果只能从第二课带走一个行动建议，我会选这个：
先补反馈子系统。
把验证命令写清楚，把完成标准写清楚，把失败结果交还给 agent。
因为这是最便宜、最快能看到效果的 harness 改进。
然后再补指令入口、环境说明、状态文件和工具边界。
不要把 harness 学成一套复杂仪式。它本质上是为了减少混乱，让 agent 更少猜测，更多依据外部证据行动。
给自己项目的检查表
读完第二课，可以直接拿这张检查表看自己的仓库。
- • 有没有一个短而清晰的
AGENTS.md 或 CLAUDE.md？ - • 长任务有没有
PROGRESS.md 或类似状态记录？ - • 完成标准是否来自测试、lint、build、E2E，而不是 agent 自己说完成？
- • 如果 agent 失败，能不能从日志或失败记录里归因？
这些问题不需要一次全部解决。
先找最低分的那个子系统，花 30 分钟补一点，再观察 agent 表现变化。
这就是第二讲给我的核心启发：Harness Engineering 不是一次性搭一个巨大系统，而是持续减少 agent 工作时的不确定性。
参考链接
- • Learn Harness Engineering 第二讲：https://walkinglabs.github.io/learn-harness-engineering/zh/lectures/lecture-02-what-a-harness-actually-is/
- • OpenAI: Harness Engineering：https://openai.com/index/harness-engineering/
- • Anthropic: Effective Harnesses for Long-Running Agents：https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents
- • HumanLayer: Harness Engineering for Coding Agents：https://humanlayer.dev/articles/harness-engineering-for-coding-agents/
- • SWE-agent: Agent-Computer Interfaces：https://github.com/princeton-nlp/SWE-agent
- • Thoughtworks: Harness Engineering on Technology Radar：https://www.thoughtworks.com/radar
