Agent Harness 与 Skill 工程调研报告

一一、调研背景与目标

1.1 为什么要调研 Harness 和 Skill

随着 AI Agent 从"单轮对话"迈入"长时间自主运行"阶段，模型本身的智能已不再是瓶颈。业界观察到：

• 大多数 Agent 失败不是因为模型不够聪明，而是因为围绕模型构建的系统配置不当（HumanLayer 观察数百个 Agent 项目的结论）。
• 同一模型（Claude Opus 4.6）在不同 Harness 下的 Terminal Bench 排名可以从 #33 变为 #5（±4位）。
• LangChain 仅通过改进 Harness（模型不变），将编码 Agent 从 Top 30 提升到 Top 5（52.8% → 66.5%）。

这意味着 Agent 的核心竞争力正在从"选择更好的模型"转向"设计更好的 Harness"。Harness Engineering 正在成为与 Prompt Engineering、Context Engineering 并列的第三大工程范式。

与此同时，Skill 作为 Harness 中的渐进式披露机制，为 Agent 提供了按需加载领域知识和工作流的能力，解决了传统工具定义导致的 Token 膨胀和认知过载问题。

本次调研旨在系统梳理 Harness 与 Skill 的核心概念、设计原则、实践案例与演进方向，为团队后续的 Agent 开发和培训体系建设提供理论基础。

1.2 调研范围与资料来源

1.3 产品经理视角：如何阅读本报告

本章价值：如果你是产品经理，本章将帮助你建立评估 Agent 需求的三个核心认知框架，直接指导后续的 Skill 设计与 Hardness 分级。

本报告的核心读者是产品经理。你不需要理解 CDP 协议或上下文窗口的技术细节，但需要建立以下三个认知层次：

快速判断法则：一个任务是否适合 Agent 化，可用以下公式初步判断：

Agent 适合度 = 规则明确性 × 反馈可视化程度 × 错误可逆性

高适合度：代码审查、数据整理、文档生成、测试执行
低适合度：创意策划、情感沟通、战略决策、伦理判断

阅读路线建议：

• 30 分钟速读路线：本章 1.1 + 1.3 → 第二章 2.1 → 第五章 5.1+5.5+5.6 → 第九章 9.1+9.2
• 深度阅读路线：按章节顺序通读，重点关注带 PM 视角 标注的段落
• 动手实践路线：第五章 5.1（对比表）→ 5.5（五步法）→ 5.6（Hardness 分级）→ 第七章（案例）→ 第九章（清单）

1.4 前置概念速览

本节为非技术背景读者准备，快速建立阅读后续章节所需的基础认知。已有相关背景的读者可跳过。

A. 基础概念

AI Agent（AI 智能体）

不只是聊天机器人，而是能自主规划、执行任务、使用工具的 AI 系统。传统 ChatGPT 是"你问我答"模式，Agent 是"你下达目标，我自己拆解步骤、调用工具、执行验证"模式。本报告的核心主题 Harness 就是为 Agent 构建的"操作系统"。

LLM（大语言模型，Large Language Model）

Agent 的"大脑"，如 ChatGPT、Claude、GPT-4 等。LLM 擅长理解和生成文本，但自身不能执行代码、不能记住上次对话、不能访问实时信息。Harness 存在的核心目的，就是弥补 LLM 的这些缺陷。

Token（令牌）

LLM 处理文本的最小单位——大约 4 个英文字符 = 1 个 token，1 个中文字 ≈ 1-2 个 token。Token 既是计费单位也是性能瓶颈：输入越多 token，成本越高、速度越慢。报告中 Harness 的渐进式披露和 Skill 设计，本质上都是在做 Token 效率优化。

Context Window（上下文窗口）

LLM 一次对话能"看到"的最大信息量，类似你工作台的面积。例如 Claude 3.5 Sonnet 的窗口约 200K tokens。窗口满了，模型就会"忘记"早期内容。报告中 Harness 的上下文管理（压缩、重置、卸载）都在解决窗口有限的问题。

Context Rot（上下文腐化）

长时间对话中，上下文窗口被过期信息、冗余内容和错误尝试逐渐填满的现象。类比：就像办公桌堆满了纸，东西越多、找东西效率越低，最终严重拖慢 Agent 的工作质量。

B. 三大工程范式

两种互补视角理解范式关系：

演进视角（学科发展路径）：从单次优化（Prompt Engineering）升级到系统管理（Context Engineering）再到完整操作系统（Harness Engineering），三者是能力建设的递进阶段。

体系视角（Harness 内部结构）：Harness 作为系统层包含四个并列层级（编排层、记忆层、执行层、反馈层），其中记忆层内部包含提示词工程和上下文工程两个子学科。

两种视角不冲突：前者帮助理解学科的演进方向，后者帮助理解系统的内部组成。

Prompt Engineering（提示词工程）

通过精心设计输入指令来引导 AI 产生更好输出的技术。例如"请你扮演一个高级开发者"、"请一步步思考"等技巧。它是 Harness Engineering 的基础层，但只能优化单次对话的效果。

Context Engineering（上下文工程）

系统性地管理"给 AI 看什么信息"——在正确的时间提供正确的上下文。核心要素包括：指令（Instructions）、用户输入（User Input）、状态信息（短期记忆 + 长期记忆 + RAG 检索）、工具（Tools）和结构化输出（Structured Output）。它是 Prompt Engineering 的升级版，而 Harness Engineering 又是它的进一步升级。

Harness Engineering（线束工程）

本报告的核心主题。简言之，是围绕 AI 模型构建完整运行系统的工程实践。详见第二章的完整定义。

C. 技术概念

Sandbox（沙箱）

一个隔离的"安全屋"，Agent 在里面执行代码不会影响你的真实系统。类比：就像银行的防弹玻璃隔间——员工可以在里面操作现金，即使出错也不会影响外面的客户。

MCP（Model Context Protocol，模型上下文协议）

让 AI Agent 连接外部工具和服务的标准协议，相当于 Agent 世界的"USB 接口"。有了 MCP，Agent 就可以读写数据库、调用 API、访问文件系统等。它是报告中 Tool Definitions 的重要实现方式。

