Harness Engineering操作手册improve-harness与repository-review两大Playbook详解【免费下载链接】harness-engineering Ryan Lopopolo’s anthology, field guide, and agent context bundle for harness engineering项目地址: https://gitcode.com/gh_mirrors/har/harness-engineeringHarness Engineering 是 Ryan Lopopolo 提出的为 AI 编码代理塑形环境的工程实践而本仓库 harness-engineering 将其沉淀为可直接执行的操作手册。本文带你快速读懂其中两大核心 Playbookimprove-harness针对单一任务的闭环改进与repository-review面向整个仓库的广度诊断帮你判断该在何时使用哪一套流程。先搞懂什么是 Playbook仓库把 Playbook 定义为anthology文集的应用层它把散落在文档中的论证和案例整理成人类和代理都能照着执行的操作步骤见 playbooks/README.md。仓库内置了三类作业场景Playbook 与场景一一对应你的作业目标对应工具入口文件围绕一个有边界的代表性任务改进 harnessImprove One Harnessed Jobplaybooks/improve-harness.md审查多个任务旅程与仓库内的所有权边界Repository Reviewplaybooks/repository-review.md对比条件或测量随时间变化的效果Evaluate the Harnessevals/README.md⚠️ 注意这两份 Playbook 是编辑综合产物不是 Ryan 本人发布的原文仓库也不包含端到端的应用记录。使用时应遵循目标仓库自身的指令与授权详见 playbooks/AGENTS.md。一、improve-harness单任务闭环改进手册核心定位在固定不变的 worker模型 编码代理下针对一个有边界、有代表性的真实任务跑通一条完整的操作闭环基线 → 最早断点 → 最小责任方干预 → 原生验证 → 全新重跑 → 保留 / 修订 / 移除这个循环的价值在于一次完整的 pass 就能证明任务在观察条件下闭环同时暴露下一个缺失的边界。第一步圈定范围与授权Playbook 开宗明义上下文包对目标系统是只读补充。用户的请求结果和授权范围说了算目标系统的指令、契约和当前状态提供本地真相。关键红线新手最容易踩的坑❌ 不扩大权限、不重新定义验收标准、不为通过而削弱评分器❌ 不把未经验证的自报行为提升为策略✅ 只选小到能重跑、重要到能验证假设缺口的真实任务让代理变得更好这种无边界的口号无法进入循环第二步记录任务契约在改动 harness 之前先写下一张契约清单目标与版本、固定模型配置、代表性任务、可接受的结果、证明结果的证据、授权边界、预算与停止条件、疑似的 harness 缺口。 精髓在于真相永远留在它的权威所有者那里。Playbook 只记录如何到达真相不应创建一套能自我印证的私有 fixture 语料。第三步六步闭环详解观察基线在安全且授权时跑一遍全新的轨迹。记录可观察证据而非摘要——结果是否被接受、代理产出了什么证明、哪些上下文被检索到、哪些能力被正确调用、人在哪里做了人肉中继、重试与延迟有多少。定位最早失败的交接点沿症状向上游追溯直到找到一个能塑造未来运行的权威所有者。然后对缺口分类这决定了后续路线Context上下文缺失/过期/过载Capability工具不可发现、不可调用、不可解读Domain ownership多个竞争表示无类型/API/状态机拥有该不变量Authority能力与权限混淆缺少审批或审计边界Proof检查只证明内部代理指标用户断言未被测试Worker limitation环境清晰时行为仍不可靠——但一次失败轨迹不能定性为模型问题只能留作候选假设陈述一个干预假设用 If … then … because … 句式在最早的责任方上做最小可逆的改动并事先写下支持证据与削弱证据各是什么。实现并在声明边界验证保持 diff 足够窄。验证分两层——先跑目标系统原生的检查保护内部契约再走一遍用户/运维旅程建立可接受结果。跑一条全新轨迹用相同模型、相同配置、实质等价的外部状态、全新会话重跑。注意确认干预确实被检索或调用了——一次成功的结果对一条轨迹从未使用的工具不构成任何证据。保留、修订或移除若新运行闭环成功、干预确实被使用、证据符合假设机制、收益配得上维护成本就暂时保留若接口难用就修订若它只是噪音或重复了更好的所有者就移除。决策记录到目标系统维护架构/运维历史的地方。最后附一张紧凑的结果记录模板任务、基线证据、干预机制、对比维度、最终决策与复盘条件。这份记录支持的是对该任务在观察条件下的有界断言而不是普适的因果结论——后者要交给 evals/README.md 的评估流程。二、repository-review仓库级广度诊断手册核心定位问一个总问题——一个有能力的编码代理能否不用人当中继恢复真实任务、做出连贯的修改、证明结果、并安全地操作与 improve-harness 不同这是一次宽幅体检它不下场修而是沿代表性旅程收集证据给出按后果排序的发现清单。体检前先定审查契约记录目标版本、固定模型配置、声称覆盖的任务、各边界的验收结果、所需证明、审查权限与访问范围、排除项以及高风险操作的停止条件。⚠️ 重要原则审查可以诊断缺失的所有者、提出改动建议但检查权限不等于修改权限。九大检查维度沿轨迹审查工作Playbook 给出 9 个贯穿请求 → 结果的问题任务如何被分类根指引如何路由到领域上下文能否找到概念的所有者能否不靠人复现并观察行为实现是否保住一个领域模型和一个事实源证明是否在正确的边界上能否处理评审、CI、冲突与交付哪些操作需要人类判断结果是否为下一次运行留下持久改进其中明确要求静态检查必要但不充分声称端到端可操作时至少要跑通一条真实旅程。六大所有权边界逐项过边界核心问题配套论题️ 上下文与路由短小的根地图能否让代理按需取到架构、依赖姿态、runbook而不必预载全库docs/just-in-time-context/ 能力与工具工具能否被发现、调用、解读、修复并在真实系统验证docs/tool-legibility/️ 领域与架构版本、清单、标识符、UI 状态、发布产物是否各有一个权威表示docs/domain-modeling/✅ 执行与证明每条绿测试映射到哪个断言用户边界证据是否独立收集docs/proof/ 依赖与供应链每个重要依赖它提供什么能力凭什么信任被移除后哪些义务进了仓库docs/durable-systems/dependency-ownership.md 交付与授权是否部署 CI 验证过的不可变产物能力与审批是否分离docs/authority/特别值得新手留意的是比例性Proportionality原则每个 harness 组件都要交代它防的是哪个已观察到的失败、维护者是谁、正常循环耗时多久——优先选择能覆盖真实失败模式的最小系统。控制太多并不等于更安全一个有大量控制的仓库可能比几个边界清晰的仓库更难维护、更不安全。如何写发现Findings发现要按后果排序每条点名五件事处于风险中的行为或不变量具体证据与所有权边界为什么现有证明没抓住它在所有权边界上的根因修正修正后应移除的冗余机制最后记录值得保留的坚实基础、实际跑过的旅程、审查的已知局限。就绪阻断项Red Flags出现以下证据时仓库不满足其声称的作业能力静默数据丢失可绕过已验证产物的发布路径凭证携带实质意外权限无门禁也无恢复路径的敏感操作文档夸大已强制的保证没有任何办法证明用户可见的结果。每个阻断项只有两条出路缩小声称或建起缺失的边界。三、怎么选两大 Playbook 的使用关系宽幅体检repository-review │ 选出按后果排序的一条发现 ▼ 单任务闭环improve-harness │ 需要跨条件/跨时间的因果断言 ▼ 对比评估evals/只做一件事你观察到一条轨迹在某个交接点失败了 → 直接进 improve-harness一次闭环就能见效。先做体检接手一个陌生仓库想知道代理今天能干什么、哪里需要人肉中继、风险堆在哪 → 先用 repository-review 出诊断再挑一条发现进入单任务闭环。要下结论想证明某干预确实有效且可推广 → 单次前后对比不够转 evals/README.md那里要求固定 worker、环境对等、条件盲评与多次重复。快速上手清单克隆仓库只读使用即可git clone https://gitcode.com/gh_mirrors/har/harness-engineering把你的编码代理指向本仓库加上目标系统入口 AGENTS.md 会自动路由到相关论题与 Playbook学原理从 README.md 读起再翻 docs/README.md 的十二条论题索引动手时先读目标系统的指令再按上文选 Playbook全程遵守检查权限 ≠ 修改权限用完把发生了什么记下来发现 Playbook 的疏漏请报告修订需单独授权 Harness Engineering 的核心信念是把组织的过程数据变成上下文与工具让判断能够累积。而这两份 Playbook就是让这份信念可执行的那两个抓手。【免费下载链接】harness-engineering Ryan Lopopolo’s anthology, field guide, and agent context bundle for harness engineering项目地址: https://gitcode.com/gh_mirrors/har/harness-engineering创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考