harness-engineering

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Harness Engineering

Harness工程

Harness = the operating system for AI agents working on your project. Model is CPU, context window is RAM, harness is OS.

Harness = 运行在你项目上的AI Agent的操作系统。模型是CPU，上下文窗口是RAM，Harness就是操作系统。

Core Principle

核心理念

Start simple, add complexity only when needed. Every harness component encodes an assumption about what the model can't do alone. Pressure-test these assumptions — they expire as models improve. Build for deletion.

从简起步，仅在必要时增加复杂度。 每个Harness组件都隐含了一个假设，即模型无法独立完成某件事。要对这些假设进行压力测试——它们会随着模型能力提升而失效。构建时就要考虑后续可删除。

When This Skill Activates

本技能触发时机

Signal	Action
Empty/new project	→ Full project setup (Section 1)
User frustrated with agent	→ Diagnose & fix harness gaps (Section 7)
Existing project needs improvement	→ Assess & incrementally improve
Explicit harness question	→ Reference relevant sections

触发信号	对应动作
空白/新项目	→ 完整项目搭建（第1节）
用户对Agent效果不满	→ 诊断并修复Harness缺口（第7节）
现有项目需要优化	→ 评估并逐步迭代改进
明确的Harness相关问题	→ 引用对应章节内容

Workflow

工作流

For New Projects

新项目搭建流程

Assess — What's the project? Tech stack? Team size? How will agents be used?
Setup — Create foundational harness files → read
```
references/01-project-setup.md
```
Context — Design information architecture → read
```
references/02-context-engineering.md
```
Constraints — Add guardrails and linters → read
```
references/03-constraints.md
```
Evaluate — Set up feedback loops → read
```
references/05-eval-feedback.md
```

If project involves multi-agent or long tasks → read

references/04-multi-agent.md

references/06-long-running.md

评估 — 项目是什么？技术栈是哪些？团队规模？Agent的使用场景是什么？
搭建 — 创建基础Harness文件 → 阅读
```
references/01-project-setup.md
```
上下文 — 设计信息架构 → 阅读
```
references/02-context-engineering.md
```
约束 — 添加防护规则和linters → 阅读
```
references/03-constraints.md
```
评估 — 搭建反馈回路 → 阅读
```
references/05-eval-feedback.md
```
如果项目涉及多Agent或长周期任务 → 阅读
```
references/04-multi-agent.md
```
、
```
references/06-long-running.md
```

For Diagnosis (Agent Not Performing Well)

问题诊断流程（Agent运行效果不佳时）

Read
```
references/07-diagnosis.md
```
immediately
Identify which harness layer is failing
Apply targeted fix from the relevant reference

立即阅读
```
references/07-diagnosis.md
```
定位出现故障的Harness层
从对应参考文档中选取针对性的修复方案

For Incremental Improvement

渐进式优化流程

Assess current harness maturity, identify weakest layer, improve one layer at a time.

评估当前Harness的成熟度，定位最薄弱的层级，每次只优化一个层级。

Harness Layers (Quick Reference)

Harness层级（快速参考）

Layer	What	Reference
Project Setup	AGENTS.md, docs/, directory conventions	`01-project-setup.md`
Context Engineering	What info agents see, progressive disclosure, working state	`02-context-engineering.md`
Constraints & Guardrails	Linters, type systems, architecture enforcement, safe autonomy	`03-constraints.md`
Multi-Agent Architecture	Agent separation, coordination protocols, delegation patterns	`04-multi-agent.md`
Eval & Feedback	Testing, grading, GC agents, observability	`05-eval-feedback.md`
Long-Running Tasks	Progress tracking, context resets, handoff artifacts	`06-long-running.md`
Diagnosis	When agents fail — identify root cause in harness, not model	`07-diagnosis.md`

层级	内容	参考文档
项目搭建	AGENTS.md、docs/目录、目录规范	`01-project-setup.md`
上下文工程	Agent可获取的信息、渐进式披露、运行状态	`02-context-engineering.md`
约束与防护规则	Linters、类型系统、架构约束、安全自主运行规则	`03-constraints.md`
多Agent架构	Agent职责划分、协调协议、委派模式	`04-multi-agent.md`
评估与反馈	测试、评分、GC Agent、可观测性	`05-eval-feedback.md`
长周期任务	进度追踪、上下文重置、交接产物	`06-long-running.md`
问题诊断	Agent运行故障时——定位Harness层面的根因，而非模型问题	`07-diagnosis.md`

Self-Update Protocol

自更新协议

When you discover a new reusable harness pattern during a project:

Identify which reference file it belongs to (or if it needs a new one)
Add the pattern with: what it solves, when to use it, how to implement it
Keep it concise — no fluff, just the pattern

当你在项目中发现新的可复用Harness模式时：

确认该模式所属的参考文件（或判断是否需要新增参考文件）
新增模式时需要说明：它解决什么问题、什么时候使用、如何实现
保持简洁——不要空话，只保留模式核心内容