HARNESS
Anthropic Engineering · 技术图谱解读 · Wayne研究室

AI Harness
设计指南

如何让复杂业务 Skill 跨会话、长期、稳定运转

来源 anthropic.com/engineering
日期 2026-04-15
类型 技术图谱 · CEO视角
01 / 14
核心结论

Harness 的本质 = 为 AI 建立「有效工作机制」

与其依赖模型更聪明，不如设计让模型持续正确工作的结构。以下三个原则决定复杂 Skill 能否长期运转：

01
状态持久化
AI 不能靠"记忆"跨会话。进度、规则、检查结果必须写入文件或数据库，每次启动先读状态再行动。
每步 → 写文件
02
职责分离
生成者不能自我评估。必须用独立评估 Agent 验收，像人类工作流中的 QA 角色一样存在。
Generator ≠ Evaluator
03
渐进验收
每一步必须有可测试的完成标准（Exit Criteria），不满足就不能进入下一步，拒绝"差不多行了"。
Done = 可证伪
02 / 14
问题溯源

复杂 AI 任务为什么会失败？

🧠
无状态断裂
每次新会话 = 全部遗忘。规则、已做什么、哪步出错——AI 完全不知道。换班工人综合症：前一班人的工作全部丢失。
🪞
自评偏差
AI 倾向于"自信地称赞自己的工作——即使质量明显很差"。自我检查形同虚设，需要独立评估者。
📉
上下文焦虑
Context window 接近上限时，AI 开始"草草收尾"，提前宣布任务完成，实际质量大幅下滑。
想象一群工程师倒班工作，但没有任何交接文档。每一班都从零开始理解项目，犯同样的错误，却不知道前人踩过这个坑。
— Anthropic Engineering, Effective Harnesses for Long-Running Agents
事实：这三个问题不是模型的缺陷，是工作机制设计缺失的结果。更好的 Harness 比等待更好的模型更有效。
03 / 14
文献来源

Anthropic 工程博客：两篇核心文章

[01]
长跑代理篇
Effective Harnesses for Long-Running Agents
  • 两段式 Agent：Initializer（首次）+ Coding Agent（后续），分工不同的 Prompt
  • 进度文件：`claude-progress.txt` + 200+ 功能的 JSON 检查列表
  • 启动仪式：每次先读 git log + progress 文件 + 功能清单，再开工
  • 浏览器验证：用 Puppeteer MCP 端到端验证，不能只靠代码判断
  • 增量提交：每完成一个 feature 立即 commit，保留可回溯状态
[02]
应用开发篇
Harness Design for Long-Running Application Development
  • GAN 双 Agent：Generator 生成，Evaluator 独立批判，5-15 次迭代
  • Sprint Contract：开工前先约定"Done 的定义"，事先签合同
  • 文件通信：Agent 间通过文件传递状态，不依赖对话 Context
  • 二元阈值：评估结果只有 Pass / Fail，不允许"大概还行"
  • Harness 精化：模型变强后，持续删除不再需要的脚手架
事实
以上内容均来自 Anthropic 官方工程博客，原文可验证。
04 / 14
挑战 01

跨会话记忆断裂：状态持久化方案

S1
Session 1：初始化
创建环境脚本 `init.sh`，生成 200+ 功能 JSON 检查列表，首次 git commit，写入进度文件
S2
Session 2 启动仪式（必须）
① 读 `init.sh` 了解环境 ② 读 git log 知道做了什么 ③ 读 progress 文件知道状态 ④ 选下一个最优先未完成功能
✗
没有 Harness 时……
AI 从零开始，不知道之前做了什么，重复踩坑，规则全靠现场记忆（必然失效）
🗂 必备状态文件
📄init.sh环境初始化
📋progress.json200+ 功能状态
📝claude-progress.txt当前状态摘要
🔧rules.md不可违反的规则
🗃git history行动可追溯记录
每次完成一步 → 立即更新状态文件 → commit
下次启动 → 先读这些文件 → 再行动
05 / 14
挑战 02

自评偏差：Generator ≠ Evaluator

❌ 单 Agent 自评（失败模式）
宣称"完成了"
VS
实际未测试
主题数量"够了"
VS
实际只有 10 个
图片"很好"
VS
用了 2018 年旧图
观点：Anthropic 测试发现，AI 独立评估时倾向于"说服自己问题不重要"，这是模型的结构性偏差，不是调 Prompt 能解决的。
✅ GAN 双 Agent 模式
Generator
→ 输出 →
Evaluator
→ 打分 →
重新生成
重复 5-15 次迭代直到 Pass
Evaluator 评分维度示例（Anthropic 实测）：
  • Design quality：整体是否有清晰的风格和主题
  • Originality：避免"AI 样板气"，有独特决策
  • Craft：细节执行（排版、间距、色彩和谐）
  • Functionality：用户任务能否真正完成