Trace（执行痕迹）

Agent 完成任务过程中每一步操作的详细记录，相当于飞机的"黑匣子"。包含每次模型调用、工具使用、结果反馈的完整日志。Trace 分析是改进 Harness 的核心数据来源。

Benchmark（基准测试）

标准化的测试套件，用来量化评估 Agent 的能力水平。例如报告中多次提到的 Terminal Bench 就是专门测试编码 Agent 的"统一考试"。

D. AI 技术概念

RAG（检索增强生成，Retrieval-Augmented Generation）

让 AI 在回答前先"查资料"——从知识库中检索相关信息再生成回答，避免"凭空编造"。是 Context Engineering 的核心技术之一，Harness 中的记忆与搜索组件就用到 RAG。

准确地说，RAG 是记忆层中上下文工程子学科的核心技术实现之一，负责在对话过程中动态检索相关知识补充 Agent 的上下文。而记忆层的另一个子学科——提示词工程——负责设计静态的系统提示和指令框架。两者共同构成了 Harness 的记忆能力。

Few-shot Learning（少样本学习）

给 AI 看几个"参考答案"，让它学会如何回答类似问题的技术。报告中 Harness 用它来校准评估器——给几个"好设计"和"差设计"的例子，让 AI 学会判断质量。

GAN（生成对抗网络，Generative Adversarial Network）

一种 AI 架构：一个网络负责生成内容，另一个网络负责判别质量，两者对抗式训练。报告中"评估分离"原则（第 4.3 节）借鉴了这一思路——生成 Agent 和评估 Agent 分工协作。

---

二二、核心概念定义

PM 阅读指南：本章建立 Agent 系统的核心词汇和概念框架。阅读后你将理解"Harness 是什么"、"Skill 如何工作"以及"Agent 与模型的本质区别"—— 这些是后续所有决策的认知基础。

2.1 Harness 的定义

核心公式

Agent = Model + Harness

Harness 是 Agent 中除了模型以外的所有部分，是围绕模型构建的系统层，负责流程编排、上下文管理、工具路由和资源配置。

更完整的视角：Agent 三要素模型

Agent 系统实际包含三个关键要素：模型（推理能力）、Harness（执行系统）、目标定义（成功标准）。仅有强大的模型和完善的 Harness 还不够——如果目标定义模糊，Agent 会陷入"不知道何时停止"的困境。因此 PM 的核心工作之一，就是确保 Agent 有清晰的成功标准和失败处理方案。

Agent 三要素中的 PM 决策点

PM 的核心价值：工程师负责实现 Harness，但 PM 负责定义"Agent 应该做什么"和"做到什么程度算成功"。模糊的成功标准是 Agent 项目失败的首要原因。

从运作维度来看，Harness 可以理解为一个四层架构系统：

• 编排层（Orchestration Layer）— 协调模型推理和工具调用的循环系统，是Agent的"神经中枢"
• 记忆层（Memory Layer）— 维持Agent的长期记忆和上下文管理，涵盖提示词工程和上下文工程
• 执行层（Execution Layer）— 工具执行、沙箱环境和资源管理，将模型决策转为实际操作
• 反馈层（Feedback Layer）— 验证、评估和持续改进，保障Agent输出质量

Harness 的组成

各方对 Harness 的理解

Harness 的作用

• 弥补模型缺陷：模型无法自行维护状态、执行代码、访问实时知识
• 提供运行环境：持久化存储、环境约束和反馈循环
• 编码先验知识：将人类的领域经验注入 Agent 行为引导
• 塑造可用系统：将模型的"峰值智能"转化为可用于实际工作的系统

2.2 Skill 的定义

Skill 是什么

Skill 是由 SKILL.md 文件及其关联资源组成的可复用 Agent 能力模块，包含专门的工作流程和领域知识，采用 YAML frontmatter + Markdown 指令的标准格式。

Skill 的核心特征

SKILL.md 格式规范

---
name: build-test-verify
description: "When the user asks to build, test, or verify code changes"
allowed-tools:
  - bash
  - read_file
  - write_file
---

# Build-Test-Verify Workflow

## Steps
1. Run the build command: `bun run build`
2. Execute tests: `bun test`
3. Verify no regressions...

## Error Handling
- If build fails, check...

三层结构：

1. 前向元数据（frontmatter） — 始终加载（5-10 行）
2. 完整指令（SKILL.md 正文） — 按需加载（匹配 description 时）
3. 辅助资源（脚本、文档、模板） — 被指令引用时加载

2.3 Harness 与 Prompt Engineering 的区别与联系

区别

联系

• 基础关系：Harness 的系统提示仍是 Prompt Engineering 的一部分
• 依赖关系：Harness 效果依赖良好的提示词设计（如结构化评分标准）
• 递进关系：先用 Prompt Engineering 探索，后用 Harness Engineering 规模化
• 互补关系：Prompt Engineering 优化单点，Harness Engineering 提升整体

2.4 Harness 设计的安全边界

本节价值：帮助 PM 在需求评审阶段快速判断任务的安全等级，避免将不适合自动化的场景交给 Agent。

Part A：任务适合度 × 安全等级矩阵

Part B：红线场景清单

🚫 红线场景（绝不完全自动化）：

1. 金融交易与资金转账
2. 医疗诊断和用药建议
3. 法律合同的最终签署
4. 未加密的个人隐私数据处理
5. 生产数据库的删除/修改操作
6. 涉及不可逆物理操作的控制指令

红线场景中 Agent 可以辅助（如起草合同、预分析数据），但最终决策和执行必须由人工完成。PM 在需求评审时应首先排除红线场景。

---

三三、Harness 核心组件

3.1 六大组件详解与四层架构映射

Harness 的六大组件与四层架构的映射关系如下：

• 记忆层 ← System Prompt（系统提示）+ Skills（技能）
• 执行层 ← Tool Definitions（工具定义）+ Sandbox（沙箱环境）+ Permission Model（权限模型）
• 反馈层 ← Hooks & Guardrails（钩子与护栏）
• 编排循环（Orchestration Loop）← 贯穿全四层，是驱动四层协作的中枢协调机制

