5.4 KiB
5.4 KiB
title, tags, source, confidence_score, last_updated
| title | tags | source | confidence_score | last_updated | ||||||
|---|---|---|---|---|---|---|---|---|---|---|
| 构建你的第一个 Harness |
|
|
高 | 2026-04-07 |
构建你的第一个 Harness
本文提供了构建 Harness 的实用框架，从个人开发者到工程组织的三个级别。
Level 1：基础 Harness（单个开发者）
如果你正在为个人项目使用 Claude Code、Cursor 或 Codex：
需要设置的内容
CLAUDE.md或.cursorrules文件，包含项目约定- 用于 linting 和格式化的预提交钩子
- 智能体可以运行以自我验证的测试套件
- 具有一致命名的清晰目录结构
设置时间： 1-2 小时
影响： 防止最常见的智能体错误
快速入门清单
-
创建 CLAUDE.md
# 项目约定 ## 代码风格 - 使用 TypeScript，严格模式 - 使用 2 空格缩进 - 函数名使用驼峰命名 ## 测试 - 所有新代码必须有测试 - 提交前运行 `npm test` ## 目录结构 - src/ - 源代码 - tests/ - 测试文件 - docs/ - 文档 -
设置预提交钩子
# 使用 husky 或 pre-commit npm install husky --save-dev npx husky install -
确保测试存在
- 即使是简单的集成测试也比没有好
- 智能体需要可以运行的东西来验证其工作
Level 2：团队 Harness（小团队）
对于共享代码库的 3-10 名开发者的团队：
在 Level 1 基础上添加
- 包含团队范围约定的
AGENTS.md - CI 强制执行的架构约束
- 常见任务的共享提示模板
- 由 linter 验证的文档即代码
- 专门针对智能体生成的 PR 的代码审查清单
设置时间： 1-2 天
影响： 整个团队的智能体行为一致
AGENTS.md 结构建议
# AGENTS.md
本文档包含智能体在此代码库中工作的约定。
## 1. 架构原则
- 我们使用分层架构：Types → Config → Repo → Service → API
- 不要跨层导入
- 所有外部依赖通过 Providers 访问
## 2. 编码标准
- [具体规则...]
## 3. 测试策略
- [具体指南...]
## 4. 审查清单
- [智能体在提交前应检查的内容...]
共享提示模板
创建一个 prompts/ 目录，包含常见任务：
prompts/add-new-feature.mdprompts/fix-bug.mdprompts/write-tests.mdprompts/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 就有差距。智能体需要的一切都必须在仓库中。
从哪里开始
如果你是单个开发者
- 从 Level 1 开始
- 创建一个简单的
CLAUDE.md - 设置基础预提交钩子
- 添加一个简单的测试套件
- 迭代——观察智能体失败的地方并加以修复
如果你是一个团队
- 首先就 Level 1 基础达成一致
- 一起编写
AGENTS.md的初稿 - 识别最常见的 3 个智能体失败模式
- 为这些模式构建前 3 个约束/检查
- 每 2 周回顾一次什么有效/什么无效
如果你是一个组织
- 从一些试点团队开始
- 收集什么有效的模式
- 构建可重用的 Harness 组件库
- 投资于可观测性和指标
- 建立 Harness 迭代的反馈循环
相关概念
参考来源
- NxCode - Harness Engineering: The Complete Guide
- OpenAI - Harness Engineering：在智能体优先的世界中利用 Codex
- Martin Fowler - Harness engineering for coding agent users
最后更新：2026-04-07
本文档由 WikiLLM 编译自多个来源