一句话总结Harness 不是让 AI 变得更聪明而是让 AI 的产出从看运气变成可预期。一、先搞懂Harness 到底是什么1.1 一个比喻客厅里来了一条龙想象你的客厅里突然来了一条龙。它聪明、强大能喷火也能驮着你飞。但它也是黑盒的、不可控的——有时候温顺有时候会把你的沙发烧了。Harness马具/缰绳就是驾驭这条龙的系统马鞍、缰绳、护具加上一个懂龙的骑手。在 AI 领域龙 大模型GPT-4、Claude、Qwen 等Harness 围绕 AI Agent 搭建的完整工作环境骑手 人类工程师负责设计规则、构建反馈回路1.2 Harness 的五大核心部件一个完整的 Harness 包含五个子系统你可以把它们理解为驯龙的五件套子系统通俗解释对应文件/机制Instructions指令给 AI 的操作手册告诉它做什么、按什么顺序做AGENTS.md、CLAUDE.mdState状态记录做到哪了别让重要信息只存在 AI 的概率云里progress.md、feature_list.jsonVerification验证测试通过才算完成AI 不能自己说好了单元测试、Lint、CIScope范围一次只做一件事不贪多、不半途而废功能清单、任务边界Session Lifecycle会话生命周期每次开始先初始化结束留干净现场init.sh、Git 提交规范核心原则模型决定写什么代码Harness 决定什么时候写、在哪里写、怎么验证。二、国内值得借鉴的 Harness 案例案例 1OpenCompass —— 大模型评测的体检中心出品方上海人工智能实验室上海AI实验室核心思路把模型评测做成标准化 Harness让评测从拍脑袋变成自动化体检。OpenCompass 是国内最权威的大模型评测体系之一它的 Harness 设计非常值得借鉴全能力评估覆盖 50 评测数据集从知识、推理到代码、安全多模型兼容支持 HuggingFace、OpenAI API、本地 Ollama 等 50 模型本土化优势内置 C-Eval、CMMLU 等中文特色评测维度分布式高效千亿参数模型完全评测最短仅需 3 小时可借鉴点把评估标准和执行流程彻底分离标准写在配置里执行交给自动化 Harness。案例 2Datawhale self-harness —— 最小化 Harness 教学范本出品方Datawhale 开源社区核心思路用miniMaster项目展示 Harness 的最小可行实现。这是一个专门教 Harness Engineering 的开源教程配套了一个最小化的类 Claude Code 系统。它的架构设计非常清晰三层嵌套循环Planner-Agent全局调度→ Executor-Agent执行→ Validator-Agent评估动态工作记忆把规划记忆、执行记忆、验证记忆分开管理既能保留上下文又能压缩旧轨迹技能按需加载启动时只给菜单需要时才加载完整食谱可借鉴点Harness 不需要一开始就很复杂30 行代码的循环 几个约束规则就能起步。案例 3“万能视频下载总结器”—— 个人开发者的 Harness 实战核心思路在真实项目中沉淀文档、控制会话、引入验证。这是一个用 AI 从零开发的全栈项目开发者完整实践了 Harness 的四个阶段方案设计阶段先自己想清楚核心方案写成文档再让 AI 补充开启 Plan Mode计划模式而非直接写代码编码开发阶段给 AI 配置联网能力MCP每完成一个功能就沉淀总结文档并提交 Git测试验证阶段让 AI 自己打开浏览器测试人工只在 AI 卡住时介入纠偏功能扩展阶段用 SubAgents 并行开发独立需求每个功能完成后作为检查点可借鉴点Harness 不是完全放手不管而是把人的精力用在AI 搞不定的关键节点。案例 4Higress —— 网关层的 Agent 管控实践核心思路在 API 网关层构建 Harness管控 Agent 的行为边界。Higress 团队提出了Harness 驾驭工程正成为新的护城河的观点强调状态外置把 TODO 列表从对话里挪到外部文件tasks.json防止被覆盖、遗忘独立评估Generator生成器不允许说完成了只能说我做了哪些变更请 Evaluator评估器验收分级验证从 lint、单测到 Playwright 真实点击流程层层把关可借鉴点把完成宣告权从 AI 手里收回来是 Harness 最能拉开差距的设计。三、从零搭建你的 Harness 工程三阶段渐进式建议不要一上来就搭完整的 Harness按阶段逐步升级。每个阶段投入 30 分钟就能看到明显效果。 Phase 1文档约束层30 分钟上手立即可用目标让 AI 从瞎猜变成按手册办事。做法在项目根目录放 4 个文件。文件 1AGENTS.mdAI 的操作手册# AGENTS.md ## 项目简介 这是一个基于 Next.js 14 PostgreSQL 的任务管理 Web 应用。 ## 快速导航 | 你想做什么 | 去哪里看 | |-----------|---------| | 了解系统架构 | docs/architecture/overview.md | | 了解编码规范 | docs/conventions/README.md | | 了解当前任务 | docs/plans/current-sprint.md | ## 硬性规则 1. 依赖方向types/ → lib/ → services/ → app/ 2. 禁止 console.log使用结构化日志 3. 单文件 ≤ 300 行 4. 新功能必须有测试 5. API 调用使用统一的 apiClient文件 2feature_list.json功能清单与状态{features:[{id:F01,name:用户登录功能,status:done,evidence:tests/auth.test.ts 通过},{id:F02,name:任务创建接口,status:in_progress,notes:已完成基础 CRUD待加权限校验},{id:F03,name:任务列表分页,status:todo}]}文件 3progress.md会话进度日志# 会话进度日志 ## 2026-08-14 会话 - 已完成F02 的任务创建基础接口 - 待验证权限校验逻辑 - 已知问题无 - 下次会话建议从 F02 的权限校验开始文件 4init.sh启动校验脚本#!/bin/bash# init.sh - 每次会话开始时运行echo 安装依赖...npmciecho 运行健康检查...npmrun lintnpmrun type-checknpmtest----passWithNoTestsecho✅ 环境就绪可以开始工作效果对比Anthropic 做过对照实验同一个模型同一个 prompt没有 Harness 时 20 分钟产出不能用有完整 Harness 时 6 小时产出可运行的游戏。模型没变变的是环境。 Phase 2反馈验证层让 AI 自己检查自己目标AI 不能自己说完成了必须有可运行的证据。做法引入三级验证机制。轻量验证每次代码变更后自动跑// package.json 中添加scripts:{verify:npm run lint npm run type-check npm run test:unit}中等验证功能完成时跑e2e 测试关键页面流程配置文件校验构建检查重量验证合并前跑Playwright 真实浏览器点击截图对比网络请求与错误日志检查关键设计把完成宣告权从 AI 手里收回来。## 完成规则写入 AGENTS.md Generator写代码的 AI不允许说完成了。 它只能说我做了以下变更请 Evaluator 验收。 Evaluator 验收通过的标准 - [ ] npm run verify 全部通过 - [ ] 新增代码有对应测试 - [ ] 手动检查关键路径正常 Phase 3状态与技能层完整 Harness目标跨会话保持连续性AI 能按需加载知识。1. 状态外置别让记忆只存在概率云里AI 的上下文就像鱼的记忆——聊着聊着就忘了或者幻觉出根本没做过的事。解决方案所有重要状态写到磁盘上。project-root/ ├── memory/ │ ├── session_log.md # 每次会话记录 │ ├── task_graph.json # 任务依赖图 │ └── retry_archive/ # 失败重试记录每次 AI 开始工作前先读取这些文件结束后必须更新。2. 技能按需加载给 AI 一本工具书不要把所有知识都塞进系统提示词里又贵又慢用技能文件夹按需加载skills/ ├── git_workflow/ │ └── SKILL.md # Git 规范、分支策略、提交格式 ├── code_review/ │ └── SKILL.md # 代码审查清单 ├── seo_audit/ │ └── SKILL.md # SEO 分析步骤 └── api_design/ └── SKILL.md # RESTful API 设计规范加载机制启动时只扫描技能名称和简介注入系统提示几十 token成本极低执行时AI 确定需要某个技能后调用load_skill工具才把完整内容加载进上下文3. 子 Agent 分工上下文隔离复杂任务不要一个 AI 从头到尾做完——上下文会臃肿表现会下降。解决方案父 Agent 派生子 Agent。用户任务优化网站 SEO 并修复登录页的兼容性问题 父 AgentPlanner ├─ 子 Agent ASEO 优化独立上下文只加载 seo_audit 技能 └─ 子 Agent B兼容性修复独立上下文只加载 frontend 技能 子 Agent 完成后只把摘要结果传回父 Agent 中间过程读了哪些文件、试了哪些方案直接丢弃。四、30 分钟快速启动模板把以下文件直接复制到你的项目根目录立刻拥有一个 Phase 1 级别的 Harness 最小 Harness 文件结构your-project/ ├── AGENTS.md ← AI 的操作手册 ├── feature_list.json ← 功能清单 ├── progress.md ← 会话进度 ├── init.sh ← 启动脚本 └── src/ ← 你的代码 AGENTS.md 模板# AGENTS.md —— AI 操作手册 ## 项目概述 [一句话描述项目] ## 技术栈 - 前端[React/Vue/...] - 后端[Node.js/Python/...] - 数据库[PostgreSQL/MySQL/...] ## 目录规范 src/ ├── types/ # 纯类型定义不依赖任何层 ├── lib/ # 工具函数只依赖 types/ ├── services/ # 业务逻辑依赖 types/ 和 lib/ └── app/ # 路由和页面依赖所有层 ## 编码规则 1. 单文件不超过 300 行 2. 禁止 console.log使用 logger 3. 新功能必须写测试 4. 提交前必须跑 npm run verify ## 工作流 1. 开始工作前读取 feature_list.json 和 progress.md 2. 每次只做一个功能 3. 完成后更新 feature_list.json、progress.md运行验证 4. 验证通过后才能标记为完成 feature_list.json 模板{version:1.0,features:[{id:F01,name:示例功能,status:todo,priority:high,acceptance_criteria:[用户可以通过界面创建任务,任务保存到数据库,创建成功后显示提示],evidence:}]} progress.md 模板# 项目进度日志 ## 当前会话[日期] - 正在处理 - 已完成 - 阻塞项 - 下次会话建议 ## 历史记录 init.sh 模板#!/bin/bashset-eecho Harness 初始化...# 1. 安装依赖echo 安装依赖...npmci# 2. 代码检查echo 运行代码检查...npmrun lint||truenpmrun type-check||true# 3. 测试echo 运行测试...npmtest----passWithNoTests||trueecho✅ Harness 初始化完成环境就绪五、三个常见避坑指南❌ 坑 1写一本百科全书式的指令文件错误做法把架构、规范、业务逻辑全塞进一个 5000 字的AGENTS.md。正确做法渐进式披露。给 AI 一张地图让它按需导航到具体文档。❌ 坑 2过度工程化控制流错误做法写大量 if-else 控制 AI 的行为试图预判AI 的每一步。正确做法Harness 必须是轻量的。每次新模型发布最佳 Agent 结构都会变。2024 年需要复杂管道的事2026 年一个提示词就能搞定。构建允许你随时丢弃昨天写的聪明逻辑的 Harness。❌ 坑 3让 AI 自己说完成了错误做法AI 写完后说我已经完成了你就信了。正确做法引入独立评估。Generator 只负责生成Evaluator 负责验收。验收标准必须是可运行的测试通过、构建成功不是看起来对。六、总结Harness 的本质Harness Engineering 的演进反映了 AI 开发范式的三次跃迁阶段核心关注比喻Prompt Engineering单次对话怎么问教龙说话Context Engineering多轮对话怎么管理记忆让龙记得刚才说了什么Harness Engineering整个工作环境怎么设计给龙造一个合适的马厩和跑道模型是龙Harness 是缰绳。龙够聪明了你把环境搭好剩下的它自己会搞定。参考资源Datawhale self-harness 开源教程Learn Harness Engineering 课程OpenCompass 官方文档