注：编排循环不单独归属某一层，而是作为中枢驱动编排层、记忆层、执行层、反馈层的协同运作。

● = 主要归属层；↺ 贯穿 = 编排循环作为中枢驱动所有层的协同运作

1. System Prompt（系统提示）

分层、动态、可继承的指令体系，是 Harness 最基础的组件。

• 层级结构：Root CLAUDE.md → 目录级 CLAUDE.md → AGENTS.md → SKILL.md
• 核心职责：定义 Agent 的角色、行为规范、项目上下文
• 动态性：Agent 可在会话中编辑 AGENTS.md，Harness 自动重加载
• 设计要求：简洁（< 300 行，推荐 < 150 行），基于真实失败事件编写

PM 视角：系统提示是你能直接影响 Agent 行为的最主要杠杆。当 Agent 表现不符合预期时，首先检查系统提示是否清晰定义了任务目标、约束条件和输出格式。

2. Tool Definitions（工具定义）

为 Agent 提供与外部世界交互的能力接口。

• 通用工具策略：给 Agent 一台"计算机"（Bash + 代码执行），而非一套预定义工具
• MCP 集成：通过 MCP 服务器连接外部服务
• Skill 扩展：通过 SKILL.md 按需注入专用工作流
• 极简原则（Browser-use）：少量高质量原始接口 > 众多高级抽象

PM 视角：工具定义决定了 Agent “能做什么”。当你发现 Agent 无法完成某类任务时，可能不是模型能力不足，而是缺少对应的工具定义。PM 需要规划 Agent 应具备的工具清单。

3. Sandbox Environment（沙箱环境）

安全隔离的代码执行环境。

• 预装环境：语言运行时（Python、Node）、Git、测试框架 CLI、浏览器
• 安全隔离：Agent 生成的代码无法访问认证令牌，凭证与沙箱分离
• 按需扩展：并行多 Agent 无共享状态污染
• 容器即牲畜（Anthropic）：容器失败时无需修复，通过新配方重新初始化

PM 视角：沙箱确保 Agent 的试错不会影响真实数据和生产环境。有了沙箱保障，你可以放心给 Agent 更大的操作权限，这是提升 Agent 可靠性和自主性的基础设施。

4. Permission Model（权限模型）

控制 Agent 的操作边界和安全约束。

• 命令白名单：可自定义允许执行的命令
• 网络隔离：控制 Agent 的网络访问范围
• 凭证管理：Git 通过本地 remote 注入 token；OAuth 通过 MCP 代理存储 token
• 渐进式授权：根据任务需要逐步开放权限

PM 视角：权限模型回答“Agent 被允许做什么”。过于宽松的权限带来安全风险，过于严格则限制 Agent 能力。PM 需要根据业务场景定义合理的权限边界。

5. Hooks & Guardrails（钩子与护栏）

在模型调用或工具执行前后的拦截点，实现质量保障和安全防护。

• PreCompletionChecklistMiddleware：Agent 退出前强制验证（LangChain）
• LoopDetectionMiddleware：跟踪单文件编辑计数，防止"厄运循环"（LangChain）
• LocalContextMiddleware：启动时映射目录结构和可用工具（LangChain）
• 时间预算警告：注入时间剩余提示，防止 Agent 超时

PM 视角：钩子与护栏是 Agent 的“质量检查员”。当你担心 Agent 在某些场景下犯错（如删除重要文件、发送敏感信息），可以通过钩子实现自动拦截和人工审批。

6. Orchestration Loop（编排循环）

协调模型推理、工具调用、上下文管理的主循环。

• 核心职责：调用模型 → 解析输出 → 路由工具调用 → 收集结果 → 回传模型
• 上下文管理：支持压缩、片段化、缓存优化
• 错误恢复：检测异常并自动重试或重置
• 多 Agent 协调：管理子 Agent 的生命周期和通信

PM 视角：编排循环是 Agent 的“工作节奏”。它决定了 Agent 是一次性回答问题，还是能够自主规划、执行、验证、迭代。理解编排循环有助于你判断 Agent 是否具备完成复杂任务的能力。

概念区分：编排层 vs 编排循环

• 编排层（Orchestration Layer）— 层级概念：Harness四层架构之一，负责协调各层的整体运作
• 编排循环（Orchestration Loop）— 流程概念：Agent执行任务时“推理→决策→执行→反馈→推理”的循环过程

两者是包含关系：编排循环发生在编排层中，但其驱动力贯穿记忆层、执行层和反馈层。类比理解：编排层是“指挥中心”，编排循环是“指挥中心发出的工作流程”。

3.2 组件间的关系与协作

协作流程：

1. Orchestration Loop 是中枢，驱动整个 Agent 生命周期
2. System Prompt 为模型提供初始指令和上下文，Skills 按需扩展
3. 模型输出经 Hooks & Guardrails 拦截验证
4. 工具调用通过 Permission Model 鉴权后在 Sandbox 中执行
5. 执行结果回传至 Orchestration Loop，注入模型下一轮上下文

推荐实施顺序：System Prompt → Tool Definitions → Sandbox → Permission Model → Hooks & Guardrails → Orchestration Loop

---

四四、Harness 设计原则

PM 阅读指南：本章提供设计 Agent 系统的五大核心原则。你将学会如何"让 Agent 永不再犯同样的错误"（棘轮原则）、如何分离生成与评估（GAN 启发），以及如何合理控制 Agent 的操作权限 —— 这些原则直接影响产品的可靠性和安全性。

4.1 棘轮原则（Ratchet Principle）

每当发现 Agent 犯一个错误，就要花时间工程化一个解决方案，使 Agent 永远不再犯同样的错误。

实践循环：

1. 观察 Agent 失败（通过 trace 分析）
2. 识别根本原因（指令缺失、约束不足、反馈循环不足）
3. 工程化解决方案（修改 CLAUDE.md、添加钩子、创建 Skill）
4. 验证改进（重新运行 benchmark 或项目）
5. 永久编码到 Harness 中