06 / 14
挑战 03

上下文焦虑：Context Reset 优于 Compaction

Context 使用率与质量关系
0-40%：正常工作区质量稳定
专注执行，规则清晰可查
40-80%：警戒区开始焦虑
开始跳步骤、简化输出、过度乐观
80%+：危险区草草收尾
提前宣布完成，实际严重缺项
事实：Anthropic 测试 Claude Sonnet 4.5 时发现，Context Compaction（压缩）不足以解决焦虑。Context Reset（清空重来 + 结构化交接）才是正解。
Session 交接协议（必须文件化）
  1. ①
    完成状态快照：已做了哪些步骤、结果如何、遗留问题
  2. ②
    规则再确认：关键约束重新声明（时间窗口、数量下限等）
  3. ③
    下一步指令：明确告知新 Session 从哪里开始，做什么
  4. ④
    验收标准：这一步完成的标准是什么（可量化）
  5. ⑤
    环境检查：运行 init.sh，确认工具/API 状态正常
07 / 14
解法 01

两段式 Agent 架构：Initializer + Executor

Initializer Agent · 只跑一次
建立工作环境
  • 创建 init.sh：一键启动开发服务器
  • 生成 功能 JSON：200+ 任务，每个有验收步骤
  • 首次 git commit：建立 baseline
  • 写 progress.txt：记录已完成、正在做什么
  • 识别所有依赖项和潜在阻塞点
用户输入需求
→
初始化 Agent
→
建好工作台 ✓
Executor Agent · 每次执行
渐进式完成任务
  • 启动时先读 init.sh → git log → progress
  • 从功能清单选 最高优先级未完成项
  • 每次只做 一个功能，不贪多
  • 完成前自我验证（或交 Evaluator 验证）
  • 通过验证后 更新 progress + git commit
  • 确保代码随时处于 可合并状态
读状态
→
选任务
→
执行验证
→
写状态 ✓
💡 关键：两个 Agent 使用不同的 System Prompt。Initializer 更开放创造性，Executor 更严格约束性。
08 / 14
解法 02

Sprint Contract：开工前先定义"Done"

📋
Sprint Contract 是什么？
Generator 和 Evaluator 在执行前协商并签署的成功标准协议。明确"做完"不是主观判断，而是可测试的客观条件。
  • ✓
    量化指标：如"聚合主题 ≥ 35 个"
  • ✓
    覆盖检查：如"所有 L1 行业至少 1 条"
  • ✓
    状态验证：如"已写入飞书并返回 record_id"
  • ✗
    主观判断："差不多完成了"
  • ✗
    跳步骤："这步可以省略"
观点：Sprint Contract 解决了"过度规格化"和"需求漂移"两个问题之间的张力——约定边界，但不规定实现细节。
二元阈值评估机制
Anthropic 实测：模糊评分（0-10分）导致 AI 说服自己"7分也够了"。改为 Pass/Fail 二元后，迭代质量显著提升。
主题数量
10/35
→ FAIL：不得进入下一步
主题数量
42/35
→ PASS：继续执行
任意一个标准低于阈值 → Sprint 失败 → Generator 收到具体反馈 → 重新执行
09 / 14
千图案例 · 问题诊断

千图内容 Skill：11 个 Bug 背后的 Harness 缺失

Bug ID
根本问题
Harness 缺失
优先级
BUG-001
AI 将当月节日纳入规划范围（应排除）
规则未外化到文件
高
BUG-002
主题数量严重不足（10 个 vs 要求 35+）
无数量 Exit Criteria
高
BUG-003
政务专题名称AI 自创，需查官方来源
无搜索步骤约束
高
BUG-008
找图未按 P0→P6 优先级，直接跳至 P3/P6
无强制流程检查
高
BUG-009
平台未登录导致采图路径失效
无环境初始化检查
高
BUG-010
规划结果未自动写入飞书，全靠手工
无 Checkpoint 强制
高
BUG-011
千图 API 401 鉴权失败
无 API 状态预检
中
🎯 观点：所有高优先级 Bug 的根因一致——规则和状态只存在于对话里，没有外化到系统。这是 Harness 设计问题，不是 Prompt 质量问题。
10 / 14
千图案例 · 改造方案

千图内容 Skill Harness 改造蓝图

