---
title: 构建你的第一个 Harness
tags: [实践指南, 入门, Harness]
source: [NxCode, OpenAI, Martin Fowler]
confidence_score: 高
last_updated: 2026-04-07
---

# 构建你的第一个 Harness

本文提供了构建 Harness 的实用框架，从个人开发者到工程组织的三个级别。

---

## Level 1：基础 Harness（单个开发者）

如果你正在为个人项目使用 Claude Code、Cursor 或 Codex：

### 需要设置的内容

- `CLAUDE.md` 或 `.cursorrules` 文件，包含项目约定
- 用于 linting 和格式化的预提交钩子
- 智能体可以运行以自我验证的测试套件
- 具有一致命名的清晰目录结构

**设置时间：** 1-2 小时  
**影响：** 防止最常见的智能体错误

### 快速入门清单

1. **创建 CLAUDE.md**
   ```markdown
   # 项目约定
   
   ## 代码风格
   - 使用 TypeScript，严格模式
   - 使用 2 空格缩进
   - 函数名使用驼峰命名
   
   ## 测试
   - 所有新代码必须有测试
   - 提交前运行 `npm test`
   
   ## 目录结构
   - src/ - 源代码
   - tests/ - 测试文件
   - docs/ - 文档
   ```

2. **设置预提交钩子**
   ```bash
   # 使用 husky 或 pre-commit
   npm install husky --save-dev
   npx husky install
   ```

3. **确保测试存在**
   - 即使是简单的集成测试也比没有好
   - 智能体需要可以运行的东西来验证其工作

---

## Level 2：团队 Harness（小团队）

对于共享代码库的 3-10 名开发者的团队：

### 在 Level 1 基础上添加

- 包含团队范围约定的 `AGENTS.md`
- CI 强制执行的架构约束
- 常见任务的共享提示模板
- 由 linter 验证的文档即代码
- 专门针对智能体生成的 PR 的代码审查清单

**设置时间：** 1-2 天  
**影响：** 整个团队的智能体行为一致

### AGENTS.md 结构建议

```markdown
# AGENTS.md

本文档包含智能体在此代码库中工作的约定。

## 1. 架构原则
- 我们使用分层架构：Types → Config → Repo → Service → API
- 不要跨层导入
- 所有外部依赖通过 Providers 访问

## 2. 编码标准
- [具体规则...]

## 3. 测试策略
- [具体指南...]

## 4. 审查清单
- [智能体在提交前应检查的内容...]
```

### 共享提示模板

创建一个 `prompts/` 目录，包含常见任务：
- `prompts/add-new-feature.md`
- `prompts/fix-bug.md`
- `prompts/write-tests.md`
- `prompts/refactor-code.md`

---

## Level 3：生产 Harness（工程组织）

对于运行数十个并发智能体的组织：

### 在 Level 2 基础上添加

- 自定义中间件层（循环检测、推理优化）
- 可观测性集成（智能体读取日志和指标）
- 计划运行的熵管理智能体
- Harness 版本控制和 A/B 测试
- 智能体性能监控仪表板
- 智能体陷入困境时的升级策略

**设置时间：** 1-2 周  
**影响：** 智能体作为自主贡献者运作

---

## 常见 Harness 工程错误

### 1. 过度工程化控制流

> "如果你过度工程化控制流，下一个模型更新会破坏你的系统。"

模型快速改进。2024 年需要复杂管道的能力现在由单个上下文窗口提示处理。构建你的 Harness 为**可剥离的**——当模型变得足够智能不需要时，你应该能够移除"智能"逻辑。

### 2. 将 Harness 视为静态的

Harness 需要随模型一起演进。当新模型版本改进推理时，你的推理优化中间件可能会适得其反。每次重大模型更新时审查和更新 Harness 组件。

### 3. 忽略文档层

最有影响力的 Harness 改进通常是最简单的：**更好的文档**。如果你的 `AGENTS.md` 含糊，你的智能体输出也会含糊。投资于精确、机器可读的文档，作为智能体的地面真理。

### 4. 没有反馈循环

没有反馈的 Harness 是一个笼子，而不是指南。智能体需要知道它何时成功何时失败。内置：
- 任务完成前的自我验证步骤
- 作为智能体工作流一部分的测试执行
- 按任务类型的智能体成功率指标

### 5. 仅人类可读的文档

如果你的架构决策存在于人们的头脑中或智能体无法访问的 Confluence 页面中，Harness 就有差距。**智能体需要的一切都必须在仓库中。**

---

## 从哪里开始

### 如果你是单个开发者

1. 从 Level 1 开始
2. 创建一个简单的 `CLAUDE.md`
3. 设置基础预提交钩子
4. 添加一个简单的测试套件
5. 迭代——观察智能体失败的地方并加以修复

### 如果你是一个团队

1. 首先就 Level 1 基础达成一致
2. 一起编写 `AGENTS.md` 的初稿
3. 识别最常见的 3 个智能体失败模式
4. 为这些模式构建前 3 个约束/检查
5. 每 2 周回顾一次什么有效/什么无效

### 如果你是一个组织

1. 从一些试点团队开始
2. 收集什么有效的模式
3. 构建可重用的 Harness 组件库
4. 投资于可观测性和指标
5. 建立 Harness 迭代的反馈循环

---

## 相关概念

- [[Harness-Engineering|Harness 工程]]
- [[Context-Engineering|上下文工程]]
- [[Architectural-Constraints|架构约束]]
- [[Mitchellh-Adoption-Journey|Mitchellh AI 采用之旅]]

## 参考来源

1. NxCode - Harness Engineering: The Complete Guide
2. OpenAI - Harness Engineering：在智能体优先的世界中利用 Codex
3. Martin Fowler - Harness engineering for coding agent users

---

*最后更新：2026-04-07*  
*本文档由 [[WikiLLM]] 编译自多个来源*