Harness Engineering 深度教案
—— 为 Coding Agent 搭建一套可工程化、可复制、可观察的工作环境
"最强的模型，搭配错的环境，依然会在真实工程任务中翻车。这不是模型问题——这是 harness 问题。"
问题不是"模型能不能写代码"——能写。问题是：能不能在真实的仓库里，跨越多次会话，不需要人一直盯着，就可靠地完成真实的工程任务？现在的答案是：没有 harness 就不行。这门课的全部内容，都在系统化地回答"如何搭建那个让答案变成'行'的 harness"。
这是一门项目制课程，不是论文综述。它把当下业界最前沿的两份关键文档——OpenAI 的 Harness Engineering 与 Anthropic 的 Effective Harnesses for Long-Running Agents——拆成 12 个可教学的概念单元，再用 6 个围绕同一个 Electron 知识库桌面应用渐进演化的项目，让学生在真实代码中亲手验证每一个机制。
模型决定写什么代码。
Harness 管控什么时候写、在哪里写、怎么写。
Harness 不让模型变聪明——它让模型变可靠。 — 课程核心命题
课程开篇就给出最有说服力的两个证据，这也是整门课的"起点性事实"：
"做一个 2D 复古游戏编辑器"。没有 harness：20 分钟 · $9 · 跑不通。有完整 harness（planner + generator + evaluator）：6 小时 · $200 · 可玩。模型没换，换的是 harness。
在"harness 搭得好"的仓库里，同一个 Codex 模型从"不可靠"变成"可靠"——不是好一点的边际优化，是质变。差别不在模型权重，差别在仓库结构本身。
这两条结论加在一起，把行业过去三年的注意力从"调更好的 prompt"硬生生掰回了"建更好的环境"。这门课就是这一转向的系统化教学版本。
大部分人嘴里的 "harness" 其实只是"一个 prompt 文件"。这就像你开了一家餐厅，只有食材——没有灶台、没有刀具、没有菜谱、没有出菜流程——那不叫餐厅，那叫冰箱。
课程给出一个精确而可操作的定义——Harness = 模型权重之外的一切工程基础设施。OpenAI 把工程师的核心工作概括为三件事：设计环境、表达意图、构建反馈循环。Anthropic 直接把 Claude Agent SDK 称为"通用 agent harness"。两家公司侧重点不同，但都在说同一件事：
模型之外的一切工程基础设施，
决定了模型能力能被发挥多少。 — Harness Engineering 的底层公理
从 prompt 工程到 harness 工程的转变，本质上是从"说服模型做对"转向"构建一个让模型只能做对的系统"。前者把 agent 当成需要哄好的同事，后者把 agent 当成必须配套基础设施才能正常运转的"计算资源"。
课程把一个完整的 harness 拆成五个职责清晰的子系统。这五者缺一不可——就像厨房的五个功能区：菜谱架、刀具架、灶台、备菜台、出菜检查口。少一个，菜还是能做，但总是别扭。这套模型是整门课的"概念基石"，后面 12 讲都在围绕它展开。
这五个子系统不是独立模块——它们围绕 agent 形成一个闭环。指令告诉 agent 该做什么；agent 通过工具访问环境；环境的运行结果回到反馈（验证）；状态记录贯穿始终；范围在每一步约束 agent 的行动半径。
想量化 harness 各组件的价值？保持模型不变，逐个移除五个子系统，看哪个子系统缺失时性能下降最多。那个就是你的瓶颈——集中精力加强它。这是 Anthropic 在内部反复使用的方法（component ablation），也是这门课贯穿始终的诊断思路。课程的 P06 综合项目要求学生亲手做一次完整的消融实验。
一个团队经历四个阶段——其实就是在一件一件地添置厨具。模型一个字没改：
yarn test && yarn lint && yarn build。四次迭代，模型一个字没改，成功率从 20% 到接近 100%。你没有换更贵的食材，你只是把厨房收拾利索了。
这门课的另一个核心理念：agent 的一次会话不应该是"自由发挥"，而应该遵循一套结构化的、可重复执行的协议。开工、选取、执行、收尾——每一步都有明确动作，每一次状态转换都被 harness 管控。
AGENTS.md / CLAUDE.md——加载项目硬约束与导航init.sh——依赖安装、环境验证、健康检查一条龙claude-progress.md——上次会话发生了什么feature_list.json——哪些功能已完成、哪些待办git log——最近的实际改动是什么claude-progress.md——本次做了什么、验证了什么feature_list.json——状态、证据、下一步Harness 管控每一次状态转换；模型决定每一步具体写什么代码。没有 harness 时，第 9 步会变成 "agent 说看起来没问题"。有 harness 时，第 9 步是"测试通过、lint 干净、类型检查通过，且证据写在了 progress.md 里"。这是整门课对"什么叫做完"的重新定义。
12 个讲义按"问题驱动"组织，每讲只回答一个核心问题。下面给出每讲的核心问题、关键概念、核心论证与"为什么这一讲重要"。讲义之间按六个学习阶段递进，每两讲对应一个项目。
开篇之讲，建立"基准测试与真实工程之间的能力鸿沟"这个起点性事实。指出 SWE-bench、HumanEval 等基准测试上的表现并不等同于在真实仓库里跨多次会话完成多步工程任务的能力——后者依赖的不只是"会写代码"，还包括对项目约定、构建系统、测试结构、隐式假设的把握。
学生在这一讲建立认知拐点：把目标从"模型能力"重新对准"环境与模型的共同体"。这一拐点不发生，后续 11 讲都白讲。
配套项目 · P01 baseline vs minimal harness给出五子系统模型的精确定义。强调"harness ≠ 一个 prompt 文件"，而是指令 + 状态 + 验证 + 范围 + 生命周期的协同结构。用"厨房五大功能区"做类比，让抽象概念可感可触。
关键论证：OpenAI 把工程师工作概括为"设计环境、表达意图、构建反馈循环"；Anthropic 直接把 SDK 称为"通用 agent harness"。两家公司路径不同，结论一致：模型权重之外的一切才是 harness。
五子系统中，反馈子系统（验证）通常是投入最少、回报最高的——这是这一讲留给学生的"先动手哪里"的明确指引。
认知基石 · 后续 10 讲都在围绕五子系统展开OpenAI harness 哲学的最硬核命题：agent 看不到的东西，对它来说就不存在。如果项目约定写在 Notion 里、构建命令写在 Slack 里、验收标准写在 PM 的脑子里，那对 agent 而言它们都不存在。所有让 agent 能可靠工作的上下文必须以文件形式存在于仓库内。
这一讲是组织结构层的"硬地基"——后面的所有状态文件、feature list、progress log，本质都是"把上下文搬进仓库"。
原则 · Repository as System of Record有了"仓库是事实来源"原则后，很多人下一步会犯的错误是：写一个无所不包的 AGENTS.md。但巨型文件会被模型按"开头近因 + 末端近因"截取上下文，关键中段往往被忽略。OpenAI 的经验：AGENTS.md 应该是目录页，不是百科全书——约 100 行，放不下就拆分到 docs/ 让 agent 按需读取。
关键概念：渐进式展开 / Progressive Disclosure——给地图，不给说明书。让 agent 自己去找具体细节，而不是把所有东西塞进入口文件。
配套项目 · P02 agent-readable workspace这是 Anthropic 文章最看重的问题。Coding agent 的上下文窗口有限，一旦超过几小时或几次会话，关键决策就会被新的对话挤出窗口。结果：agent 反复重做、做错、做了完全不同的方向。
解法是"把状态写到磁盘上"——progress.md 记录每次会话发生了什么，下次会话开头就读它。把"记忆"从模型上下文转移到仓库文件，这是这一讲的核心机制。
"环境健康"是一切工作的前提，但环境会腐化：依赖版本漂移、本地缓存损坏、上次会话残留的脏文件。如果不显式跑一遍 init，agent 会在一个看似正常但暗藏问题的环境里工作几小时，最后才发现根本问题在环境上。
解法：init.sh 作为会话开工的第一个动作——dependency install、verification、health check 一条龙，失败就停下来，绝不带着隐患进入主任务。
Agent 有一种典型的"半完成多个东西"倾向：开始做功能 A 的一部分，过程中觉得"顺手把功能 B 也加上"，又被 B 拖住，最后两个都没做完，进度日志一片混乱。
解法是"一次一个功能"原则 + 显式的 Definition of Done。前者来自范围子系统的约束，后者来自验证子系统对"完成"的重定义——没有可运行证据就不能宣告完成。
原则 · One Feature at a Time这一讲提升了 feature_list 的地位——它不是普通文档，是 harness 的原语（primitive）：机器可读、有明确状态字段、有验证步骤、有证据链。agent 无法绕过它（一切动作都要登记），也无法"偷偷改"（修改本身就是可审计的）。
这一讲让学生意识到：结构化数据 > 散文式指令。一个 JSON 比一段 Markdown 更难被"创造性解读"。
配套项目 · P04 incremental indexing这是体感最强的痛点。Agent 写完代码后会"自我感觉良好地"说做完了——读自己的 diff、模拟一下执行流程，得出 "Looks good!" 然后停手。本质是 验证缺口（verification gap）：模型的"自信"不等同于"正确"。
Anthropic 的关键解法：把"干活的人"和"检查的人"分开——separate writer and verifier。让另一个 agent（或同一个 agent 的另一轮）专门负责审查，不允许写代码的那一轮自己拍板"完成"。
机制 · Writer / Verifier Separation单元测试通过 ≠ 应用真的能跑。Agent 经常做出"测试通过但集成时崩溃"的代码：mock 用错了、依赖注入错了、构建链断了。课程把"完整流水线跑通"立为唯一可信的验证标准——install → build → unit → integration → e2e 全过，才算"完成"。
这一讲也解释了为什么验证应该写进 init.sh 和 verify.sh——让 agent 必须跑、且能复现地跑。
很多人把可观测性当成"日志库"——它远不止。当 agent 在你的仓库里跑 6 小时，做了 200 次文件编辑和 80 次 shell 调用，如果你看不到它做了什么，你就修不了它搞坏的东西。可观测性必须是 harness 的内建子系统：会话日志、命令执行轨迹、文件变更摘要、决策点回放。
这一讲把 P11 与 OpenAI Codex 的本地可观测性栈（日志/指标/追踪 + git worktree 隔离）对齐，是"工业级 harness"的标志。
原则 · Observability is a First-Class Citizen课程收官：下一次会话的成功，取决于这一次会话的清理。clean-state checklist 应该是会话结束前 agent 必须跑过的最后一道关口——所有改动 commit、所有进度文件更新、所有未完成项明确登记、没有遗留的脏文件。
课程在这里完成闭环——L06（开工初始化）与 L12（收尾清理）形成结构对偶：每次开门和关门都有协议。这是工业级 harness 与 hobby-grade harness 的分水岭。
配套项目 · P06 runtime observability + full harness课程最有匠心的设计：所有 6 个项目都围绕同一款 Electron 个人知识库桌面应用。P(N+1) 的 starter 来自 P(N) 的 solution——应用本身在演化，你的 harness 技能也跟着一起演化。这避免了"每个项目从零开始"的认知负担，让学生能在真实的、持续变化的代码库里观察 harness 改进的累积效果。
核心功能：导入本地文档 → 管理文档库 → 处理与索引 → AI 问答（带引用） → 返回可追溯的回答。选这个应用是因为它同时具备：实际价值感强、真实的产品复杂度、非常适合观察 harness 优化前后的对照——既有 UI、又有索引、还有 AI 调用，三条线索都能被 harness 影响。
用同一个任务跑两次：第一次只给 prompt，第二次给完整最小 harness。亲手对比两次的成功率、返工次数、时间花费。这是整门课最重要的"打脸时刻"——大多数学生在这里第一次相信 harness 真的有用。
把项目重构成 agent 友好的结构：渐进式 AGENTS.md（目录页 + docs/）、明确的命令清单、持久化状态文件初步引入。这里学生第一次实践"渐进式展开"原则——不写一个巨型 prompt，而是写一张能让 agent 自己导航的地图。
这是体感最强的项目之一。学生强制把一个 4–6 小时的任务拆到三天里完成，每天关掉 agent 重新开。如果 harness 没做好，第二天的 agent 会重做第一天的工作；做好的 harness 会让它从 progress 日志和 feature_list 里"完全恢复上下文"，继续干第三天的剩余任务。
实现增量索引功能，强制 agent 一次只动一个功能、做完一个再做下一个。引入运行时反馈机制——agent 每完成一步要从 verification 拿到证据，证据缺失就回去重做。这里学生真正理解了"功能清单作为原语"的实际意义。
实现带引用的问答功能，要求 agent 给出的每个回答都有可追溯的文档来源。借此让学生第一次实现"writer / verifier 分离"模式：写答案的那一轮不能宣告完成，必须由另一轮专门审查，引用对不上就回退重做。这是 Anthropic harness 哲学的核心实践。
综合项目：把前 5 个项目积累的所有机制系统地组织成一套"工业级 harness"，加入运行时可观测性（命令轨迹、文件变更摘要、决策回放），并做消融实验——依次移除每个子系统，量化它的边际贡献，写成报告。这是整门课的"出师作品"，学生在这里成为真正能为自己团队搭 harness 的从业者。
这套"同一应用，逐项目演化"的设计有两个非常聪明的教学副作用：
课程作者在 README 中专门给出"最小起步"路径：四个文件，今天放进你的项目，明天 agent 的稳定性就会有可感的提升。这是这门课少见的"先尝甜头、再看原理"的入口设计，特别适合想推动团队采纳的技术负责人——先做一次能复述的小成功，再讲方法论。
包含五件事：项目一句话概述、技术栈与版本、首次运行命令、不可违反的硬约束（如"所有 API 必须走 OAuth 2.0"）、指向更详细文档的链接。关键是"指南"不是"百科"——agent 按需自己跳转去 docs/ 读细节。
三段：INSTALL_CMD（依赖安装）→ VERIFY_CMD（验证环境健康）→ START_CMD（启动服务）。失败必须 exit non-zero，强制 agent 在环境有问题时停下来，绝不带着隐患进入主任务。
每个 feature 至少四个字段：id、status（todo/in_progress/done/blocked）、verify_command（什么命令能验证它完成）、evidence（最近一次验证的输出摘要）。这是 agent 不能绕过的范围边界。
每次会话尾部写一段：本次做了什么、验证了哪些、哪些做了一半、哪些被阻塞、下次进来该做什么。会话开头读它，会话结尾写它——这条简单的循环就把"跨会话记忆"问题解决了 80%。
四件套之后，按项目演化引入：
session-handoff.md —— 比 progress 更紧凑的"会话交接简报"clean-state-checklist.md —— 会话结束前必须过的清单evaluator-rubric.md —— Writer / Verifier 分离时给 verifier 用的评分量规课程不建议跳读。每两讲对应一个学习阶段，每个阶段一个项目。兼职节奏每阶段约一周；想加速的话，前三阶段一个长周末就能跑完。
如果你已经在用 Claude Code 或 Codex 做项目，非常建议直接从 P01 开始，再回头读 L01–L02 印证。课程的设计就是"先用后悟"——亲手做过对照实验，才更能体会五子系统模型的精度。直接读概念再去做项目，反而会觉得"这不是显然吗"，错过认知重塑的最佳时机。
读完整个课程目录，能感受到几条贯穿始终的工程哲学。它们既是课程的设计准则，也是 harness engineering 这个学科的"性格"。
这门课不是孤立存在的——它处在 2025–2026 年间快速演化的 agent 工程生态中。把它和你已经熟悉的几条线索放在一起看，会得到更立体的理解。
如果你熟悉 Anthropic 的 Skills 体系或 MCP 生态，Harness Engineering 教的就是"Harness 这一层"的工程化：Skills 是可复用的领域能力包，Tools 是底层可调用的原语，Harness 是把这两者组织起来、加上状态/验证/范围/生命周期的运行时环境。Skills 让 agent "会做某件事"，Harness 让 agent "可靠地做某件事"。两者不冲突，是层叠关系——一个好的 Harness 内部会内嵌多个 Skills 调用。
如果你之前对比过 OpenAI 的 harness 设计与 Anthropic 的 Claude Agent SDK，这门课会给你一个统一的"评估框架"：
如果你在探索多 agent 架构（如 Google A2A 协议、Claude Code Sub-agents、agent-team 模式），这门课提供了"单 agent 工作环境"的基础。多 agent 协作的本质是多个 agent 共享同一套 harness 约定，或者每个 agent 有自己的 harness 但通过结构化协议互通。没有单 agent 的 harness 工程，就没有靠谱的多 agent 编排——L09 的 writer/verifier 分离就是多 agent 模式最朴素的形式。
如果你在为团队制定 AI 工具采纳规范、写 CLAUDE.md 配置标准、设计多 agent 工作流 playbook，这门课的价值不只在概念，更在可借用的具体格式——AGENTS.md 模板、feature_list.json schema、init.sh 范本、progress 日志规约、clean-state checklist。这些都是可以直接吸收进团队 playbook 的"现成砖头"。
对已经在做团队工具采纳的人——把这门课的最小起步部分（§ 06 的四件套）作为团队所有项目的"AI-Ready 仓库基线"，再把课程的 12 讲作为团队内部分享会的素材，每周一讲，3 个月跑完。配合每个项目的对照实验作为"成果展示"，比纯理论分享会落地效率高得多。
| 类型 | 资源 | 读法建议 |
|---|---|---|
| 主参考 | OpenAI · Harness Engineering | 读 L01–L04 之前先看，建立 "repo as system of record" 直觉 |
| 主参考 | Anthropic · Effective Harnesses for Long-Running Agents | 读 L05、L09 之前看，对应 state 持久化与 writer/verifier 分离 |
| 主参考 | Anthropic · Harness Design for Long-Running Apps | 读 P06 之前看，是综合项目的"业界对照" |
| 辅助 | LangChain · The Anatomy of an Agent Harness | 第三方视角的"解剖学"，适合 L02 之后做横向印证 |
| 辅助 | Thoughtworks · Harness Engineering on Technology Radar | 行业地位证明，给团队推广时引用 |
| 辅助 | HumanLayer · Skill Issue: Harness Engineering for Coding Agents | 从从业者角度写的实战教训，适合 P01 之后读 |
直接做 P01 → 边做边读 L01–L02 → P02 → 读 L03–L04 → 依此类推。先体验对照实验，再看原理。这是课程作者隐含推荐的路径。
从 L01 一路读到 L12，再回头做 6 个项目。适合"必须先全局理解再动手"的学习者。但请记住：L02 之前读完五子系统模型，意义有限。
读 § 06 最小起步 + § 02 五子系统 + § 03 会话生命周期 → 在自己项目落地 → 跑完一次明显成功的对照 → 把这次成功作为 team demo → 再扩散到 12 讲分享会。用一次具体的小胜利换取整个团队的认知共识，比直接讲方法论高效得多。