🚀 Init Agent · 每月首次运行
Skill 初始化 Agent
  • API 状态预检：飞书 token + 千图 API token 均测试连通
  • 平台登录检查：站酷/小红书/JD 登录状态确认
  • 月度配置：规划月份 / 行业权重 / 操作人写入 config.json
  • 功能 JSON：生成本月完整任务清单（含 Exit Criteria）
  • 规则文件：将时间窗口、数量下限、行业清单写为 rules.md
⚙️ Executor Agent · 每步执行
Skill 执行 Agent
  • 启动仪式：读 config.json + progress.json + rules.md
  • 步骤验收：每步完成后对照 Exit Criteria 自检
  • 飞书 Checkpoint：写入成功才算该步完成
  • 增量状态更新：每步完成立即更新 progress.json
  • 阻塞提前报告：遇到环境问题立即报告，不自行绕过
🔍 Evaluator Agent · 独立验收
Skill 评估 Agent
  • 数量校验：聚合主题 ≥ 35，子主题 ≥ 200（硬约束）
  • 行业覆盖：遍历所有 L1 行业 Checklist
  • 时效校验：图片年份 ≥ 当年，过期图一律拒绝
  • 优先级路径：P0→P6 顺序核查，不允许跳步
  • Pass/Fail 判断：任意一项不通过 → 反馈给 Executor 重做
📁 状态文件体系
外化的状态管理
  • rules.md：时间窗口逻辑、数量下限、行业清单、优先级路径
  • config.json：月份、操作人、行业权重等月度配置
  • progress.json：每个主题/步骤的完成状态 + 飞书 record_id
  • api-status.json：API 连通性检查结果 + 平台登录状态
  • 飞书 bitable：最终真值，progress.json 是它的镜像
11 / 14
进阶原则

Harness 精化：随模型进化持续瘦身

🏗
Harness 编码了对模型的假设
每一个脚手架都是"我不信任模型能自己做对这件事"的声明。假设过时了，脚手架就成了阻碍。
✂️
定期删除不再承重的部分
Anthropic 将 Opus 4.6 接入后，移除了 Sprint 分解步骤和每 Sprint 评估，改为结尾单次验收——因为模型自己处理得更好。
🔄
解空间不缩小，只是转移
模型更强 → Harness 空间不变小，而是可以探索更复杂的 Agent 组合。用省下的脚手架预算去做更有意思的实验。
脚手架需求随模型能力变化
高 低 脚手架需求 模型能力 Sonnet Opus Next
早期模型 模型能力 → 未来模型
"每个 Harness 组件都编码了对模型局限的假设。随着模型进步，持续审计——删掉不再承重的脚手架。"
— Anthropic Engineering, Harness Design
12 / 14
CEO 视角 · 行动建议

我应该做什么？三阶段行动清单

立即做 · 本周
建立外化状态
  • 创建 rules.md：时间窗口、数量下限、行业清单等硬规则写入文件
  • 在每个 SKILL.md Step 末尾加强制 Checkpoint：写入飞书成功才算完成
  • 修复 BUG-002：Step 3 末尾加数量强制校验（聚合主题 < 35 不得进入 Step 4）
  • 创建 api-status.json：Skill 启动前先测试 API 和平台登录
近期 · 2 周内
分离评估角色
  • Skill 1 中增加独立评估步骤（图片质量、覆盖面、时效）
  • 写 Sprint Contract 模板：每次执行前明确本轮的 Done 标准
  • 创建 progress.json 体系：每个主题有独立 ID 和状态字段
  • 对照行业找图路径手册，给 Skill 2 加P0→P6 强制顺序检查
中期 · 1 个月
全链路 Harness 化
  • 三 Skill 统一 Initializer Agent（月度配置 + 环境检查）
  • 实测 GAN 模式：Skill 2 用双 Agent 迭代找图和完善 notice
  • 建立 Harness 审计周期：每季度检查哪些脚手架可以移除
  • 考虑并发 Executor：多行业主题并行生成
🏆
本质判断：三个内容 Skill 的核心挑战不是 Prompt 质量，而是工作机制设计。用 3 天时间建好 Harness 基础设施，比反复调 Prompt 效率高 10 倍。
13 / 14
Wayne研究室 · 技术图谱 · 2026-04-15

Harness 不是配置，
是工作机制

AI 不会因为"你让它认真"就变得可靠。
可靠来自结构：状态持久化、职责分离、渐进验收。

原文 01：长跑代理 Harness → 原文 02：应用开发 Harness →
wwei.ai · Learn in Public · Wayne 2026
14 / 14