【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载本篇技术指南围绕开源课程仓库 Learn Harness Engineering项目路径 README.md展开系统讲解Harness Engineering的核心内涵为 AI 编程 Agent 构建完整工作环境使其在真实仓库、多会话、无人全程盯守的情况下稳定交付。读者读完可掌握 Harness 的五大子系统指令、状态、验证、范围、会话生命周期、16 步会话生命周期、快速上手的四个关键文件以及课程 14 讲 8 项目 模板库的完整学习路径。界面预览这门课长什么样课程使用 VitePress 构建文档站点下面三张截图分别展示了课程首页、单讲页面和模板资源库页面的实际效果截图来自 docs/public/screenshots/readme/ 目录一、核心事实模型很聪明但 Harness 决定它可不可靠课程 README 用一个反直觉的结论开篇世界上最强的模型在真实工程任务上如果你不为其搭建合适的环境依然会失败。这不是泛泛而谈。README 引用 Anthropic 的受控实验同一个模型Opus 4.5、同一个需求创建一个 2D 复古游戏编辑器——没有 Harness20 分钟、花费 9 美元产出一个无法运行的东西带完整 Harness规划器 生成器 评估器6 小时、花费 200 美元产出一个真正可玩的游戏。模型没有变变的是 Harness。OpenAI 在 Codex 上也报告了同样的结论在良好 Harness 化的仓库中同一个模型会从不可靠跃迁到可靠——这不是边际改善而是质量上的跳变。你很可能亲身经历过这种场景让 Claude 或 GPT 在自己的仓库里干活开头一切顺利——读文件、写代码、看起来高效然后某一步出错跳过某个步骤、弄坏测试、宣称完成但实际什么都没跑通你花在修补上的时间比自己做还多。README 的结论非常直接这不是模型的问题这是 Harness 的问题。一个 HARNESS 的示意 你 -- 下达任务 -- Agent 读取 harness 文件 -- Agent 执行 | harness 控制每一步 | -- 指令做什么、按什么顺序 -- 范围一次一个功能不过度扩张 -- 状态进度日志、功能清单、git 历史 -- 验证测试、lint、类型检查、试运行 -- 生命周期开始时初始化、结束时清理 | v 只有验证通过时 Agent 才会停下二、什么是 Harness Engineering围绕模型建造完整的工作环境Harness Engineering 的定义是在模型周围构建完整的工作环境使它产出可靠的结果。它不只是写更好的 prompt而是设计模型运行其上的整套系统。五大子系统Harness 有五个子系统README 用一张架构图完整呈现┌─────────────────────────────────────────────────────────────────┐ │ HARNESS │ │ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐ │ │ │ 指令 │ │ 状态 │ │ 验证 │ │ │ │ │ │ │ │ │ │ │ │ AGENTS.md │ │ progress.md │ │ 测试 lint │ │ │ │ CLAUDE.md │ │ feature_list │ │ 类型检查 │ │ │ │ feature_list │ │ git log │ │ 试运行 │ │ │ │ docs/ │ │ 会话交接 │ │ e2e pipeline │ │ │ └──────────────┘ └──────────────┘ └──────────────────────┘ │ │ │ │ ┌──────────────┐ ┌──────────────────────────────────────┐ │ │ │ 范围 │ │ 会话生命周期 │ │ │ │ │ │ │ │ │ │ 一次一个功能 │ │ 开始时 init.sh │ │ │ │ 完成的定义 │ │ 结束时 clean-state 检查清单 │ │ │ │ │ │ 为下一会话留交接记录 │ │ │ └──────────────┘ │ 仅在安全可继续时提交 │ │ │ └──────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────────┘ MODEL 决定怎么写代码。 HARNESS 控制何时、何地、怎么写。 Harness 不会让模型更聪明 它让模型的结果更可靠。各子系统的职责README 原文要点指令Instructions——告诉 Agent 要做什么、按什么顺序、开工前先读什么。它不是单个巨型文件而是 Agent 按需导航的渐进式展开结构。状态State——跟踪已完成、进行中、待办事项。状态落在磁盘上下一会话可以从上一会话停下的地方精确续接。验证Verification——只有实际跑过的测试才算数。Agent 不能在没有可执行证据的情况下宣称成功。范围Scope——把 Agent 限制在一次只做一个功能。不过度扩张不把三件事各做一半不通过改写功能清单来掩盖未完成的工作。会话生命周期Session Lifecycle——开始时初始化结束时清理为下一会话留下干净的重新启动路径。仓库中的 skill 定义与这个框架完全对应。skills/harness-creator/SKILL.md 将五个子系统映射为最小产物清单子系统最小产物用途InstructionsAGENTS.md或CLAUDE.md启动路径、工作规则、完成的定义Statefeature_list.json、progress.md当前功能、状态、证据、下一步Verificationinit.sh或文档化的命令Agent 宣称完成前必须运行的测试/检查Scope功能依赖与完成标准防止过度扩张与半成品Lifecyclesession-handoff.md、会话结束例程让下一个会话可重新启动三、为什么需要这门课有无 Harness 的会话对比课程要回答的真实问题不是模型会不会写代码会而是它们能否在真实仓库里、跨多个会话、在无持续人工监督下可靠地完成真实工程任务目前答案很明确——没有 Harness不行。README 给出了两种会话的对比无 HARNESS 有 HARNESS 第 1 会话agent 写代码 第 1 会话agent 读指令 agent 弄坏测试 agent 运行 init.sh agent 说完成了 agent 一次只做一个功能 你手动修补 agent 宣称完成前先验证 agent 更新进度日志 第 2 会话agent 从零开始 agent 提交干净状态 agent 没有记忆 不知道之前发生了什么 第 2 会话agent 读进度日志 agent 重做已做过的工作 agent 从停下的地方精确续接 或做完全无关的事 agent 继续未完成的功能 你又修补一次 你审查结果而不是救火 结果你花在修补上的时间 结果agent 把活干完 比自己干还多 你审查结果课程关注的真实问题包括哪些 Harness 设计能提升任务完成指标哪些设计能减少返工和错误收尾哪些机制能让长时任务稳定推进哪些结构能在多次 agent 运行后仍保持系统可维护四、快速上手今天就能用四个文件改善你的 AgentREADME 强调不必读完 14 讲才能受益。如果你已经在真实项目里使用编码 Agent现在就能改进它。核心思路与其只写 prompt不如给 Agent 一套结构性文件明确要做什么、已做了什么、工作如何被验证。这些文件放在仓库里保证每次会话从相同状态开始你的项目根目录 ├── AGENTS.md -- agent 的工作手册 ├── CLAUDE.md --使用 Claude Code 时的替代方案 ├── init.sh -- 安装 验证 启动 ├── feature_list.json -- 有哪些功能、哪些已完成 ├── claude-progress.md -- 每次会话发生了什么 └── src/ -- 你的真实代码四个文件即可让会话稳定性显著提升。这些模板在仓库中都有可直接复制的实现位于 skills/harness-creator/templates/AGENTS.md / CLAUDE.mdagent 的工作手册模板 agents.md 的结构值得逐节解读启动工作流Startup Workflow写代码之前先pwd确认工作目录、完整读取本文件、读取项目文档、运行./init.sh验证环境健康、读取feature_list.json了解功能状态、git log --oneline -5审查近期提交。若基线验证失败先修复再扩展新范围。工作规则Working Rules一次只从feature_list.json挑选一个未完成功能不跑验证命令不得宣称完成结束会话前更新progress.md与feature_list.json不修改与当前功能无关的文件保证下一会话可立即运行./init.sh。完成定义Definition of Done目标行为已实现 必需验证确实运行过测试/lint/类型检查 证据已记录进feature_list.json或progress.md 仓库仍可从标准启动路径重启。会话结束End of Session更新进度、更新功能状态、记录未解决风险、在安全状态下用描述性信息提交、留出可立即重启的干净仓库。升级路径Escalation架构决策查架构文档需求不清查需求文档测试反复失败则更新进度并标记人工审查范围模糊则重读feature_list.json的完成定义。init.sh标准启动与验证路径模板 init.sh 是一个跨语言、跨包管理器的自检测脚本核心逻辑检测到package.json时按pnpm-lock.yaml→yarn.lock→bun.lock/bun.lockb→ 默认npm的顺序选择包管理器然后按check→typecheck→type-check→lint→test→build的优先级执行package.json中已存在的脚本检测到pyproject.toml/requirements.txt时运行python -m pytestpytest 退出码 5 表示未收集到测试不算失败和compileall语法检查跳过 venv、node_modules、build 等目录依次支持 Gogo test ./...、Rustcargo test、Mavenmvn test、Gradle./gradlew test、.NETdotnet test结尾打印下一步提示读feature_list.json→ 挑一个未完成功能 → 只实现该功能 → 宣称完成前重跑验证。feature_list.json功能状态跟踪器模板 feature-list.json 定义了机器可读的功能条目结构每个功能含id功能唯一标识如feat-001name功能名称description功能行为描述dependencies依赖的功能 id 数组形成范围边界statusnot-started/ 进行中 / 已完成等状态evidence完成证据验证命令输出、测试结果等。模板内置了 5 个渐进式占位功能项目搭建 → 第一个用户可见功能 → 验证覆盖 → 文档更新 → 清理与交接演示了依赖链如何约束 Agent 的执行顺序。session-handoff.md多会话交接模板 session-handoff.md 为更大的会话提供结构化交接当前目标Goal/状态/分支与提交、本次会话完成项、验证证据表检查项/命令/结果/备注、变更文件、已做决策、阻塞项/风险以及下一会话启动清单读 AGENTS.md → 读 feature_list.json 和 progress.md → 审阅本交接 → 编辑前运行 ./init.sh。仓库中的真实项目示例可以印证这套文件布局例如 projects/project-01/solution/ 下就包含AGENTS.md、CLAUDE.md、claude-progress.md、feature_list.json、init.sh等完整产物。五、Agent 会话生命周期16 步把宣称完成变成验证通过课程的核心观点之一是Agent 会话必须遵循结构化的生命周期而不是自由发挥。README 给出了完整的 16 步生命周期启动 1. Agent 读取 AGENTS.md / CLAUDE.md 2. Agent 运行 init.sh安装、验证、健康检查 3. Agent 读取 claude-progress.md上次发生了什么 4. Agent 读取 feature_list.json什么完成了、接下来做什么 5. Agent 检查 git log最近的变更 选择 6. Agent 精确选择一个未完成的功能 7. Agent 只在该功能上工作 执行 8. Agent 实现功能 9. Agent 运行验证测试、lint、类型检查 10. 若验证失败修复并重跑 11. 若验证通过记录证据 收尾 12. Agent 更新 claude-progress.md 13. Agent 更新 feature_list.json 14. Agent 记录仍损坏或未验证的内容 15. Agent 提交仅在安全可继续时 16. Agent 为下一会话留下干净的重新启动路径README 的总结非常精辟Harness 控制这个生命周期中的每一次转换模型决定每一步怎么写代码。没有 Harness第 9 步会退化成agent 说看起来不错有 Harness第 9 步是测试通过、lint 干净、类型已检查。六、课程体系14 讲 8 项目 模板库课程由三部分组成讲座Lectures解释 Harness Engineering 背后理论的 14 个概念模块项目Projects从零构建 agent 工作环境的 8 个实战项目模板库Templates可直接复制进自己仓库的模板AGENTS.md、feature_list.json、init.sh等。14 讲每讲回答一个关键问题会话问题核心思想L01强大的模型为何在真实任务上失败基准测试与真实工程的差距L02Harness到底是什么五大子系统指令、状态、验证、范围、生命周期L03为什么仓库必须成为唯一事实来源Agent 看不到的东西就不存在L04为什么单个巨型指令文件会失败渐进式展开给地图而不是百科全书L05为什么长时任务会丢失连续性进度落盘从停下的地方继续L06为什么初始化需要独立阶段Agent 动工前先验证环境可运行L07为什么 Agent 会过度扩张又做不完一次一个功能完成的精确定义L08为什么功能清单是 Harness 原语Agent 无法忽略的、机器可读的范围边界L09为什么 Agent 过早宣布胜利验证空洞自信 ≠ 正确L10为什么端到端测试会改变结果只有跑通完整 pipeline 才算真验证L11为什么可观测性必须内置于 Harness看不到 Agent 做了什么就无法修复它弄坏的东西L12为什么每个会话都必须留下干净状态下一会话的成功取决于本会话的清理L13为什么你应该停止给 Agent 写 prompt从手动 prompt 到自主 loop目标 loop、定时器 loop、maker-checker 分工L14为什么单个 loop 会演变成图从单 loop 到图工程——节点、边、共享状态、路由以及何时真正值得画图8 个项目把讲座方法应用到同一个 Electron 应用上项目你要做什么Harness 机制P01同一任务做两次仅 prompt vs 规则化最小 HarnessAGENTS.md init.sh feature_list.jsonP02把仓库重构成 Agent 可读Agent 可读工作区 持久状态文件P03让 Agent 从停下的地方继续进度日志 会话交接 多会话连续性P04阻止 Agent 做太多或太少运行时反馈 范围控制 增量索引P05强制 Agent 验证自己的工作自验证 有依据的问答 证据驱动的完成P06从零构建完整 Harness毕业项目完整 Harness全部机制 可观测性 消融研究P07构建你的第一个自动化 loop目标 loop、定时器 loop、maker-checker 分工、loop 状态管理P08把你的工作流画成图显式节点/边/状态/路由、并行 fan-out/fan-in、回退边、人工审批项目的递进关系非常清晰P01 让你看到问题 → P02 重排仓库 → P03 连接会话 → P04 加入反馈回路 → P05 强制自验证 → P06 构建完整系统 → P07 跳出 loop → P08 把系统画成图。每个项目的 solution 会成为下一个项目的 starter——应用在进化你的 Harness 技能也随之成长。2026 年新增内容README 记载了近期的三次内容更新2026 年 8 月 · Frontier Harness Design Breakdowns前沿 Harness 设计拆解新增 文档目录用课程的五子系统框架对四款先进产品做逆向工程分析——Pi 如何构建自己的 Harness最小内核、可编程扩展、Claude Code 如何构建自己的 Harness四层记忆、五级压缩、hooks 与子代理隔离、Codex 如何构建自己的 Harness仓库即事实来源、AGENTS.md 作目录页、worktree 隔离、DeepSeek 如何构建自己的 Harness一切皆插件、能力边界、事件管道。2026 年 8 月 · Graph Engineering图工程新增 第 14 讲 与 项目 08。核心观点Loop 只是只有一个节点的图。2026 年 7 月 · Loop EngineeringLoop 工程新增 第 13 讲 与 项目 07核心观点Harness 工程造机器Loop 工程设计机器行驶的道路。七、学习路径8 个阶段循序渐进课程按时间顺序设计每阶段建立在前一阶段之上第 1 阶段看到问题 第 2 阶段重建仓库 L01 强大模型 ≠ 可靠执行 L03 仓库作为唯一事实来源 L02 Harness 到底是什么 L04 指令分文件而非单巨型文件 ↓ P01 仅 prompt vs 规则化对比 ↓ P02 Agent 可读的工作环境 第 3 阶段连接会话 第 4 阶段反馈与范围 L05 会话间保持上下文 L07 划定明确任务边界 L06 每个会话前初始化 L08 功能清单作为 Harness 原语 ↓ ↓ P03 多会话连续性 P04 用运行时反馈矫正 Agent 行为 第 5 阶段验证 第 6 阶段整体组装 L09 阻止 Agent 过早宣布成功 L11 让 Agent 运行时可观测 L10 跑通完整 pipeline 真验证 L12 每会话结束干净交接 ↓ ↓ P05 Agent 独立验证自己的工作 P06 构建完整 Harness毕业项目 第 7 阶段自动化 loop 第 8 阶段把系统结构化 L13 别再写 prompt——设计 loop L14 把系统画成图—— ↓ 节点、边、共享状态、路由 P07 构建第一个自动化 loop ↓ 目标 loop、定时器 loop、 P08 把工作流画成图 maker-checker 显式图、并行 fan-out/fan-in、 回退边、人工参与README 建议按序学习时每个阶段约一周想加速的话可在周末一次性完成 1–3 阶段。八、最终项目一个真实的 Electron 应用全部 8 个项目围绕同一个产品构建基于 Electron 的个人知识库桌面应用。┌─────────────────────────────────────────────────────┐ │ 知识库桌面应用 │ │ │ │ ┌──────────────┐ ┌──────────────────────────────┐│ │ │ 文档列表 │ │ 问答面板 ││ │ │ │ │ ││ │ │ doc-001.md │ │ 问: Harness 工程是什么 ││ │ │ doc-002.md │ │ 答: 围绕 Agent 模型构建的… ││ │ │ doc-003.md │ │ [来源: doc-002.md] ││ │ │ ... │ │ ││ │ └──────────────┘ └──────────────────────────────┘│ │ │ │ ┌─────────────────────────────────────────────────┐│ │ │ 状态栏: 42 篇文档 | 38 篇已索引 | 上次同步 3 天前 ││ │ └─────────────────────────────────────────────────┘│ └─────────────────────────────────────────────────────┘ 核心功能: ├── 导入本地文档 ├── 管理文档库 ├── 处理与索引文档 ├── 基于导入内容进行 AI 问答 └── 返回带来源依据的回答选择这个产品的原因高实用价值、足够的真实产品复杂度以及良好的 Harness 改进可观测场景。仓库中 projects/shared/ 提供共用的 Electron TypeScript React 基础projects/project-01/ 至 projects/project-08/ 各自包含starter/起点与solution/解法。九、适用人群与前置条件适合正在使用编码 Agent、希望获得更高稳定性与质量的开发者想在 Harness 设计上建立系统认知的研究者或工程师想理解环境设计如何影响 Agent 表现的团队技术负责人。不适合想无编程接触 AI 的人只对 prompt 感兴趣、不打算真实落地的人还没准备好让 Agent 在真实仓库里干活的学习者。工具要求至少其一Claude Code、Codex或任何支持文件编辑、命令执行与多步任务的 IDE/CLI 编码 Agent。课程要求打开本地仓库、允许 Agent 编辑文件、允许 Agent 执行命令、验证结果并重启任务。没有这类工具也能读课程材料但无法按设计完成项目。前置知识熟悉终端、Git 与本地开发环境至少能用一种常见技术栈读写代码有基本调试经验读日志、跑测试、观察运行时行为有足够时间做动手型课程作业。Electron、桌面应用、local-first 工具、测试/日志/软件架构经验、以及 Codex/Claude Code 使用经验有帮助但非必需。十、本地预览与仓库结构仓库使用 VitePress 构建文档站点package.json 中确认了以下脚本npm install npm run docs:dev # 带热重载的开发服务器 npm run docs:build # 生产构建 npm run docs:preview # 预览构建产物此外还有两个辅助脚本npm run pdf:build本地生成英文与中文 PDF 课程材料产物写入artifacts/pdfs/和npm run screenshots:readme更新 README 预览截图。README 还提到可用 GitHub Actions workflow 自动构建并发布 PDF 到 Releases。仓库结构概览README 记载learn-harness-engineering/ ├── docs/ # VitePress 文档站点 │ ├── lectures/ # 14 讲index.md code/ 示例 │ ├── projects/ # 8 个项目描述 │ └── resources/ # 多语言模板与参考 ├── projects/ │ ├── shared/ # 共用的 Electron TypeScript React 基础 │ └── project-NN/ # 各项目的 starter/ 与 solution/ ├── skills/ # 可复用的 AI Agent skill │ └── harness-creator/ # Harness Engineering skill ├── package.json # VitePress 开发工具 └── CLAUDE.md # 本仓库的 Claude Code 指令十一、可复用技能与实战工具harness-creator仓库附带一个可安装进 IDE 或 Agent 工作环境的可复用 skillskills/harness-creator/用于在几分钟内为自己的项目生成生产级 Harness。其 SKILL.md 定义了最小 Harness 优先原则并提供四组脚本# 创建 harness为本地仓库生成 AGENTS.md、feature_list.json、init.sh 等 node skills/harness-creator/scripts/create-harness.mjs --target /path/to/project # 审计已有 harness按五大子系统打分报告最低分区域与改进项 node skills/harness-creator/scripts/validate-harness.mjs --target /path/to/project # 生成可分享的评估报告 node skills/harness-creator/scripts/render-assessment-html.mjs --target /path/to/project # 运行结构化基准测试先自检脚本本身再对目标打分 node skills/harness-creator/scripts/run-benchmark.mjs --target /path/to/project --html /path/to/report.htmlcreate-harness.mjs的常用选项--agent-file CLAUDE.md面向 Claude 的项目、--package-manager npm|pnpm|yarn|bun检测错误时手动指定、--commands cmd one,cmd two自定义验证命令、--force仅在确认可覆盖时使用。SKILL.md 还列出 7 份模式参考如 memory-persistence-pattern.md、context-engineering-pattern.md、lifecycle-bootstrap-pattern.md、gotchas.md 等按需加载。skill 的设计规则同样值得在自建 Harness 时遵循根指令文件保持简短路由与不变量而非完整手册项目事实放项目文档而非 skill验证命令显式且可运行标记功能完成前必须给出证据一次只激活一个功能除非有显式多 Agent 所有权边界优先追加/更新状态文件而非依赖聊天历史绝不在脚本里隐藏破坏性行为覆盖操作必须经用户明确同意。十二、核心参考资源课程 README 列出的主要参考来源行业内的 Harness Engineering 代表性资料OpenAIHarness engineering: leveraging Codex in an agent-first worldAnthropicEffective harnesses for long-running agentsAnthropicHarness design for long-running application developmentOpenAIUnrolling the Codex agent loopAnthropicDemystifying evals for AI agentsLangChainImproving Deep Agents with harness engineeringThoughtworks / Martin FowlerHarness engineering for coding agent usersCursorContinually improving our agent harness结语从能写代码到可靠交付回到课程最核心的命题模型决定怎么写代码Harness 决定何时、何地、怎么写并最终决定结果可不可靠。通过五大子系统指令、状态、验证、范围、生命周期、16 步会话生命周期、四个关键文件AGENTS.md、init.sh、feature_list.json、progress.md以及 14 讲 8 项目的渐进路径这门课把给 Agent 写 prompt升级为为 Agent 设计工作系统。无论你今天是给现有仓库补上feature_list.json还是按 skills/harness-creator 的模板从零搭建迈出的每一步都是在把看起来完成了变成验证通过了。赞分享【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载相关推荐从提示词到系统Learn Harness Engineering 开源课程带你为 AI 编码 Agent 构建可靠的 Harness从提示词到系统Learn Harness Engineering 开源课程带你为 AI 编码 Agent 构建可靠的 Harness 本文以 learn ha深入理解 Harness五子系统模型与可验证的 AI Agent 工程化实践learn-harness-engineering Lecture 02深入理解 Harness五子系统模型与可验证的 AI Agent 工程化实践learn harness engineering Lecture 02 本篇Learn Harness Engineering 实战指南从 0 到 1 构建让 AI 编码 Agent 稳定可靠的 Harness 环境Learn Harness Engineering 实战指南从 0 到 1 构建让 AI 编码 Agent 稳定可靠的 Harness 环境 本文以 docs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考