【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载本指南以 learn-harness-engineering 仓库中随课程交付的harness-creatorskill 为核心讲解如何用它将任意代码仓库武装成 AI 编码 Agent 可靠工作的护栏系统——覆盖指令、状态、验证、范围与生命周期五大子系统。读完本文你将掌握从零脚手架一个 harness、对既有 harness 进行五维评分审计、生成可分享的评估报告以及理解支撑这些能力的模板、脚本与评估集在仓库中的真实实现。Skills 目录是什么随课程交付的 Agent 能力包在仓库的 docs/fr/skills/index.md 中skills目录被定位为随课程一起交付的 AI Agent skill 集合。所谓 skill本质上是一组自包含的 prompt 模板Claude Code、Codex、Cursor、Windsurf 等 AI 编码 Agent 可以按需加载它们去执行专门任务。与一次性提示词不同skill 把做某类事的方法论 可执行脚本 参考文档 模板打包成可复用、可版本化的资产。当前仓库交付的核心 skill 只有一个harness-creator全部实现位于 skills/harness-creator/ 目录入口是 SKILL.md同时提供 SKILL.md.en 英文版与 SKILL.md.uk 乌克兰语版。它定位为生产级的 harness engineering skill帮助开发者创建、评估并改进一个 harness 的五个核心子系统子系统最小产物目的Instructions指令AGENTS.md或CLAUDE.md启动路径、工作规则、完成定义State状态feature_list.json、progress.md当前特性、状态、证据、下一步Verification验证init.sh或文档化命令Agent 声称完成前必须运行的测试/检查Scope范围特性依赖与完成标准防止越界与半成品Lifecycle生命周期session-handoff.md、会话结束例程让下一个会话可无缝续接从 SKILL.md 的 Core Model 一节可以看到这五张表并非抽象口号而是被直接落地成了脚本评分维度、模板文件与评估用例的具象结构——下文逐一展开。快速开始安装与挂载 skill原文档给出的安装方式有两条路径方式一通过skillsCLI 直接添加npx skills add walkinglabs/learn-harness-engineering --skill harness-creator方式二手动拷贝将仓库中的harness-creator/目录整体复制到你项目的 skill 路径下若使用 Claude Code可以直接把 Agent 指向 SKILL.md 文件。关于 skill 的声明信息见 metadata.json版本1.0.0、MIT 许可、入口为SKILL.md兼容claude-code、codex-cli、cursor、windsurf以及通用的generic类 Agent。它还声明了 15 个触发词如harness engineering、session continuity、AGENTS.md、feature tracking意味着只要用户提到这类话题skill 就应当被自动唤起。对应地agents/openai.yaml 提供了 OpenAI 风格 Agent 的注册信息allow_implicit_invocation: true表示允许隐式调用。创建 Harness一条命令脚手架五件套SKILL.md 的 Common Tasks 给出了创建 harness 的入口命令node skills/harness-creator/scripts/create-harness.mjs --target /path/to/project支持的关键参数--agent-file CLAUDE.md面向 Claude 系项目时指定指令文件名默认AGENTS.md--package-manager npm|pnpm|yarn|bun当自动检测错误时手工指定包管理器--commands cmd one,cmd two自定义验证命令列表--force仅在确认允许覆盖已有文件时使用。脚本的完整实现位于 scripts/create-harness.mjs其行为逻辑非常透明解析参数后通过detectProject(target)探测项目类型再结合detectPackageManager()与用户指定的--package-manager决定包管理器若没有--commands则从 lib/harness-utils.mjs 的verificationCommands(project, ...)生成默认验证命令。随后依次拷贝四份模板文件init.sh则特殊处理——只有当目标不存在或传了--force时才写入并执行chmod(initPath, 0o755)赋予可执行权限避免覆盖用户已有的初始化脚本create-harness.mjs。脚本执行后会在终端打印检测到的技术栈、验证命令清单以及每个产物的WRITTEN/SKIPPED状态。根据 README.md 的说明脚本只依赖 Node.js 内置模块因此把 skill 目录复制到任意仓库后即可直接运行create-harness.mjs支持 Node/npm/pnpm/yarn/bun、Python、Go、Rust、Maven、Gradle 与 .NET 的基础验证命令检测。模板详解五件套各司其职脚手架落地的产物由 templates/ 下的模板决定逐一拆解agents.md —— 指令文件骨架agents.md 是一个带{{变量}}占位的模板被create-harness.mjs以AGENT_FILE_NAME、PROJECT_PURPOSE、VERIFICATION_COMMANDS、PRIMARY_VERIFICATION_COMMAND四个替换变量渲染create-harness.mjs。渲染后的文件包含五段核心结构Startup Workflow启动工作流pwd确认目录 → 完整读取本文件 → 读取项目文档 → 运行./init.sh→ 读取feature_list.json→git log --oneline -5查看近期提交若基线验证失败必须先修复再开新功能Working Rules工作规则一次只做一个特性、未跑验证不许宣称完成、会话结束前更新progress.md与feature_list.json、不越界改文件、离开时保持干净状态Definition of Done完成定义实现目标行为、验证确实运行、证据写入状态文件、仓库可从标准启动路径重启四项全部满足才算完成End of Session会话收尾更新进度、更新特性状态、记录风险阻塞、安全状态下提交、保证下一个会话能立即运行./init.shEscalation升级路径架构决策、需求不清、反复测试失败、范围模糊时分别该如何处理。feature_list.json —— 特性状态追踪器feature_list.json 是单一事实来源示例中预设了 5 个占位特性feat-001到feat-005每个特性含id、name、description、dependencies、status、evidence六个字段并通过dependencies串成一条依赖链Setup → 首个用户特性 → 验证覆盖 → 文档更新 → 清理交接天然约束了 Agent 的执行顺序。与之配套的 feature-list.schema.json 是 JSON Schemadraft-07定义了严格约束id必须匹配^feat-\d$status枚举为not-started、in-progress、blocked、done四种evidence在状态为done时用于记录验证证据id/name/description/status为必填。这使特性列表不仅能被人读还能被程序化校验——这正是结构化状态优于聊天记录的设计哲学。init.sh —— 标准初始化与验证路径init.sh 是整个验证子系统的核心也是五子系统中最能体现工程细节的部分。它以set -e开头保证失败即停随后按技术栈分支执行Node 系根据锁文件pnpm-lock.yaml/yarn.lock/bun.lock/bun.lockb自动选择 pnpm / yarn / bun / npm安装依赖后按check→typecheck→type-check的优先级运行静态检查再依次运行 lint、test、build均通过读取package.json的scripts字段判断是否存在Python优先python3运行pytest注释明确说明pytest 在没有收集到测试时退出码为 5对全新项目不算失败因此用|| [ $? -eq 5 ]兜底compileall用-x正则跳过.venv、env、node_modules、build、dist、__pycache__等目录避免语法检查误编译依赖Gogo test ./...Rustcargo testMavenmvn testGradle./gradlew test.NETdotnet test兜底未识别到清单文件时打印提示要求替换为项目自己的验证命令。脚本末尾还会打印下一步指引读取feature_list.json→ 挑一个未完成特性 → 只实现该特性 → 宣称完成前重跑验证。另外注意create-harness.mjs在自定义--commands时是通过 lib/harness-utils.mjs 的initScriptFromCommands(commands)动态生成 init.sh 的而非直接套用这份模板。progress.md —— 会话连续性日志progress.md 提供会话级状态记录模板包含当前状态上次更新时间、会话 ID、活跃特性、已完成/进行中/下一步清单、阻塞项与风险、决策记录含备选方案、本会话修改的文件清单、完成证据测试、类型检查、手工验证、以及留给下个会话的自由格式笔记。它解决的是长任务跨会话失去连续性的问题——所有关键上下文都落盘不依赖 Agent 的记忆。session-handoff.md —— 会话交接单session-handoff.md 用于多会话、跨天的大任务交接当前目标目标/状态/分支与提交、本会话完成项、验证证据表Check/Command/Result/Notes 四列、文件变更、决策、阻塞与风险、下一会话启动步骤读AGENTS.md→ 读feature_list.json和progress.md→ 复查本交接单 → 编辑前运行./init.sh、以及推荐下一步。审计既有 Harness五子系统结构化评分当 Agent 明明有 AGENTS.md 却还是把事情搞砸时就该对既有 harness 做审计。命令为node skills/harness-creator/scripts/validate-harness.mjs --target /path/to/project审计器会按五个子系统Instructions、State、Verification、Scope、Lifecycle分别打分然后报告最低分项以及能提升可靠性的前 2~3 项改动。按照 SKILL.md 的指导要把最低分视为候选瓶颈并用真实失败、日志或任务结果去确认因果关系而不是直接把低分当成事实结论。README.md 特别强调该评分是结构性structural的——它告诉你 harness 是否齐备、是否自洽但不能替代真实的前后 Agent 会话对比测试。评估报告与结构基准测试当需要可分享的评估结果时使用两个报告命令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.htmlrun-benchmark.mjs执行的是结构基准测试其自检机制值得一提它先脚手架一个一次性的临时 harness 并做验证以此证明自带脚本端到端可用然后再对目标项目评分并统计评估集覆盖度。SKILL.md 明确提醒真实效果仍然需要在代表性任务上做 Agent 会话的前后对比。七个参考 Pattern何时读哪一篇skill 内置了 7 份针对性参考文档位于 references/对应原文档中的表格并附上实际文件路径Pattern何时使用仓库文件Memory PersistenceAgent 跨会话遗忘memory-persistence-pattern.mdSkill Runtime把可复用工作流打包成 skillskill-runtime-pattern.mdContext Engineering上下文预算管理、JIT 加载context-engineering-pattern.mdTool Registry工具安全、并发控制tool-registry-pattern.mdMulti-Agent Coordination并行、专业化工作流multi-agent-pattern.mdLifecycle BootstrapHooks、后台任务、初始化lifecycle-bootstrap-pattern.mdGotchas15 个不明显的失败模式及修复gotchas.md这些参考文档并非空泛说教而是可直接落地的工程规律。例如 memory-persistence-pattern.md 提出三条黄金规则分层记忆人工维护的指令记忆 / Agent 自动写入的持久记忆 / 会话结束后的后台抽取、两步写入不变量先写完整内容到专题文件再向索引追加一行指针即使中途崩溃最坏也只是产生孤儿专题文件、以及本地覆盖优先指令优先级组织级 → 用户级 → 项目级 → 本地覆盖越局部越有最终决定权。索引被硬性限制在约 200 行 / 25KB每条一行专题文件则不限细节、按需加载。gotchas.md 则记录了违背原则会引发 bug 的非显然陷阱例如内存索引静默截断长条目先撞字节上限而非行数上限索引条目应保持一行钩子优先级反直觉本地覆盖文件在项目根目录时胜过用户级注入的规则需用cat ~/.claude/CLAUDE.md、cat ./CLAUDE.md、cat ./CLAUDE.local.md实测优先级栈并发安全应逐调用分类而非逐工具分类同一工具对某些输入安全、对另一些不安全需在运行时判断例如rm -rf开头的不允许并发、cat开头的允许。设计规则与交付清单SKILL.md 定义了八条设计规则是使用该 skill 时必须遵守的准则根指令文件保持精简只放路由与不变量不要写成完整手册项目事实放进项目文档不要塞进 skill验证命令必须显式、可运行特性标记完成前必须要求证据除非有显式的多 Agent 所有权边界否则同一时间只保留一个活跃特性优先追加/更新状态文件而不是依赖聊天历史绝不在脚本里隐藏破坏性行为覆盖操作必须获得用户明确同意。可交付的最小可用 harness 检查清单SKILL.mdAGENTS.md或CLAUDE.mdfeature_list.jsonprogress.mdinit.sh多会话工作时的可选session-handoff.md文档化的验证证据或下一步行动若环境不允许创建文件则改为提供完整文件内容与命令。评估集10 个用例如何约束行为skill 的评估配置位于 evals/evals.json共 10 个 eval 用例README 中标注10 eval cases已完成。每个用例包含prompt触发场景、expected_output期望产物和expectations可逐条核验的行为断言。例如Minimal Harness Creation要求为 TypeScript React 新项目产出约 50~100 行的 AGENTS.md、含 3~5 个占位特性的 feature_list.json、带验证命令的 init.sh断言包括包含启动工作流包含一次一特性策略字段合法的 JSON等Session Continuity Setup针对Agent 跨会话全忘场景断言 progress.md 与 session-handoff.md 的章节结构、记忆目录创建指引以及两步保存不变量Harness Assessment要求五个子系统各打 1~5 分并给出理由、识别瓶颈、给出 2~3 步改进计划Verification Workflow Design针对说完成但测试挂掉要求显式验证命令清单、含验证要求的完成定义、会话末检查清单包含证据记录、失败路径不得宣称完成。这套评估集是 skill 质量保障的核心它把可靠 harness 长什么样编码成了可自动判定的断言与run-benchmark.mjs的评估覆盖统计配合构成 skill 自身的回归测试体系。skill 自身的构建方法论原文档特别说明harness-creator是按照 Anthropic 官方的skill-creator元技能开发的——一个用于创建、测试、迭代 Agent skill 的结构化工作流提供草稿 → 测试 → 评估 → 迭代的循环并配套评估 runner、grader 与基准可视化器。这解释了为什么本 skill 会同时拥有模板、脚本、参考文档和评估集四层结构模板保证产出的一致性脚本让流程可执行参考文档沉淀领域知识评估集则让每次迭代都有可量化的验收标准。在 README.md 的 Status 一节可以看到迭代的开放性已完成最小脚手架、五子系统验证、HTML 评估报告、结构基准报告、10 个评估用例、常见技术栈验证检测而未完成项是可选的真实前后 Agent 会话回放——这正好呼应了 SKILL.md 中结构评分不能替代真实会话测试的边界声明。边界与适用前提最后是 skill 的职责边界README.md 的 Boundaries 一节它服务于 harness engineering不负责模型选型、孤立地调 prompt、聊天 UI 设计或通用应用架构项目特定的事实应保留在目标仓库中而不是写进 skill 本身。使用时的前提也很明确npx skills add需要本机有 Node 环境所有.mjs脚本仅依赖 Node 内置模块可在拷贝 skill 目录后于任意仓库直接运行审计与基准给出的是结构性评分真实可靠性仍须以代表任务上的 Agent 前后对比为准。赞分享【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载相关推荐harness-creator 实战用 learn-harness-engineering 内置技能为 AI 编码 Agent 构建、审计与改进 Harnessharness creator 实战用 learn harness engineering 内置技能为 AI 编码 Agent 构建、审计与改进 Harneslearn-harness-engineering 内置 Skills 体系与 harness-creator为 AI 编程代理构建生产级 Harness 的实战指南learn harness engineering 内置 Skills 体系与 harness creator为 AI 编程代理构建生产级 Harness 的深入解析 learn-harness-engineering 的 harness-creator面向 AI 编程 Agent 的生产级 Harness 工程技能深入解析 learn harness engineering 的 harness creator面向 AI 编程 Agent 的生产级 Harness 工程技上一篇3步打造专属操作体验Godot输入映射系统完全指南下一篇Assistant-UI LangGraph集成企业级AI工作流的架构融合与可视化方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
 用法与选中状态机制深度解析)
