init commit
This commit is contained in:
Junjian Wang
@@ -0,0 +1,201 @@
|
||||
---
|
||||
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]] 编译自多个来源*
|
||||
Reference in New Issue
Block a user