Harness Engineering 学习笔记
11 分钟
核心主题： 更好的 Prompt 只能改善一次回答；更好的 Harness 能改善每一次运行。
1. Harness Engineering 是什么
这篇文章的核心观点是：
当 Agent 会遗忘约束、选错工具、跳过验证、反复重试直到耗尽预算时，问题不一定只是模型能力不够，更可能是模型周围的执行环境设计得不够好。
模型负责：
Reasoning
推理Harness 负责把这种推理变成：
Controlled Execution
受控执行一个 Harness 至少需要处理：
Context
Tools
State
Evidence
Limits
Recovery也就是：
选择上下文
授权工具
保存状态
收集证据
执行限制
失败恢复因此：
Prompt ≠ System更准确地说：
Prompt
只是 Harness 的一个输入2. Harness Engineering 的核心问题
Prompt Engineering 主要问：
我应该告诉模型什么？
Context Engineering 主要问：
模型现在应该知道什么？
Harness Engineering 进一步问：
什么样的系统，能够让模型采取行动、证明自己的工作、从失败中恢复，并安全地持续运行？
这是三者最重要的区别。
3. 最小可行 Harness
文章提出，一个实用的 Harness 不需要一开始就做：
20 个服务
多智能体 Swarm
复杂 Agent Framework先把下面六件事情做好即可：
1. Task Contract
2. Context Compiler
3. Permissioned Tool Gateway
4. Durable State
5. Evidence Gates
6. Trace & Recovery Loop可以记成：
Request
↓
Contract
↓
Context
↓
Tools
↓
State
↓
Evidence
↓
Trace / Recovery4. 第一层：Task Contract
4.1 为什么需要任务契约
自然语言很灵活。
例如：
“帮我给 Dashboard 加一个 CSV 导出。”这里可能有很多隐藏问题：
- 可以改数据库吗？
- 可以加依赖吗？
- 怎样才算完成？
- UI 需要检查吗？
- 测试失败怎么办？
如果没有边界，Agent 很容易：
解决一个更简单的问题
↓
然后宣布任务完成因此，在 Agent 开始执行之前，需要把用户请求转换成一个明确的：
Task Contract4.2 Task Contract 应该包含什么
例如：
task_id: feature_042
goal: Add CSV export to the analytics dashboard
inputs:
- issue.md
- repository
- design/export-flow.png
constraints:
- preserve the public API
- do not change the database schema
- do not add a new dependency
deliverable:
type: pull_request
done_when:
- tests pass
- typecheck passes
- exported CSV matches the fixture
- UI screenshot passes review
escalate_when:
- schema change appears necessary
- tests fail three times for the same reason
- requested behavior conflicts with an existing product rule可以概括为：
Goal
Inputs
Constraints
Deliverable
Done When
Escalate When5. Done When 比“看起来不错”重要
Harness 最关键的思想之一是：
Agent 说完成了
≠
任务真的完成了不好的 Stop Condition：
Looks good更好的 Stop Condition：
Tests Passed
Typecheck Passed
Fixture Matched
UI Review Passed因此：
完成应该由可验证条件决定，而不是由模型自己的感觉决定。
6. 第二层：Context Compiler
6.1 Context 是有限资源
Context 不是越多越好。
常见错误：
完整聊天记录
+
所有工具输出
+
整个项目文档
+
超长 System Prompt然后一次性全部塞给模型。
问题是：
More Context
≠
More UnderstandingContext 本质上是一种：
有限的注意力预算。
7. 给 Agent 地图，而不是百科全书
文章中的一个重要原则：
Give the agent a map, not a manual.
即：
给 Agent 一张地图，而不是整本说明书。
例如：
AGENTS.md
↓
Architecture Index
↓
Product Rules
↓
Task-specific Guide
↓
Exact Files / Evidence根目录文档的作用不是：
把所有知识写进去而是：
告诉 Agent 去哪里找到知识真正需要的信息再：
Just in Time
按需获取8. Context Compiler
Harness 应该根据：
Task
+
Current State动态构建 Context。
例如：
function buildContext(task, state) {
return [
load("AGENTS.md"),
load(task.relevantProductSpec),
load(task.relevantArchitecture),
summarize(state.completedSteps),
state.openRisks,
state.currentArtifacts
];
}核心原则：
只加载当前步骤真正需要的信息9. Progressive Disclosure
Context 管理适合使用：
Progressive Disclosure
渐进式披露即：
先给概览
↓
需要时再展开
↓
再需要时读取具体文件这样可以避免：
Context Pollution
上下文污染10. 一个很重要的观念
文章中有一句非常值得记住：
Conversation should not be your database.
也就是说：
聊天记录
≠
数据库另外：
System Prompt
≠
文件柜不能把所有知识都堆进 Prompt。
11. 第三层：Permissioned Tool Gateway
模型可以：
Propose an Action
提出操作但不能直接决定：
Execute the Action
执行操作应该在模型和工具之间加入：
Tool Gateway结构：
MODEL
提出 Tool Request
↓
HARNESS
检查 Schema
检查权限
检查风险
↓
TOOL
真正执行12. Tool Gateway 的执行过程
典型逻辑：
Tool Request
↓
Validate Schema
↓
Authorize
↓
Risk Check
↓
Deny / Approval / Execute
↓
Normalize Result例如：
if (decision === "deny") {
return observation("permission_denied");
}
if (decision === "approval_required") {
return pauseForHumanApproval(request);
}
const result = await sandbox.execute(request);13. 一个好的 Tool 应该具备什么
每个工具都应该有：
Clear Purpose
Unambiguous Schema
Permission Boundary
Predictable Success Response
Structured Failure Response
Timeout即：
- 用途明确；
- 参数明确；
- 权限明确；
- 成功返回值明确；
- 失败返回值明确；
- 有超时时间。
14. Tool Result 应该结构化
不好的返回：
几千行 terminal output更好的返回：
{
"status": "failed",
"tool": "run_tests",
"reason": "2 snapshot mismatches",
"evidence": [
"artifacts/home-mobile-before.png",
"artifacts/home-mobile-after.png"
],
"retryable": true
}这样模型可以直接推理：
发生了什么？
证据是什么？
能不能重试？15. Tool Design 的本质
好的 Tool Design：
减少模型需要猜测的决策差的 Tool Design：
每一次工具调用
都变成新的推理问题因此：
工具本身也是 Agent Intelligence 的一部分。
16. 第四层：Durable State
长任务一定会遇到：
Context Limit
Crash
Restart
Agent Handoff如果当前任务状态只存在于：
Chat Transcript那么系统非常脆弱。
所以：
State 必须保存到模型之外。
17. State 中应该保存什么
例如：
{
"task_id": "feature_042",
"status": "verifying",
"current_step": "mobile_visual_check",
"completed": [
"implementation",
"unit_tests",
"desktop_visual_check"
],
"decisions": [
"reuse existing export endpoint"
],
"artifacts": [
"export.csv"
],
"open_risks": [
"mobile toolbar may overflow"
],
"next_action": "render mobile viewport"
}核心包括：
Current Step
Completed Steps
Decisions
Artifacts
Open Risks
Next Action18. Memory 应该分成四类
文章把 Memory 分成：
FACTS
DECISIONS
STATE
LESSONS分别代表：
FACTS
稳定的项目知识。
例如：
系统使用 PostgreSQLDECISIONS
当前任务过程中做出的决策。
例如：
复用现有导出接口STATE
当前任务运行到哪里。
例如：
正在做 Mobile Visual CheckLESSONS
过去失败后应该影响未来运行的经验。
例如：
每次修改导出逻辑后
都必须执行 CSV Fixture Regression Test19. 什么应该保留，什么应该丢弃
临时 Tool Result：
总结后可以丢弃Architecture Decision：
应该长期保存Repeated Failure：
应该转成 Rule 或 Test因此：
Memory 不是保存所有东西。
更准确地说：
Memory 是保留未来继续正确执行任务所需的最小信息集合。
20. 第五层：Evidence Gates
模型负责：
Produce Artifact环境负责：
Produce EvidenceHarness 负责：
Evaluate Evidence即：
Artifact
↓
Verification
↓
Evidence
↓
Accept / Retry / Escalate21. Evidence First
验证流程可以是：
Run Tests
Run Typecheck
Validate Schema
Capture Screenshot
Check Constraints最后：
全部成功
→ Accept
局部问题可修复
→ Retry
无法安全处理
→ Escalate22. 优先使用 Deterministic Checks
文章建议：
先使用确定性验证，再考虑模型 Reviewer。
不同任务的 Evidence 可以不同。
Code
Tests
Types
Lint
Dependency RulesUI
Render
Screenshot
Interaction ReplayResearch
Source Coverage
Citation Match
Contradiction CheckData
Schema
Range
Freshness
ReconciliationSupport
Policy Check
PII Check
Approval Boundary23. Maker 和 Checker 最好分离
一个重要思想：
Maker
≠
Checker生成内容的模型当然可以检查自己的工作。
但更可靠的方法是：
Independent Verifier
+
Different Instructions
+
Fresh Context因为：
做出错误的模型，可能也看不出自己的错误。
24. Autonomy 与 Evidence 的关系
非常值得记住一句：
Autonomy should expand only when evidence quality expands with it.
即：
更高自主性
必须对应
更强验证能力不能：
权限越来越大
↓
验证却没有增强25. 第六层：Trace & Recovery
如果没有 Trace：
Failure
→ 一个故事例如：
“刚才好像哪里出问题了。”有 Trace：
Failure
→ Reproducible Test Case这就是工程化的重要区别。
26. Trace 应该记录什么
例如：
Run ID
Contract Version
Model Route
Context Sources
Tool Calls
State Changes
Verification Results
Retries
Cost
Stop Reason
Rollback Point比如：
{
"tool_calls": 17,
"state_changes": 6,
"retries": 1,
"cost_usd": 2.84,
"stop_reason": "human_approval_required"
}27. 为什么 Trace 很重要
Trace 可以帮助回答：
为什么失败？
失败在哪里？
模型看到了什么 Context？
调用了什么 Tool？
为什么停止？
能不能回滚？28. Failure Classification
失败之后不能直接：
Retry
Retry
Retry应该先分类。
例如：
Missing Context
Bad Tool Contract
Missing Guardrail
Weak Verification
Unknown Failure然后对应处理。
29. 不同 Failure 应该怎样修
Missing Context
Update Project MapBad Tool Contract
Improve Tool SchemaMissing Guardrail
Add Policy CheckWeak Verification
Add Regression TestUnknown
Escalate With Evidence30. 不要使用“更情绪化的 Prompt”
一个很有意思的表述：
不要在同一个失败环境中继续运行，只是换一个更加情绪激烈的 Prompt。
例如：
“你必须认真检查！”
“这次千万不要再犯错！”没有真正解决问题。
正确方式：
找到缺失能力
↓
修复能力
↓
重跑精确失败案例
↓
永久保留修复31. Harness 的复利效应
好的 Harness：
一次失败
↓
修系统
↓
以后所有 Run 都变好这就是：
Compounding
复利因此：
真正应该优化的是系统，而不是某一次回答。
32. Permission Ladder
模型不能：
自己提出高风险操作
+
自己批准
+
自己执行正确结构：
MODEL PROPOSES
↓
POLICY AUTHORIZES
↓
TOOL EXECUTES
↓
HARNESS RECORDS即：
Propose
Authorize
Execute
Record职责分离。
33. 不同风险需要不同权限
例如：
Read Files
AutomaticWrite Workspace
Automatic
但要求：
Isolated Workspace
Diff RecordedSend Message
Approval RequiredDeploy Production
Approval Required
Tests Pass
Rollback ReadyDelete Data
Approval Required
Exact Targets
Recovery Plan34. Permission 的原则
非常值得记住：
Match the control to the consequence.
也就是：
控制强度
应该匹配
操作后果读取公开文档：
Low Risk删除客户数据：
High Risk两者不能走完全一样的审批流程。
35. 最小项目结构
文章给出的最小结构：
agent-harness/
├── AGENTS.md
├── contracts/
│ └── task.schema.json
├── context/
│ ├── architecture.md
│ ├── product-rules.md
│ └── security.md
├── tools/
│ ├── registry.json
│ └── permissions.yaml
├── state/
│ ├── current.json
│ └── decisions.md
├── checks/
│ ├── verify.ts
│ └── regression-cases/
├── runs/
│ └── traces.jsonl
└── lessons/
└── harness-updates.md重要的不是：
具体文件夹名字而是：
Separation of Responsibilities
职责分离36. Harness 应该怎样一步步构建
文章给出的顺序非常实用。
Step 1：Define Done
先定义：
什么叫完成？然后建立 2～3 个检查项。
Step 2：Wrap One Tool
只先封装一个工具。
增加：
Schema
Timeout
Permission
Structured ResultStep 3：Persist One State
先建立一个 State 文件。
记录：
Completed
Decisions
Artifacts
Open Risks
Next ActionStep 4：Add One Recovery Path
检查失败时：
返回精确证据
↓
允许一次有限修复重点：
Bounded Repair不是无限 Retry。
Step 5：Save Trace
记录：
加载了什么 Context
运行了什么 Tool
改变了什么
什么检查通过了
为什么停止Step 6：Turn Failures Into Infrastructure
重复错误最终应该变成四类基础设施之一：
A Clearer Map
A Better Tool
A Stricter Permission
A New Test即：
更清晰的 Context
更好的 Tool
更严格的权限
新的验证37. 什么时候增加 Multi-Agent
文章态度非常明确：
Do not begin with a swarm.也就是：
不要一开始就做多 Agent。
推荐顺序：
Single Agent
↓
Reliable Loop
↓
Evidence
↓
Recovery
↓
More Tools
↓
More Autonomy
↓
More Agents只有基础可靠后，再增加复杂性。
38. Harness Engineering 不是什么
Harness Engineering 不是：
5000 行 System Prompt不是：
把能接的所有工具都交给 Agent不是：
把整个聊天记录永久保存
然后叫做 Memory不是：
没有客观标准
却再增加一个 Reviewer Agent不是：
无限 Retry
直到随机出现一次好结果也不是：
彻底消灭 Human in the Loop39. Human Attention 应该花在哪里
Harness 的作用不是：
完全替代人而是：
自动化可以自动化的部分
+
把人工注意力留给真正需要判断的地方即：
Machine Handles Routine
Human Handles Judgment40. 真正重要的指标
不要重点优化：
Tokens Generated
Tool Calls
Tasks Started文章提出一个很有意思的指标：
Accepted Outputs
----------------
Human Review Minutes即：
每投入一分钟人工审核时间，能够获得多少被接受的有效产出。
41. 为什么这个指标重要
Harness 真正应该做到：
Model Capability
↓
Useful Work
↓
Reviewable Work
↓
Low Human Effort如果：
Agent 做 1 小时
↓
人检查 1 小时自动化价值就有限。
真正目标是：
Agent 产生大量高质量工作
↓
人只需要少量检查42. Prompt → Context → Harness
整个文章最终可以浓缩成三层：
Prompt Engineering
What should I tell the model?我应该告诉模型什么？
Context Engineering
What should the model know right now?模型现在应该知道什么？
Harness Engineering
What system lets the model
act,
prove its work,
recover,
and improve safely?什么样的系统可以让模型：
Act
证明工作
Recover
安全改进43. 六层 Harness 总图
USER REQUEST
│
▼
┌────────────────┐
│ TASK CONTRACT │
│ │
│ Goal │
│ Constraints │
│ Done When │
│ Escalate When │
└───────┬────────┘
│
▼
┌────────────────┐
│ CONTEXT │
│ COMPILER │
│ │
│ High Signal │
│ Just-in-Time │
└───────┬────────┘
│
▼
┌─────────┐
│ MODEL │
└────┬────┘
│
Tool Request
│
▼
┌────────────────┐
│ TOOL GATEWAY │
│ │
│ Schema │
│ Permission │
│ Risk │
│ Sandbox │
└───────┬────────┘
│
▼
Tool
│
▼
Observation
│
▼
┌────────────────┐
│ DURABLE STATE │
│ │
│ Facts │
│ Decisions │
│ State │
│ Lessons │
└───────┬────────┘
│
▼
┌────────────────┐
│ EVIDENCE GATE │
│ │
│ Tests │
│ Schema │
│ Screenshot │
│ Reviewer │
└───────┬────────┘
│
┌──────────┼──────────┐
▼ ▼ ▼
ACCEPT RETRY ESCALATE
│
▼
┌────────────────┐
│ TRACE & │
│ RECOVERY │
│ │
│ Classify │
│ Repair │
│ Regression │
└────────────────┘44. 文章最重要的工程思想
① Prompt 不是系统
Prompt ⊂ Harness② Context 要编译，不要堆积
Right Context
>
More Context③ 模型提出操作，Harness 决定能不能执行
Model Proposes
Policy Authorizes
Tool Executes④ Memory 不是聊天历史
Memory
=
最小必要长期信息⑤ Evidence 决定 Done
Model says done
≠
Done
Evidence passes
=
Done⑥ Failure 应该改善系统
Failure
↓
Infrastructure Improvement45. Harness Engineering 的核心闭环
最终可以浓缩为：
Contract
↓
Context
↓
Execute
↓
Observe
↓
Persist
↓
Verify
↓
Pass?
├── Yes → Done
└── No
↓
Classify Failure
↓
Repair Harness
↓
Retry Exact Case46. 最值得背下来的几个概念
Task Contract
Context Compiler
Progressive Disclosure
Tool Gateway
Permission Boundary
Durable State
Facts / Decisions / State / Lessons
Evidence Gate
Deterministic Checks
Independent Verifier
Trace
Recovery
Regression Test
Human Approval
Bounded Retry47. 一句话理解 Harness
Harness 就是模型周围那套负责给它正确上下文、限制它如何行动、保存执行状态、验证结果、处理失败，并让经验不断沉淀的工程系统。
48. 一句话理解 Harness Engineering
Harness Engineering 的目标，不是让模型“更会回答”，而是让一个有能力的模型能够长期、可控、可验证、可恢复地完成真实任务。
49. 最终记忆版
只需要记住：
CONTRACT
定义任务
CONTEXT
给正确的信息
TOOLS
控制行动
STATE
记住进度
EVIDENCE
证明结果
RECOVERY
从失败中学习进一步浓缩：
Define → Inform → Act → Remember → Prove → Improve
这就是这篇文章的整个 Harness Engineering 框架。