# Awesome Harness Engineering 知识库

> 基于 [awesome-harness-engineering](https://github.com/walkinglabs/awesome-harness-engineering) 策展的 36 篇核心文章，系统梳理 AI Agent 的 Harness Engineering 最佳实践。
>
> **目标受众：** 技术管理者 / 架构师
> **语言：** 中文为主，英文术语保留原文
> **最后更新：** 2026-04-02

---

## 如何使用本知识库

本知识库包含两层内容：

1. **逐篇读书笔记**（`notes/`）：每篇文章的结构化摘要，包含核心论点、关键概念、实践建议和交叉引用
2. **主题综述**（`insights/`）：融合多篇文章的跨文章洞见，按主题提炼为系统化知识

**推荐阅读路径：**
- 如果你想快速了解全貌 → 先读 6 篇主题综述
- 如果你对某个具体话题感兴趣 → 从综述中的引用跳转到对应的读书笔记
- 如果你想深入某篇原文 → 每篇笔记都包含原文链接

---

## 主题综述导读

### 📐 [Harness Engineering 基础](insights/01-harness-engineering-foundations.md)
**融合文章：** #01-#08（8 篇）

Agent 的表现瓶颈不在模型能力，而在围绕模型的系统设计质量。本文梳理 harness 的定义边界（vs framework vs runtime）、核心组件、设计原则，以及长时运行 agent 的特殊挑战。核心洞见：**harness 是连接、保护和编排组件的基础设施层，它本身不做工作，但决定了工作能否可靠地完成。**

### 🧠 [Context Engineering](insights/02-context-engineering.md)
**融合文章：** #09-#15（7 篇）

从 prompt engineering 到 context engineering 的范式转变。Context 是有限的稀缺资源，每个 token 都有 n² 级别的计算成本。本文深入探讨压缩技术（backpressure、condensation）、CLAUDE.md 最佳实践、外部化记忆策略。核心洞见：**找到"最小的高信号 token 集合"来最大化期望输出的概率。**

### 🛡️ [安全约束与自主性](insights/03-safety-constraints-autonomy.md)
**融合文章：** #16-#23（8 篇）

当 agent 拥有 bash、git、网络权限时，安全从理论风险变成工程现实。本文覆盖分层防御模型、沙箱设计、工具设计原则、提示注入缓解、人机协作模式。核心洞见：**安全不是限制自主性，而是划定自主性的边界——约束越明确，可授予的自主权越大。**

### 📋 [Spec-Driven Development 与工作流](insights/04-spec-driven-development-workflow.md)
**融合文章：** #24-#26（3 篇）

规范（specification）才应该是 agent 开发的主要产物，代码只是规范的派生物。本文覆盖 SDD 的三个层次、12 Factor Agents 原则、AgentOps 运维框架。核心洞见：**在 agent 时代，提示是一等公民代码，规范是可执行的契约。**

### 📊 [评估与可观测性](insights/05-evaluation-observability.md)
**融合文章：** #27-#33（7 篇）

Agent 评估从"事后补充"到"核心基础设施"的认知升级。本文覆盖 eval 方法论、非确定性指标（pass@k）、基础设施噪声影响、harness engineering 对评分的实际提升（52.8%→66.5%）。核心洞见：**不要追求完美的 benchmark，而是建立能快速定位问题并迭代改进的评估闭环。**

### 🏗️ [Runtime 与多 Agent 架构](insights/06-runtime-multi-agent-architecture.md)
**融合文章：** #34-#36（3 篇）

Framework / Runtime / Harness 三层分类法、orchestrator-worker 架构、token 经济学（15× 开销）、Agent SDK 设计理念。核心洞见：**多 agent 并行化可压缩 90% 的研究时间，但 token 成本是单 agent 的 15 倍——这是用金钱换时间的工程决策。**

---

## 逐篇读书笔记索引

### Harness Engineering 基础（#01-#08）

| # | 标题 | 来源 | 笔记 |
|---|------|------|------|
| 01 | Harness Engineering: Leveraging Codex in an Agent-First World | OpenAI | [笔记](notes/01-openai-harness-engineering.md) |
| 02 | Effective Harnesses for Long-Running Agents | Anthropic | [笔记](notes/02-anthropic-effective-harnesses.md) |
| 03 | Harness Design for Long-Running Application Development | Anthropic | [笔记](notes/03-anthropic-harness-design-long-running.md) |
| 04 | The Anatomy of an Agent Harness | LangChain | [笔记](notes/04-langchain-anatomy-of-harness.md) |
| 05 | Harness Engineering | Thoughtworks | [笔记](notes/05-fowler-harness-engineering.md) |
| 06 | Building Effective Agents | Anthropic | [笔记](notes/06-anthropic-building-effective-agents.md) |
| 07 | Skill Issue: Harness Engineering for Coding Agents | HumanLayer | [笔记](notes/07-humanlayer-skill-issue.md) |
| 08 | Your Agent Needs a Harness, Not a Framework | Inngest | [笔记](notes/08-inngest-harness-not-framework.md) |

### Context Engineering（#09-#15）

| # | 标题 | 来源 | 笔记 |
|---|------|------|------|
| 09 | Effective Context Engineering for AI Agents | Anthropic | [笔记](notes/09-anthropic-context-engineering.md) |
| 10 | Context Engineering for AI Agents: Lessons from Building Manus | Manus | [笔记](notes/10-manus-context-engineering.md) |
| 11 | Context Engineering for Coding Agents | Thoughtworks | [笔记](notes/11-fowler-context-engineering-coding.md) |
| 12 | Advanced Context Engineering for Coding Agents | HumanLayer | [笔记](notes/12-humanlayer-advanced-context.md) |
| 13 | Context-Efficient Backpressure for Coding Agents | HumanLayer | [笔记](notes/13-humanlayer-backpressure.md) |
| 14 | OpenHands Context Condensation for More Efficient AI Agents | OpenHands | [笔记](notes/14-openhands-context-condensation.md) |
| 15 | Writing a Good CLAUDE.md | HumanLayer | [笔记](notes/15-humanlayer-writing-claude-md.md) |

### 安全约束与自主性（#16-#23）

| # | 标题 | 来源 | 笔记 |
|---|------|------|------|
| 16 | Beyond Permission Prompts: Making Claude Code More Secure and Autonomous | Anthropic | [笔记](notes/16-anthropic-claude-code-sandboxing.md) |
| 17 | Code Execution with MCP: Building More Efficient Agents | Anthropic | [笔记](notes/17-anthropic-code-execution-mcp.md) |
| 18 | Writing Effective Tools for Agents | Anthropic | [笔记](notes/18-anthropic-writing-tools-for-agents.md) |
| 19 | Mitigating Prompt Injection Attacks in Software Agents | OpenHands | [笔记](notes/19-openhands-prompt-injection.md) |
| 20 | Assessing Internal Quality While Coding with an Agent | Thoughtworks | [笔记](notes/20-fowler-quality-with-agents.md) |
| 21 | Anchoring AI to a Reference Application | Thoughtworks | [笔记](notes/21-fowler-anchoring-reference.md) |
| 22 | Humans and Agents in Software Engineering Loops | Thoughtworks | [笔记](notes/22-fowler-humans-and-agents.md) |
| 23 | Claude Code: Best Practices for Agentic Coding | Anthropic | [笔记](notes/23-claude-code-best-practices.md) |

### Spec-Driven Development 与工作流（#24-#26）

| # | 标题 | 来源 | 笔记 |
|---|------|------|------|
| 24 | Understanding Spec-Driven-Development: Kiro, spec-kit, and Tessl | Thoughtworks | [笔记](notes/24-fowler-sdd-tools.md) |
| 25 | 12 Factor Agents | HumanLayer | [笔记](notes/25-humanlayer-12-factor-agents.md) |
| 26 | 12-Factor AgentOps | HumanLayer | [笔记](notes/26-12-factor-agentops.md) |

### 评估与可观测性（#27-#33）

| # | 标题 | 来源 | 笔记 |
|---|------|------|------|
| 27 | Testing Agent Skills Systematically with Evals | OpenAI | [笔记](notes/27-openai-eval-skills.md) |
| 28 | How to Evaluate Agent Skills (And Why You Should) | OpenHands | [笔记](notes/28-openhands-evaluating-skills.md) |
| 29 | Demystifying Evals for AI Agents | Anthropic | [笔记](notes/29-anthropic-demystifying-evals.md) |
| 30 | Quantifying Infrastructure Noise in Agentic Coding Evals | Anthropic | [笔记](notes/30-anthropic-infrastructure-noise.md) |
| 31 | Evaluating Deep Agents: Our Learnings | LangChain | [笔记](notes/31-langchain-evaluating-deep-agents.md) |
| 32 | Improving Deep Agents with Harness Engineering | LangChain | [笔记](notes/32-langchain-improving-with-harness.md) |
| 33 | Learning to Verify AI-Generated Code | OpenHands | [笔记](notes/33-openhands-verify-ai-code.md) |

### Runtime 与多 Agent 架构（#34-#36）

| # | 标题 | 来源 | 笔记 |
|---|------|------|------|
| 34 | Agent Frameworks, Runtimes, and Harnesses, Oh My! | LangChain | [笔记](notes/34-langchain-frameworks-runtimes-harnesses.md) |
| 35 | How We Built Our Multi-Agent Research System | Anthropic | [笔记](notes/35-anthropic-multi-agent-research.md) |
| 36 | Building Agents with the Claude Agent SDK | Anthropic | [笔记](notes/36-anthropic-claude-agent-sdk.md) |

---

## 跨主题核心洞见

1. **Harness > Model**：所有主要厂商（OpenAI、Anthropic、LangChain）不约而同地得出同一结论——agent 质量的决定性因素不是模型能力，而是 harness 设计质量。LangChain 的实验数据最具说服力：仅通过 harness 优化就将 SWE-bench 分数从 52.8% 提升到 66.5%。

2. **Context 是稀缺资源**：Context window 不是"越大越好"。每个 token 都有 n² 级别的计算成本，过多的 context 会导致 "context rot"。最佳实践是找到"最小的高信号 token 集合"。

3. **约束即自由**：一个反直觉但被多方验证的洞见——更多的运行时约束不是限制了 agent，而是使其能更可靠地自主工作。沙箱、linter、类型检查、架构约束都在减少 agent 需要考虑的解空间。

4. **简单胜过复杂**：Anthropic 的"从简单开始"、Inngest 的"harness not framework"、HumanLayer 的"微 agent 模式"都指向同一方向——避免过度工程化，优先使用最简单的模式。

5. **评估驱动迭代**：不要追求完美的一次性设计，而是建立快速的 eval → identify → fix 循环。从 10-20 个测试用例开始，逐步扩展。

6. **人机协作是光谱**：从完全人类控制到完全自主是一个连续谱系，不同任务需要不同的协作模式。关键是找到每个场景的最优协作点位。

---

## 来源分布

| 来源 | 文章数 | 笔记编号 |
|------|--------|----------|
| Anthropic | 11 | #02, #03, #06, #09, #16, #17, #18, #23, #29, #30, #35, #36 |
| Thoughtworks (Martin Fowler) | 6 | #05, #11, #20, #21, #22, #24 |
| HumanLayer | 6 | #07, #12, #13, #15, #25, #26 |
| OpenHands | 4 | #14, #19, #28, #33 |
| LangChain | 4 | #04, #31, #32, #34 |
| OpenAI | 2 | #01, #27 |
| Manus | 1 | #10 |
| Inngest | 1 | #08 |

---

## 致谢

本知识库基于 [walkinglabs/awesome-harness-engineering](https://github.com/walkinglabs/awesome-harness-engineering) 策展的文章列表构建。感谢所有原文作者的智慧贡献。