关键原则：好的 CLAUDE.md 中的每一行都应该追溯到一个具体发生过的失败事件。

4.2 解耦设计：Brain / Hands / Session

Anthropic 在 Managed Agents 中提出了三层解耦架构：

设计灵感：参考操作系统的抽象设计 —— OS 通过进程、文件等通用抽象让程序独立于硬件。read() 命令对 1970 年代磁盘和现代 SSD 都有效。

关键优势：

• 实现独立升级（Harness 升级不影响 Session）
• 提高容错能力（单点失败隔离）
• 支持多种基础设施连接（本地/云/VPC）
• 性能提升：解耦后 p50 TTFT（Time To First Token）下降约 60%，p95 下降超 90%

Session (append-only event log)
  ↓
Harness (coordinates Claude + tool routing)
  ├→ Brain (Claude inference)
  ├→ Hands (Sandboxes & Tools)
  └→ Context Management (event querying & transformation)

4.3 评估分离（GAN 启发）

Anthropic 在长时间运行应用设计中提出：生成者与评估者必须分离。

问题根源：LLM 对自己的工作过于乐观（Self-Evaluation Bias）。

• 传统方式：单 Agent 自评估 → 模型过于乐观 → 质量停滞
• Harness 方式：分离评估 → 对生成工作更严苛 → 迭代质量更高

实现方式：

• 建立 4 维度结构化评分标准（设计质量、原创性、工艺、功能性）
• 用少量示例校准评估器（Few-shot learning）
• 用分数范围（1-5）而非二元判定
• 评估 Agent 拥有独立上下文，避免噪声积累

4.4 极简工具哲学（Bitter Lesson）

Browser-use 提出的核心理念：

"我们试图隐藏的 CDP 复杂性不是应该隐藏的东西。它们是应该让模型看到的东西。"

原理：源自 Richard Sutton 的 "The Bitter Lesson" —— AI 系统成功的关键是计算和数据，不是人类对系统的具体假设。模型已见过千万级别的 CDP token，比工程师更懂处理复杂性。

适用边界：这是一种"让模型处理复杂性"的工程哲学，而非普适用于所有场景的绝对真理。在安全敏感场景（金融交易、医疗诊断、隐私数据处理）中，适度封装仍然是必要的 —— 完全暴露原始 API 可能带来不可控风险。产品经理需要根据业务场景的安全等级，在"暴露复杂性"和"安全封装"之间找到平衡点。

实践对比：

为什么暴露原始 API 反而更有效？传统工程思维假设"我们比模型更擅长简化复杂性"，于是层层抽象封装。但现代 LLM 已经学习了百万级别的复杂系统讨论（Chrome 错误日志、API 文档、Stack Overflow 等），它们处理原始复杂信息的能力往往超过工程师的预期。过度简化反而限制了模型的能力，使其无法应对现实中的异常情况。这就是 Bitter Lesson 的启示：让模型直接面对复杂性，而非替模型做决定。

4.5 渐进式披露（Progressive Disclosure）

渐进式披露（Progressive Disclosure）是一种信息呈现架构模式，通过分层加载机制优化Agent的上下文管理：

• 第一层：元数据始终可见 — Skill 的 frontmatter（名称、描述、触发条件）始终加载，供 Agent 判断是否需要该能力
• 第二层：完整指令按需加载 — 当 Agent 决定使用某 Skill 时，才加载完整的工作流指令
• 第三层：辅助资源引用时加载 — 关联的文档、示例、配置文件仅在被引用时加载

核心价值：降低初始认知负荷，优化 Token 使用效率，同时确保 Agent 在需要时能获取完整知识。

三层设计：

1. 前向元数据（frontmatter）— 始终加载
   ├─ name: Skill 名称
   ├─ description: 何时使用（Agent 据此判断是否加载）
   └─ allowed-tools: 使用权限

2. 完整指令（SKILL.md 正文）— 按需加载
   └─ 仅当 Agent 匹配 description 时读取

3. 辅助资源（脚本、文档、模板）— 被指令引用时加载
   └─ 在 Harness 中声明调用方式

Token 效率对比：

• 传统工具模式：所有工具定义预加载（100-200 行/tool × N tools）
• Skill 模式：frontmatter 始终加载（5-10 行），完整指令按需加载
• 量化效果：节省 context 使用 20-30%（Anthropic 数据），避免 Agent 在工具选择上的认知过载

5.5 Skill 设计的五步法

本章价值：为产品经理提供从 0 到 1 设计第一个 Skill 的实操框架，可与 5.6 节的 Hardness 分级配合使用。

基于 Anthropic 官方 Skill Building Patterns 及实践社区经验，Skill 设计遵循以下五个步骤：

关键原则：好的 Skill 中的每一行指令都应该追溯到一个具体发生过的失败事件（棘轮原则在 Skill 层面的应用）。

Skill 质量门禁检查表

在发布 Skill 前，对照以下清单进行质量验收：

【结构质量】

• □ Frontmatter 控制在 5-10 行以内
• □ 完整 SKILL.md 在 150 行以内（L1-L2）/ 500 行以内（L3-L4）
• □ 无交叉引用其他 Skill（保持独立性）
• □ 触发条件（description）描述明确，不含歧义

【功能质量】

• □ 触发率 ≥ 90%（Agent 在应该使用时确实使用了该 Skill）
• □ 执行准确率 ≥ 95%（按指令执行，不偏离）
• □ 覆盖 3+ 个常见失败场景的错误恢复机制
• □ 包含自验证步骤（Agent 完成后能检查自己的工作）

【可维护性】

• □ 每条核心指令都能追溯到一个真实发生的失败事件（棘轮原则）
• □ 团队新成员能在 15 分钟内理解此 Skill 的目的和用法
• □ 有版本变更记录（修改原因 + 日期）

质量门禁不是一次性检查，而是持续迭代的过程。建议每月审视一次 Skill 库，淘汰触发率低于 50% 的 Skill，优化准确率低于 90% 的 Skill。

从 Hardness 分级到 Skill 设计

产品经理在评估需求时，应先判断任务的 Hardness 等级（见 5.6 节），再决定技术方案：

