这是 Learn Harness Engineering 第一讲的学习笔记。
第一讲的题目很直接：模型能力强，不等于执行可靠。
这句话看起来像常识，但它其实是使用 AI coding agent 时最容易被忽略的判断。
很多人遇到 agent 做砸了，第一反应是换模型：是不是这个模型不够聪明？是不是该换更贵的？是不是上下文窗口还不够大？
第一讲提醒我们：先别急。
Agent 在真实仓库里失败，很多时候不是模型不会，而是模型外面的工作系统没有搭好。这个工作系统，就是课程里反复讲的 harness。
能力只是潜力，可靠性是结果
一个模型在 benchmark 上表现强，不代表它在你的项目里就能稳定完成任务。
Benchmark 里的任务通常更干净：问题描述清楚，有现成测试，代码范围相对明确。真实项目不是这样。
真实项目里，需求常常一句话带过：加个搜索、改个导入、补个权限。业务规则可能藏在旧代码里、团队习惯里、文档角落里，甚至只存在于某个人脑子里。测试可能不完整，启动命令可能没人维护，环境配置可能只在某台机器上跑得通。
这时候，模型能力只是潜力。它能不能把潜力变成可靠执行，取决于它看到了什么、能调用什么、失败后能得到什么反馈、下一次会话能不能接住上一次状态。
所以，模型能力和执行可靠性不是一回事。
同一个模型，结果可以完全不同
第一讲里举了一个很典型的对照：同一个模型，同一个需求，如果裸跑，结果可能是核心功能不可用；如果配上 planner、generator、evaluator 这样的完整 harness，结果就可能变成可运行的软件。
模型没有变。
变的是模型外面的系统：有人负责规划，有人负责实现，有人负责评估，有明确的任务边界，有运行反馈，有验收标准。
这就是 harness 的意义。
它不是一个漂亮术语，而是模型权重之外的一切工程基础设施：指令、工具、环境、状态管理、验证反馈。
如果把模型看成发动机，harness 就是车架、传动、刹车、仪表盘、道路规则和维修流程。发动机再强，没有这些东西，也不能稳定把人送到目的地。
Agent 失败，通常卡在五层
第一讲最有用的部分，是把 agent 失败拆成了几类可诊断的问题。
我把它理解成五层排查表。
第一层是任务规范。
你说“加个搜索功能”，agent 只能猜。搜索什么？怎么排序？要不要分页？要不要高亮？权限怎么处理？如果这些都没写清楚，agent 不是在执行需求，而是在替你补需求。
第二层是上下文供给。
项目里的隐性约定如果没有写进仓库，agent 就看不到。比如团队已经统一使用某个错误处理模式、某个 ORM 版本、某种 API 分层方式，但这些只存在于人的记忆里，agent 自然会写偏。
第三层是执行环境。
如果项目启动不了、依赖装不上、测试命令缺失，agent 会把大量上下文和时间浪费在环境故障上。它不是不想做业务任务，而是连工作台都没搭起来。
第四层是验证反馈。
没有测试、没有 lint、没有类型检查、没有端到端验证，agent 就只能靠自己判断“看起来差不多了”。这就是最常见的提前宣布完成。
第五层是状态管理。
长任务不可能永远在一个会话里完成。上次做到哪里、为什么这么做、还差什么、哪些验证通过了，如果没有持久化记录，新会话就要重新探索。
这五层里任何一层断了，都会让强模型表现得像弱模型。
最常见的误判：模型不行
第一讲给我的最大提醒是：不要把所有失败都归因成“模型不行”。
“模型不行”这个判断太粗了。它既不可操作，也很贵。你换一个更强模型，可能只是让同一个坏 harness 跑得更快、更贵。
更好的问题是：这次失败具体是哪一层出了问题？
这样问，失败就变成了可修复的工程问题。
如果是任务规范问题，就把需求写成验收标准。
如果是上下文问题，就把项目约定写进 AGENTS.md 或架构文档。
如果是环境问题，就补初始化脚本。
如果是验证问题，就明确测试、类型检查和端到端流程。
如果是状态问题，就补进度文件和会话交接。
完成定义不能交给 agent 自己编
第一讲里还有一个很关键的概念：Definition of Done。
也就是“什么叫做完成”。
对 agent 来说，完成定义不能是“我觉得写完了”。它必须是一组可以执行、可以验证的条件。
比如不要只说：
“帮我加一个用户偏好设置接口。”
更好的说法是：
完成标准： - 新增 GET /api/v2/users/preferences - 新增 PUT /api/v2/users/preferences - 沿用现有错误处理模式 - 新增 API 测试 - pytest tests/api/v2/ 通过 - 类型检查通过
这类完成定义的价值在于，它把 agent 的“主观信心”替换成了“外部证据”。
Agent 可以很自信地说完成了，但测试不会因为它自信就变绿。
AGENTS.md 可能比换模型更有效
第一讲里有一句我觉得特别实用：一个 AGENTS.md 文件可能比换一个更贵的模型更有效。
这句话不是说模型不重要，而是说在很多真实项目里，瓶颈不是推理能力，而是工作条件。
一个最小可用的 AGENTS.md 至少应该告诉 agent：
这些信息对人类开发者来说可能是“常识”，但对 agent 来说，如果没写下来，就等于不存在。
把失败变成诊断循环
第一讲最后给的工作方式，是把每次失败都当成 harness 的诊断信号。
不要停在“agent 又犯错了”。
而是记录：
这次失败发生在哪一层？
是任务没写清楚，还是上下文没给够？是环境坏了，还是验证缺失？是状态没交接，还是完成定义太模糊？
然后修那一层。
下一次再跑。
几轮之后，你会得到一个越来越强的工作系统。它不是靠一次神奇提示词变强，而是靠每次失败后把缺陷沉淀成规则、脚本、文档和验证。
这才是 Harness Engineering 的工程味道。
我的理解
第一讲真正想建立的不是某个技巧，而是一种默认判断：
当 agent 失败时，先怀疑 harness，而不是先怀疑模型。
模型能力当然重要。但在真实仓库里，强模型只是起点。可靠执行来自一整套工作系统：清楚的任务、可见的上下文、稳定的环境、可执行的验证、可恢复的状态。
如果这些都没有，换模型只是换一台更贵的发动机，车还是没有刹车、仪表盘和路标。
所以这节课最值得带走的行动建议很简单：
下次 agent 做砸了，不要先说“模型不行”。
先问五个问题：
任务说清楚了吗？
上下文给够了吗？
环境跑通了吗？
验证明确了吗？
状态留下了吗？
这五个问题，比“换哪个模型”更接近真正的工程解法。
参考链接
- • Learn Harness Engineering 第一讲：https://walkinglabs.github.io/learn-harness-engineering/zh/lectures/lecture-01-why-capable-agents-still-fail/
- • 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
- • SWE-bench：https://www.swebench.com/
