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]] 编译自多个来源*
|
||||
@@ -0,0 +1,150 @@
|
||||
---
|
||||
title: Mitchellh AI 采用之旅
|
||||
tags: [实践指南, 采用路径, 个人工作流]
|
||||
source: [Mitchell Hashimoto]
|
||||
confidence_score: 高
|
||||
last_updated: 2026-04-07
|
||||
---
|
||||
|
||||
# Mitchellh AI 采用之旅
|
||||
|
||||
本文总结了 HashiCorp 创始人 Mitchell Hashimoto 的个人 AI 工具采用历程。他分享了从怀疑论者到深度用户的六个阶段，为其他开发者提供了实用的参考路径。
|
||||
|
||||
## 核心观点
|
||||
|
||||
> "我采用任何有意义的工具的经验是，我必然经历三个阶段：(1) 低效率时期 (2) 胜任时期，最后 (3) 工作流和生活改变发现时期。"
|
||||
|
||||
---
|
||||
|
||||
## 六个阶段
|
||||
|
||||
### 阶段 1：放弃聊天机器人
|
||||
|
||||
**立即停止尝试通过聊天机器人执行有意义的工作**（例如 ChatGPT、网页版 Gemini 等）。
|
||||
|
||||
聊天机器人确实有价值，而且是 Mitchell AI 工作流的日常组成部分，但它们在编码中的效用非常有限，因为你大多希望它们根据先前训练得出正确结果，而纠正它们涉及人类（你）反复告诉它们错了。这是低效的。
|
||||
|
||||
**关键点：**
|
||||
- 每个人的第一次 AI 体验都是聊天界面
|
||||
- 每个人第一次尝试用 AI 编码都是要求聊天界面写代码
|
||||
- 要找到价值，你**必须**使用**智能体**（Agent）
|
||||
|
||||
**什么是智能体？**
|
||||
智能体是行业采用的术语，指能够聊天并循环调用外部行为的 LLM。至少，智能体必须具备以下能力：
|
||||
- 读取文件
|
||||
- 执行程序
|
||||
- 发起 HTTP 请求
|
||||
|
||||
---
|
||||
|
||||
### 阶段 2：重现你自己的工作
|
||||
|
||||
Mitchell 最初尝试 Claude Code 时并没有留下深刻印象。他只是没有从会话中得到好的结果。他觉得必须润色它生成的所有内容，这个过程比他自己做要花更多时间。
|
||||
|
||||
**解决方案：**
|
||||
> "我没有放弃，而是**强迫自己用智能体重现所有手动提交**。我真的做了两次工作。我会手动完成工作，然后与智能体斗争以产生相同的质量和功能结果（当然，不让它看到我的手动解决方案）。"
|
||||
|
||||
**这是痛苦的**，因为它妨碍了简单地完成事情。但 Mitchell 从第一性原理中自己发现了别人已经在说的东西，但自己发现它产生了更强的基本理解：
|
||||
|
||||
1. 将会话分解为单独清晰、可操作的任务。不要试图在一个大型会话中"画猫头鹰"。
|
||||
2. 对于模糊的请求，将工作分成单独的规划与会话。
|
||||
3. 如果你给智能体验证其工作的方法，它往往会修复自己的错误并防止回归。
|
||||
|
||||
更一般地说，他还发现了智能体当时擅长什么、不擅长什么的边界，以及对于它们擅长的任务如何实现想要的结果。
|
||||
|
||||
所有这些都导致了显著的效率提升，以至于他开始自然地使用智能体，感觉不比自己做慢（但他仍然不觉得更快，因为他主要在照看智能体）。
|
||||
|
||||
---
|
||||
|
||||
### 阶段 3：日终智能体
|
||||
|
||||
为了尝试找到一些效率，Mitchell 开始了一个新模式：**每天划出最后 30 分钟来启动一个或多个智能体。**
|
||||
|
||||
他的假设是，如果智能体能在他无论如何都不能工作的时间里取得一些**积极进展**，也许他可以获得一些效率。基本上：与其试图在他拥有的时间里做更多，不如尝试在他没有的时间里做更多。
|
||||
|
||||
**发现的有价值的工作类别：**
|
||||
|
||||
1. **深度研究会话**：要求智能体调查某个领域，例如查找特定许可证类型的特定语言的所有库，并为每个库生成关于其优缺点、开发活动、社会情绪等的多页摘要。
|
||||
|
||||
2. **并行智能体尝试他没有时间开始的不同模糊想法**：不期望它们产生他会交付的东西，但也许可以在第二天他处理任务时阐明一些未知的未知。
|
||||
|
||||
3. **问题和 PR 分类/审查**：智能体擅长使用 `gh`（GitHub CLI），因此手动编写了一个快速方法来并行启动一堆来分类问题。不会允许智能体回复，只想要第二天的报告来尝试引导他走向高价值或低工作量的任务。
|
||||
|
||||
**结果：**
|
||||
他开始感觉自己比 AI 之前做的更多，哪怕只是一点点。
|
||||
|
||||
---
|
||||
|
||||
### 阶段 4：外包稳操胜券的任务
|
||||
|
||||
到了这个阶段，Mitchell 对他的 AI 擅长和不擅长什么任务非常有信心。他对某些任务 AI 会实现基本正确的解决方案有非常高的信心。
|
||||
|
||||
**所以旅程的下一步是：让智能体做所有这些工作，而他做其他任务。**
|
||||
|
||||
更具体地说：
|
||||
- 每天从查看前一晚分类智能体的结果开始
|
||||
- 手动过滤以找到智能体几乎肯定会很好解决的问题
|
||||
- 让它们在后台继续（一次一个，不是并行）
|
||||
|
||||
**同时，他做其他事情。** 不是去社交媒体（比平时不用 AI 更多），不是看视频等。他处于自己的、正常的、AI 之前的深度思考模式，处理他想做或必须做的事情。
|
||||
|
||||
**非常重要：关闭智能体桌面通知。** 上下文切换非常昂贵。为了保持效率，他发现作为人类控制何时中断智能体是他的工作，而不是相反。不要让智能体通知你。在工作的自然休息时间，切换标签检查它，然后继续。
|
||||
|
||||
**结果：**
|
||||
他坚定地处于"我无法回去"的境地。他觉得更有效率，但即使不是，他最喜欢的是他现在可以将编码和思考集中在他真正喜欢的任务上，同时仍然充分完成他不喜欢的任务。
|
||||
|
||||
---
|
||||
|
||||
### 阶段 5：设计 Harness
|
||||
|
||||
冒着陈述显而易见的风险：智能体在第一次产生正确结果时效率要高得多，或者最坏情况下产生需要最少润色的结果。实现这一点的最可靠方法是给智能体快速、高质量的工具来自动告诉它什么时候错了。
|
||||
|
||||
Mitchell 不知道是否有一个广泛的行业接受的术语，但他已经逐渐称之为"**Harness 工程**"。这是这样一种想法：任何时候你发现智能体犯了错误，你都花时间设计一个解决方案，使智能体永远不会再犯那个错误。
|
||||
|
||||
**这有两种形式：**
|
||||
|
||||
1. **更好的隐式提示（AGENTS.md）**：对于简单的事情，比如智能体反复运行错误的命令或找到错误的 API，更新 `AGENTS.md`（或等效文件）。每一行都是基于坏的智能体行为，并且几乎完全解决了所有问题。
|
||||
|
||||
2. **实际的编程工具**：例如，截图脚本、运行过滤测试等。这通常与 AGENTS.md 更改配对，让它知道这存在。
|
||||
|
||||
**这就是 Mitchell 今天所处的位置。** 他正在真诚地努力，每当看到智能体做坏事时，防止它再做那件坏事。或者，相反，他正在真诚地努力让智能体验证它们在做好事。
|
||||
|
||||
---
|
||||
|
||||
### 阶段 6：始终运行一个智能体
|
||||
|
||||
与阶段 5 同时，Mitchell 也在**始终运行一个智能体**的目标下运作。如果智能体没有运行，他会问自己："现在有什么智能体可以为我做的吗？"
|
||||
|
||||
他特别喜欢将其与较慢、更深思熟虑的模型结合使用，比如 Amp 的 [deep mode](https://ampcode.com/news/deep-mode)（基本上只是 GPT-5.2-Codex），这可能需要 30 多分钟来做小的更改。另一面是它确实倾向于产生非常好的结果。
|
||||
|
||||
**重要说明：**
|
||||
- 他还没有运行多个智能体，目前也真的不想。
|
||||
- 他觉得现在有一个智能体运行是一个很好的平衡，既能做他觉得愉快的深度手动工作，又能照看他有点愚蠢但又神秘高效的机器人朋友。
|
||||
|
||||
"始终运行一个智能体"的目标仍然只是一个目标。他会说现在他在正常工作日的 10 到 20% 时间里有效地运行后台智能体。但他正在积极努力改善这一点。
|
||||
|
||||
> "我不想为了运行智能体而运行智能体。我只希望在有任务我认为对我真正有帮助时运行它们。这个目标的一部分挑战是改善我自己的工作流和工具，以便我能有源源不断的高质量工作可以委托。即使没有 AI，这也很重要！"
|
||||
|
||||
---
|
||||
|
||||
## 今天
|
||||
|
||||
这就是 Mitchell 今天所处的位置。
|
||||
|
||||
通过这段旅程，他个人已经达到了一个点，他在现代 AI 工具上取得了成功，并且相信他正在以基于现实的适当衡量观点来处理它。他真的不在乎 AI 是否会留下来，他是一个软件工匠，只是为了热爱而构建东西。
|
||||
|
||||
整个格局变化如此之快，他相信他会很快回头看这篇帖子，嘲笑自己的天真。但正如他们所说，如果你不能为过去的自己感到尴尬，你可能就没有成长。他只希望他会朝着正确的方向成长！
|
||||
|
||||
## 相关概念
|
||||
|
||||
- [[Harness-Engineering|Harness 工程]]
|
||||
- [[Agent|智能体]]
|
||||
|
||||
## 参考来源
|
||||
|
||||
1. Mitchell Hashimoto - My AI Adoption Journey
|
||||
|
||||
---
|
||||
|
||||
*最后更新：2026-04-07*
|
||||
*本文档由 [[WikiLLM]] 编译*
|
||||
Reference in New Issue
Block a user