• L1 标准化任务：不需要写 Skill，直接用自然语言描述即可
• L2 协议化任务：需要简单 Skill（< 150 行），重点是定义触发条件和核心流程
• L3 推理化任务：需要完整 Skill + 验证脚本 + 错误处理机制
• L4 创造化任务：需要多 Agent 协作 + 企业级安全和合规框架

5.6 Hardness 分级方法论：从"复杂度"到"管理难度"

本章价值：建立可操作的四级分类体系，帮助产品经理在评估需求时快速判断实现复杂度和资源投入。

原报告提供了"从固定到动态、从集中到分布"等演进方向，但未将其构建为可操作的分类体系。以下四级 Hardness 框架填补了这一空白：

Hardness 分级与资源投入的对应关系

5.7 Skill 与 Hardness 的映射关系

本章价值：提供从需求评估到技术方案的决策路径，降低产品经理与工程师之间的沟通成本。

决策路径：产品经理在评估新需求时，先问"这个任务的 Hardness 等级是什么？"，再问"需要什么样的 Skill 来支撑？"—— 两个问题的答案共同决定了技术方案和投入资源。

ROI 估算公式：

Agent ROI = (节省人工时长 - 后续审核成本 - 系统维护成本) / 总投入成本

其中：
- 节省人工时长 = 单次任务人工耗时 × 月频率 × 自动化比例
- 后续审核成本 = L1-L2 可忽略；L3 需 10-20% 人工抽检；L4 需人工终审
- 系统维护成本 = Skill 更新频率 × 单次更新成本
- 总投入成本 = 初始开发人天 + 基础设施成本

从设计到评测的完整链路：第5.5-5.7节提供了Skill的设计方法论（五步法）、复杂度分级（Hardness L1-L4）和投资决策框架（ROI估算）。但一个关键问题仍未回答：如何系统性地验证Skill的设计质量并持续改进？ 下节引入Anthropic的Evals评测框架，完成从"设计→评测→迭代"的闭环。

5.8 Evals 框架与 Skill 质量评测体系

5.8.1 为什么需要系统性评测

第5.5节的质量门禁检查表为单个 Skill 的交付设定了质量关卡——从触发条件覆盖到错误处理完整性，逐项核查。然而，当企业的 Skill 库规模增长到 10+ 甚至数十个 Skill 时，单次的门禁检查已不足以保障整体质量。Skill 之间可能存在触发语义重叠、版本迭代可能引入回归、模型升级可能改变既有行为——这些系统性问题需要系统性方案。

这一挑战并非 AI 编程领域的独有问题。在机器学习领域，模型的质量保障早已从"人工抽检"进化到"标准化 Benchmark 评测"——没有 benchmark 的模型，无从谈起可靠性。Skill 作为一种结构化的 AI 工作流定义，同样需要建立可量化、可重复、可对比的评测体系。

Anthropic 的 Skill-Creator 项目正是这一理念的实践产物。该项目提供了一套完整的、经过大规模内部验证的评测框架，涵盖评测维度定义、基准对比方法、盲对比评估机制和防过拟合策略。其核心理念可以概括为：Skill 不是写完就结束的静态文档，而是通过结构化评测持续改进的可迭代资产。这一理念从根本上改变了 Skill 的生命周期管理方式——从"一次编写、长期使用"转变为"持续评测、数据驱动迭代"。

5.8.2 五维评测体系

这五个维度形成了一个完整的评估视角：触发精准度回答"Skill 在正确的时机被使用了吗？"；功能性能回答"Skill 按预期完成了任务吗？"；输出质量回答"最终交付物达到标准了吗？"；性能开销回答"成本可接受吗？"；可靠性回答"结果稳定可重复吗？"。五个维度从不同角度审视同一个 Skill，任何单一维度的优秀都不足以代表整体质量——一个触发精准但输出低质的 Skill，或一个输出优质但 Token 消耗过高的 Skill，都需要进一步优化。

5.8.3 盲对比评估：消除偏见的质量判断

传统的 A/B 测试中，评估者知道哪个版本是"改进版"，容易产生确认偏见（Confirmation Bias）——倾向于认为改进版"理应更好"。这种偏见在 Skill 评测中尤为突出：开发者花费数小时优化 Skill 后，很难客观承认改进版可能并不优于原版。

Anthropic 在 Skill-Creator 项目中引入了盲对比评估（Blind Comparison）机制，借鉴学术界"双盲同行评审"的方法论，从根本上消除评估偏见。其工作流程如下：两个 Skill 版本分别执行相同的测试用例；输出结果被标记为"A"和"B"，完全隐藏版本来源；独立的评估 Agent（即 Comparator Agent）从内容正确性、完整性、组织结构三个维度评分；最终仅基于质量判断胜负，期望通过率作为辅助证据而非决定因素。

这种机制的价值不仅在于消除偏见，更在于提供了一个可信的"谁更好"的判断标准。当迭代到第 5、第 10 轮时，改进的边际效益递减，开发者凭直觉已难以判断哪个版本更优——盲对比评估提供了客观的决策依据。

5.8.4 评测驱动的迭代循环

防过拟合机制：将测试用例分为训练集和测试集。改进时仅针对训练集的失败进行优化，用测试集验证泛化能力。最终选择测试集得分最高的版本——这是 ML 领域的标准实践，在 Skill 开发中同样适用。Anthropic 的实践表明：不采用这种分割的迭代，容易导致 Skill 对特定测试用例"过拟合"，而在真实使用中表现下降。

5.8.5 按 Hardness 定制评测策略

不同 Hardness 等级的 Skill 在评测重点、合格门槛和迭代方式上存在显著差异。以下框架与第 5.6 节的 Hardness 分级形成对照，为每个等级提供量身定制的评测方案：

5.8.6 Description Tuning：触发精准度的精细优化

Skill 的 description 是 Agent 决定是否触发该 Skill 的唯一依据——它对应渐进式披露的第一层（见 4.5 节）。当 Agent 面对用户请求时，它会扫描所有可用 Skill 的 description，选择最匹配的一个（或不选择）。因此，description 的质量直接决定了触发精准度：过于宽泛导致误触发，过于狭窄导致漏触发。Anthropic 基于大量实践提出了一套系统化的 Description Tuning 方法，核心是通过失败分析驱动针对性优化。

