关于 harness-engineering
面向自主 Agent 工作流设计者的工程指南，说明如何设置 Agent 的可编辑范围、反馈、持久状态、回滚和审批边界。重点是通过锁定评估标准、耐久日志和明确治理规则，支持可审计的长时间运行。
主要功能
- 01划分锁定、可编辑和人工控制范围
- 02设计快速且难以操纵的反馈循环
- 03通过持久日志保存运行状态
- 04加入新颖性检查与复杂度裁剪
- 05设定回滚、监控和人工审批规则
适用场景
- 01构建自主研究或实验循环
- 02让后台 Agent 安全准备 PR
- 03防止 Agent 修改评估标准以获取好成绩
- 04保障长时间运行任务在上下文压缩后恢复
安装
复制下面的命令，在终端中运行。
npx skills add https:/安装后在 Claude Code 中输入/harness-engineering确认已加载。
详细介绍
Harness Engineering
Harness 工程旨在为 Agent 设计周边控制系统：Agent 可以编辑什么、如何接收反馈、在哪里写入状态、如何从故障中恢复，以及谁可以批准不可逆操作。Harness 决定了一次有用的 Agent 会话，与一个无需频繁人工提示、可连续运行数日且不会偏离目标的自主循环之间的差别。
何时启用
在以下情况下启用此技能：
- 构建自主研究或实验循环
- 设计具有锁定指标以及可编辑代码或内容的 Agent 环境
- 创建可生成 PR 或在后台运行的 Agent
- 评估 Agent 是否可以在不频繁接受人工提示的情况下安全运行
- 在 Agent 工作流中添加新颖性检查、消融、剪枝、回滚或持久化日志
- 防止 Agent 钻基准测试的空子、弱化评分标准，或在上下文压缩时丢失状态
对于由其他技能负责的相关工作，请勿启用此技能：
- 不涉及自主控制界面的一般质量门禁、回归测试套件或结果指标：
evaluation。 - Harness 工具的工具架构、响应格式和恢复错误：
tool-design。 - 项目层面的任务与模型适配、管线结构和成本规划：
project-development。 - 远程沙盒、预热池和托管会话基础设施：
hosted-agents。
核心概念
Harness 边界
将 Agent 与其运行环境分开。Agent 提出操作；Harness 定义允许操作的范围、反馈、持久化和晋级规则。
使用四类操作界面：
| 操作界面 | 示例 | 规则 |
|---|---|---|
| 锁定 | 评估指标、评分标准、验证脚本、合并策略 | Agent 可以读取并提出修改，但不能用修改后的规则给自己打分 |
| 可编辑 | 技能草稿、实验文件、提示词、测试中的配置 | Agent 可以在循环期间修改 |
| 仅追加 | 结果日志、研究线程、否决的想法 | Agent 可以追加，但不能改写 |
| 人工控制 | 合并、生产环境部署、凭证、破坏性操作 | 需要人工明确批准 |
紧密反馈循环
当反馈快速、明确且难以钻空子时，自主运行才能奏效。Karpathy 的 autoresearch 是最简模式：一个可编辑文件、一个锁定的评估文件、固定的墙钟时间预算、一个标量指标、Git 回滚，以及持久化结果日志。关键不在于每个 Harness 都需要一个指标，而在于模糊的反馈会导致模糊的自主行为。
对于从开放式研究到技能构建的工作，应以锁定的评分标准、确定性的结构检查、来源可追溯性和人工审核阈值取代标量指标。
持久化状态
长时间运行的 Agent 必须将状态外化。将计划、来源队列、结果、故障和交接记录存入文件，以便后续 Agent 无需依赖聊天记录即可恢复工作。Prime Intellect 的自主 nanoGPT 工作展示了持久化草稿区和 THREAD.md 风格日志在恢复、监控和审计方面的价值。
使用仅追加日志记录：
- 尝试过什么
- 哪些内容有所改进或失败
- 保留、丢弃候选项或将其转交审核的原因
- 检查过哪些上游来源
- 下一个 Agent 应执行什么操作
搜索纪律
Agent 往往会利用最近的操作界面、叠加复杂性，并减少剪枝。应添加明确的搜索规则：
- 按计划刷新上游来源。
- 在投入大量预算前，必须进行新颖性检查。
- 保留被否决的尝试，避免重复发现。
- 当堆栈中有多个新增项时，进行逐项留一剪枝。
- 在质量相同时，优先奖励简化。
- 在晋级前进行独立验证。
机制注册表
对于从研究到技能的系统，应将已接受的机制与说明文字分开跟踪。机制记录应包含稳定的 mechanism_id、owning_skill、status、激活场景、行为变化、证据和失效模式。新颖性门槛应先与此注册表比对，再检查更广泛的语料重叠，因为关键词重叠只能发现过时的措辞，而机制比对才能发现真正的重复。
治理
自主 Agent 可以准备 PR，但必须明确治理规则。它们可以起草变更、运行检查并撰写 PR 摘要。除非用户已明确授权执行特定操作，否则它们不得在未经人工批准的情况下合并、部署或推送。
详细主题
类 Autoresearch 循环
针对稳定的评估器优化产物时，使用此模式：
read locked context -> choose hypothesis -> edit allowed surface -> commit/checkpoint
-> run evaluator -> log result -> keep if better -> discard or rollback if worse
-> repeat
必要属性：
- 评估器位于可编辑范围之外。
- 反馈频率足够固定，以便比较不同尝试。
- 失败的尝试会留下审计记录。
- 回滚成本低。
- Agent 对崩溃和超时有处理策略。
从研究到技能的循环
将来源转化为技能变更时，使用此模式：
discover -> retrieve -> gate -> score -> extract mechanism
-> map to existing or new skill -> draft proposal -> validate structure
-> prepare PR -> human review
锁定的评估器由来源评分标准、技能变更评分标准、结构检查和审核者批准组成。可编辑产物是拟议的技能增量。
抵御指标投机
假设优化型 Agent 会摸透测试框架。应防范以下情况：
- 修改评估代码或评分标准后，再用新版本进行自我批准
- 添加讨好评审者、却损害技能激活效果的冗长内容
- 引用未检索到的来源
- 优化汇总分数，却未能满足关键维度的要求
- 在日志中隐去失败结果
缓解措施：每次运行时锁定评分标准，报告各维度的分数，要求提供来源检索证据，保留被拒绝的尝试，并将治理变更交由人工审核。
监控 Agent
长时间运行的任务可使用监控 Agent，但除非明确要求，否则应限制其只读报告。监控输出应报告：
- 当前最佳候选项
- 正在运行的任务或草稿
- 上次上游刷新时间
- 失败或过时的循环
- 日志与声称状态之间的差异
- 下一步操作和阻碍因素
实用指南
测试框架设计检查清单
- 用一句话定义目标。
- 确定锁定、可编辑、只追加和由人工控制的范围。
- 选择反馈机制：标量指标、评分标准、确定性测试、人工审核，或其组合。
- 定义保留、丢弃、崩溃、超时和审核状态。
- 在循环开始前创建持久化线程日志。
- 为长时间运行的循环添加来源刷新、机制注册表新颖性检查和裁剪规则。
- 明确 Agent 无需询问即可执行的操作，以及需要批准的操作。
- 使用一个已知良好和一个已知不良的产物验证测试框架。
文件布局
research-run/
THREAD.md
sources/
queue.md
evaluations/
proposals/
logs/
results.tsv
rejected.md
drafts/
只追加的机器可读日志使用 TSV 或 JSONL。交接内容和面向审核者的摘要使用 Markdown。
示例
示例 1：锁定指标
Agent 优化 train.py，但数据加载和评估由 prepare.py 负责。Agent 可以编辑模型，但不能更改指标。失败的实验会被记录并回滚。
示例 2：锁定评分标准
Agent 评估一篇新的 Anthropic 或 OpenAI 工程文章，但本次运行使用的来源筛选评分标准已锁定。如果来源通过评估，Agent 会起草技能提案。它不能降低评分标准的门槛来接纳该来源。
示例 3：自动创建 PR，不自动合并
Agent 通过来源、技能和结构检查后，会准备分支和 PR 正文。PR 会说明尚未解决的风险，并等待人工批准合并。
指南
- 在开始循环前锁定评估器。
- 将可编辑范围限制在足够小的范围内，以便可靠地查看差异。
- 在上下文压缩抹去状态前，写入持久日志。
- 报告各维度的分数，而不只是汇总分数。
- 要求先检索来源，再进行引用。
- 为广泛搜索设置新颖性门槛，并为复杂技术栈设置精简门槛。
- 在质量相当时，优先选择简化方案。
- 将 PR 准备工作与合并权限分开。
- 使用新旧评估器重新验证测试框架的变更。
- 将停止的自主循环视为测试框架故障，而非 Agent 的性格问题。
注意事项
- 评估器可变：如果 Agent 可以编辑指标，它可能会优化基准测试，而不是完成任务。在运行期间锁定评分标准和评估代码。
- 仅依赖聊天记忆：长时间运行时，如果计划只存在于对话记录中，上下文压缩后就会失败。从一开始就写入线程日志和结果文件。
- 没有丢弃记录：没有被拒绝尝试的日志，Agent 就会重复失败的想法。保留足够详细的失败记录，避免重复探索。
- 复杂性累积：Agent 会不断叠加变更，却很少移除变更。要求进行精简轮次，并奖励在质量相当时进行简化。
- 过早宣称新颖性：Agent 可能会把重新组合的内容标记为新颖。在宣称新颖之前，应与现有仓库技能、来源队列和被拒绝日志进行比较。
- 监控报告失实：监控 Agent 可能会总结过时或不一致的状态。要求它们引用支撑声明的文件或日志。
- 人工审批含糊：“准备 PR”不等于“合并 PR”。在测试框架中明确审批边界。
- 易变来源漂移：快速发展的实验室声明很快就会过时。在参考资料中注明证据日期，并安排重新验证。
集成
此技能可与以下内容配合使用：
- evaluation - 评分标准和质量门槛提供锁定的反馈界面
- advanced-evaluation - 成对比较和偏差缓解可改进提案审核
- filesystem-context - 持久日志、草稿区和线程文件可保留状态
- multi-agent-patterns - 研究者、验证者、监控者和撰写者 Agent 需要隔离的上下文
- tool-design - 测试框架工具必须提供清晰的契约和错误恢复机制
- project-development - 基于文件的流水线和任务与模型适配分析可让循环保持简单
- hosted-agents - 后台执行需要沙箱、快照和审批边界
参考资料
内部参考资料：
researcher/README.md- 实现仓库原生的研究到技能运作系统时阅读researcher/rubrics/harness-change.md- 评估 Agent 测试框架的变更时阅读researcher/runbooks/autonomous-research-loop.md- 运行来源到技能的循环时阅读
外部资源：
- Karpathy
autoresearch- 具有锁定评估机制的受限自主实验循环 - Prime Intellect autonomous nanoGPT speedrun - 持久草稿区、交接、监控和自主运行故障模式
- AlphaEvolve 和 FunSearch - 将大模型生成的候选方案与系统化评估器配对
- HELM 和 LM Evaluation Harness - 透明、可复现的评估基础设施
技能元数据
创建时间：2026-05-14 最后更新：2026-05-15 作者：Agent Skills for Context Engineering Contributors 版本：1.1.0