失败分析四分类：

Description Tuning 的核心原则：

• 使用祈使句式：Use this skill when...（而非描述性陈述）——Agent 更容易识别指令式的触发条件
• 聚焦用户意图而非实现细节——用户不关心底层机制，description 应反映用户的自然表述
• 长度控制在 100-200 字（硬限制 1024 字符）——简洁胜于详尽，过长的 description 反而降低匹配精准度
• 记住 Skill 之间存在"注意力竞争"——description 需要独特且易识别，避免与其他 Skill 的语义空间重叠
• 如果多次迭代后触发率仍不收敛，考虑从根本上重构 Skill 的定位——可能是 Skill 的职责边界不清晰，而非 description 措辞的问题

5.8.7 版本追踪与基线管理

每个 Skill 的迭代历史应被完整记录，形成可追溯的版本链。Anthropic 的实践中采用 history.json 记录每一轮迭代的关键数据：

v0 (基线)        → 期望通过率: 65%  → 状态: baseline
  ↓
v1 (优化 description) → 期望通过率: 75%  → 状态: won → 替代 v0
  ↓
v2 (补充错误处理)    → 期望通过率: 85%  → 状态: won → 当前最佳

何时触发新一轮迭代？Anthropic 建议关注以下触发条件：触发精准度下降超过 10%（可能因模型更新导致行为变化）、新增业务场景未被现有测试用例覆盖、用户负面反馈累计达到阈值、以及模型大版本更新后的例行重评估。

其中最后一点尤为关键：模型升级不等于"自动变好"。每次模型更新后都应重跑评测基线，用数据验证而非假设。Anthropic 的实践表明：即使模型能力整体提升，不合适的 description 仍会导致触发率下降——因为新模型对语义的理解方式可能发生了微妙变化。将"模型更新后重评估"纳入标准流程，是避免"升级即退化"的最有效手段。

5.8.8 与衡量体系的集成

宏观 + 微观的完整闭环：第 9.4 节定义了 Harness 层面的宏观衡量指标（任务完成率、Token 效率、失败分类等）和反馈循环频率（日/周/月/季度）。Evals 框架则提供了每个 Skill 层面的微观评测规则。两者共同构成从"单个 Skill 质量"到"整体 Harness 性能"的完整评测体系。PM 应同时关注两个层面：微观评测确保每个 Skill 持续改进，宏观衡量确保整体 Agent 性能持续提升。

---

五五、Skill 体系设计

PM 阅读指南：本章是报告的核心实操章节。你将掌握 Skill 与 Tool/MCP 的选择决策框架（5.1）、从 0 到 1 设计 Skill 的五步法（5.5）、以及评估任务复杂度的 Hardness 四级分级体系（5.6）—— 这些内容直接支撑后续的 Skill 设计与 Hardness 分级工作。

5.0 需求评估决策树：从需求到 Hardness 定级

本节价值：提供一个快速筛选工具，帮助 PM 在 5 个问题内初步判断需求的 Hardness 等级，为后续的 Skill 设计和资源评估提供起点。

使用说明：决策树仅为初步筛选工具。实际定级时还需考虑：数据敏感性、系统集成复杂度、团队技术储备。建议 PM 与工程团队共同完成最终定级。

5.1 Skill vs Tool vs MCP 对比

使用建议：

• Skill 用于重复出现的工作流和知识模块
• Tool 用于原子操作（API 调用、文件读写）
• MCP 用于与外部服务集成

Skill vs Tool vs MCP 决策流程

面对新需求时，按以下流程快速判断应该使用哪种方案：

决策流程应用示例

5.2 三层架构：CLAUDE.md → Skills → Agent Guides

Tier 1：Root CLAUDE.md（< 100 行，通用规则）

• 项目 WHY / WHAT / HOW
• 所有任务都需要的命令（bun vs npm 等）
• 指向 Tier 2-3 的索引

Tier 2：Skills（.claude/skills/）（按任务划分，100-500 行）

• build-test-verify（验证命令集）
• git-commit（提交规范）
• create-pull-request（PR 标准）
• core-conventions（代码风格）
• self-review-checklist（质量门禁）

Tier 3：Agent Guides（docs/agent-guides/）（深层参考，无限制）

• 完整命令清单
• 架构详解
• 约定俗成的完整文档

5.3 CLAUDE.md / AGENTS.md 最佳实践

核心原则

Less is More：

• 目标：< 300 行，优先 < 150 行
• HumanLayer 标准：< 60 行
• 原因：LLM 指令跟随能力在 150-200 条指令时达到可靠阈值

通用性约束：

• 仅包含应用于所有任务的指令
• 任务特定内容 → Skill 或 Agent Guide 中
• 避免添加条件规则（降低适用性，模型倾向忽视）

内容框架（Why / What / How）：

Why: 项目为什么存在，什么是重要的
What: 项目结构、依赖关系、主要组件地图
How: 通用的开发原则、构建命令、测试流程

常见错误

5.3.1 在 Harness 中设计人工审批节点

本节价值：当任务涉及中高风险操作时，需要在 Harness 中嵌入人工审批检查点。以下是三种常见的审批模式。

模式一：执行前审批

场景：Agent 准备执行不可逆操作（如：提交 PR、发送邮件、修改配置）

实现方式：在 CLAUDE.md 或 Hooks 中声明：

在执行以下操作前，必须暂停并请求人工确认：
- 创建或合并 Pull Request
- 发送外部通知/邮件
- 修改生产环境配置

模式二：阶段性审批

场景：复杂任务的关键里程碑

实现方式：在 Skill 中定义检查点：

Step 1: 分析需求 → Step 2: 设计方案 → [人工审批]
→ Step 3: 实现 → Step 4: 测试 → [人工审批]
→ Step 5: 部署

模式三：异常触发审批

场景：Agent 遇到预设之外的情况

实现方式：在 Hooks 中定义触发条件：

当以下情况发生时，自动暂停并通知 PM：
- 连续 3 次相同操作失败
- 操作范围超出预期（如：修改了 10+ 文件）
- 检测到敏感数据模式

审批节点的设计原则：宁多勿少（初期），逐步放开。新上线的 Agent 建议在所有关键操作上设置审批，运行稳定后再选择性取消。这与棘轮原则一致——每次取消审批都应基于足够的成功证据。

5.4 渐进式披露的 Token 效率分析

场景假设：一个项目有 20 个工具/Skill

节省比例：约 80%（在工具数量多但单次任务使用少量工具的场景下效果更显著）。注：80% 是极端场景下的理论上限（20 个 Skill 仅使用 3 个），Anthropic 官方实测数据为 20-30%（典型业务场景），实际效果取决于 Skill 数量和任务类型的匹配度。

Anthropic 数据显示，渐进式披露可节省 context 使用 20-30%，同时降低 Agent 的认知过载。

---

六六、各方文章核心观点对比

6.1 Anthropic：Managed Agents 与解耦架构

核心主题：系统性地解决长期运行代理的架构问题

关键贡献：

• 提出 Brain / Hands / Session 三层解耦架构
• 会话持久化：事件日志记录所有活动，Harness 无需保存状态可独立重启
• 容器即牲畜：失败即丢弃重建，无需修复
• 安全隔离：凭证与沙箱分离
• 量化成果：解耦后 p50 TTFT 下降约 60%，p95 下降超 90%

关键洞察：Harness 编码的是对模型能力的假设，这些假设需要随模型改进不断更新。例如 Context Anxiety 在 Sonnet 4.5 中存在，但在 Opus 4.5 中消失，原有的重置代码变成无用"死代码"。

6.2 Anthropic：长时间运行应用的 Harness 设计

核心主题：长期运行任务中的自评估问题与多代理架构解决方案

关键贡献：

• 将主观判断（如"设计是否好看"）转化为具体可评分的 4 维度标准
• 提出三代理架构（Planner → Generator → QA）
• 代理间通过文件交互通信，保持工作忠于规格
• 使用 Agent SDK 自动压缩处理上下文增长

核心洞察：

传统单 Agent 自评估 → 模型过于乐观。分离评估后 → 对生成工作更严苛 → 迭代质量更高。这类似 GAN 的生成器-判别器架构。

6.3 Browser-use：Bitter Lesson 与极简主义

核心主题：最小化抽象，让 Agent 直接访问原始工具 API

关键贡献：

• 仅 ~600 行代码的四文件极简架构
• 自修复循环：Agent 在遇到缺失工具时自动编辑 Harness 添加功能
• 直接暴露 CDP 而非包装的 helper

四文件架构：

核心洞察：

"我们试图隐藏的 CDP 复杂性不是应该隐藏的东西。它们是应该让模型看到的东西。"

6.4 LangChain：Trace 分析与自验证改进

核心主题：通过系统性的 Harness 优化，利用痕迹分析和自验证改进 Agent 性能

关键贡献：

• 定义 Harness 的三个可调节"旋钮"：System Prompt、Tools、Middleware/Hooks
• 提出基于 trace 分析的自动化改进循环
• "推理三明治"策略（规划 xhigh → 实现 high → 验证 xhigh）
• 量化成果：模型不变，仅调整 Harness，从 52.8% 提升到 66.5%

Harness 工程师的目标：

"准备并交付上下文，使 Agent 能够自主完成工作。"

6.5 跨文章共识与分歧

共识

分歧

---

七七、实战案例

PM 阅读指南：本章通过三个真实案例展示 Harness 改进的量化效果（52.8% → 66.5% 的提升）。重点关注"推理三明治"策略和 4 维度评分标准 —— 这两个工具可直接复用到你的 Agent 场景。

7.1 LangChain Terminal Bench 实验（52.8% → 66.5%）

背景：Terminal Bench 2.0 基准测试，使用 GPT-5.2-Codex 模型

基线表现：52.8%（排名 Top 30）

改进措施：

Trace 分析方法：

步骤 1: 从 LangSmith 获取实验痕迹
步骤 2: 生成并行错误分析 Agent → 检测错误模式
步骤 3: 主 Agent 综合发现 → 聚合反馈
步骤 4: 人工验证 → 修改 Harness
步骤 5: 重新运行基准测试 → 验证改进

最终结果：66.5%（+13.7%），排名 Top 5

关键发现：

• 最常见失败：Agent 写完代码就停止，不运行测试
• 测试是 Agent 迭代改进的信号源
• 预先注入目录结构和可用工具大幅提速
• "推理三明治"策略 66.5% vs 仅 xhigh 预算 53.9%（Agent 超时）

7.2 Browser-use 自修复循环案例

与传统框架的对比：

• 传统框架：十种 Chrome 标签崩溃场景 → 十个 watchdog 处理器 → 需保持与 Chrome 内部同步
• Harness 方式：Agent 读错误 → 自动重新附加 target → 重试。模型已见过千万 threads 讨论 Chrome 崩溃

7.3 Anthropic 前端设计迭代案例

问题：Claude 倾向于生成技术正确但视觉平凡的设计（"安全模板"风格）

解决方案 — 4 维度评分标准：

实施过程：

1. 建立结构化评分标准
2. 通过少量示例校准评估器（Few-shot）
3. 分离生成 Agent 和评估 Agent
4. 多轮迭代

效果：设计从"安全模板"进化到创意突破（如将博物馆网站转为 3D 空间体验）

4维度评分规则示例（1-5分制）：

• 设计质量：1分 = 完全不一致，5分 = 所有组件视觉协调统一
• 原创性：1分 = 完全套用模板，5分 = 大量自定义设计决策
• 工艺：1分 = 排版混乱间距不等，5分 = 完美的视觉层级和细节
• 功能性：1分 = 严重可用性问题，5分 = 所有交互符合预期

对 4 个维度分别评分，取平均值作为总分。每轮迭代对比分数变化，量化 Harness 改进带来的提升效果。PM 可以将此评分框架复用到其他 Agent 场景。

7.4 Anthropic 全栈应用三代理架构

架构设计：

通信机制：

• 代理通过文件交互（一个 Agent 写文件，另一个读并响应）
• 保持工作忠于规格
• 使用 Agent SDK 自动压缩处理上下文增长
• 单次会话可运行多小时

---

八八、Harness 演进方向

8.1 从固定到动态

• 早期：预设所有处理逻辑，Harness 编码静态假设
• 现在：假设需要随模型版本更新（如 Context Anxiety 在 Sonnet 4.5 中存在，但在 Opus 4.5 中已消失）—— 这说明 Harness 编码的假设是模型版本的动态函数，而非固定缺陷
• 未来：Agent 根据模型能力和任务需求自动调整 Harness

8.2 从集中到分布

• 集中式：所有逻辑在一个进程中（易调试，难扩展）
• 分布式：通过清晰接口分离 concern（易扩展，需明确设计）
• 趋势：Anthropic 的 Brain/Hands/Session 解耦已证明可降低 TTFT 60-90%+

8.3 从黑盒到透明

• 旧思路：把复杂性藏起来，让模型专注高层任务
• 新思路（Browser-use）：暴露细节，让模型学会应对现实复杂性
• 趋势：模型能力增强后，过度抽象反而成为瓶颈

8.4 从单 Agent 到多 Agent

• 单 Agent：一个 Agent 承担所有角色
• 多 Agent：每个 Agent 在特定角色上更优异（规划/执行/评估）
• 实现方式：通过结构化的文件/消息通信，各 Agent 独立 context 避免噪声积累

新兴趋势：

• Harness 即代码化：用 DSL 定义 Harness 配置
• AI 辅助的 Harness 设计：让 Agent 帮助优化自己的 Harness
• Harness 元学习：系统自动学习什么补丁有效
• 组织级 Harness 标准库：构建企业级 Skill 市场

Harness 演进优先级指南（PM 路线图）

基于当前行业发展趋势，建议按以下节奏规划 Harness 投资：

路线图建议：先确保 P0 项（自验证 + 评估分离）在所有项目中落地，再根据具体项目复杂度选择 P1 投资。P2 项属于前瞻性布局，建议指定专人跟踪行业动态。每季度回顾一次路线图，根据实际进展调整优先级。

---

九九、可操作的最佳实践

PM 阅读指南：本章提供从"第 1 周该做什么"到"长期迭代节奏"的全周期行动清单，以及 9 个常见反模式（Anti-Patterns）的规避指南。建议将 9.1 节的快速启动清单作为团队启动 Agent 项目的标准流程。

9.1 快速启动清单

□ 第 1 周：编写或审核根 CLAUDE.md (< 100 行)
  - 项目 WHY / WHAT / HOW
  - 所有任务都需要的命令（bun vs npm 等）
  - 指向 Skill 和 Agent Guide 的索引

□ 第 2-3 周：创建 5 个核心 Skill
  - build-test-verify（验证命令集）
  - git-commit（提交规范）
  - create-pull-request（PR 标准）
  - core-conventions（代码风格）
  - self-review-checklist（质量门禁）

□ 第 4 周：建立 trace 分析反馈循环
  - 记录失败的 trace
  - 识别模式 → 改进 Harness
  - 重新验证 → 迭代优化

9.2 改进优先级矩阵

9.3 常见 Anti-Patterns

9.4 衡量与迭代方法

关键度量

反馈循环频率

日常：  每 10-20 次运行分析一次 trace，发现通用失败模式
每周：  Review CLAUDE.md 和 Skill 有效性
每月：  Audit Harness 中是否有过时补丁或"死代码"
每季度：评估是否需要架构级调整（单 Agent → 多 Agent 等）

自动改进循环（LangChain 方法）

步骤 1: 建立基准
  → 定义评估指标（如 Terminal Bench 得分）
  → 记录所有执行痕迹（LangSmith）

步骤 2: 痕迹分析
  → 生成分析 Agent，研究失败案例
  → 识别通用的失败模式

步骤 3: 目标性改进
  → 修改系统提示 / 工具 / 中间件
  → 验证改进不会引入回归

步骤 4: 迭代
  → 重新运行基准测试
 → 继续优化

初期失败模式分析

在达到 52.8% 基线之前，团队经历了多个典型的 Harness 设计失败。这些失败模式对 PM 具有重要的参考价值：

PM启示：这些失败模式是如何被发现的？答案是Trace分析。建议PM要求工程团队保留Agent的完整执行日志（Trace），定期回顾失败案例，每个修复都应转化为Harness规则（棘轮原则）。

---

十十、关键术语表

---

十一十一、参考资料

Anthropic

1. Scaling Managed Agents: Decoupling the brain from the hands — Anthropic Engineering Blog, 2026
2. Harness design for long-running application development — Anthropic Engineering Blog, 2026

LangChain

1. The Anatomy of an Agent Harness — Vivek Trivedy, LangChain Blog, 2026
2. Improving Deep Agents with Harness Engineering — Vivek Trivedy, LangChain Blog, 2026
3. Using Skills with Deep Agents — Lance Martin, LangChain Blog, 2025

Browser-use

1. The Bitter Lesson of Agent Harnesses — Browser-use Blog, 2026

Martin Fowler

1. Harness engineering for coding agent users — Birgitta Böckeler, martinfowler.com, 2026

HumanLayer

1. Skill Issue: Harness Engineering for Coding Agents — HumanLayer Blog, 2026
2. Writing a good CLAUDE.md — HumanLayer Blog, 2026

其他

1. Agent Harness Engineering — Addy Osmani, 2026
2. Building AI Coding Agents for the Terminal: Scaffolding, Harness, Context Engineering — OpenAI/OpenDev, arxiv, 2026
3. CLAUDE.md Examples and Best Practices — morphllm.com, 2026
4. Implementing CLAUDE.md and Agent Skills — groff.dev, 2026

---

报告生成时间：2026 年 4 月 26 日

调研范围：Anthropic、LangChain、Browser-use、HumanLayer、Martin Fowler、OpenAI 等业界领先团队的 2025-2026 年发布内容