如何驯服AI这头狂飙的野马?

Harness Engineering 通用范式指南，真实项目中的一次harness实践

版本：1.0 | 适用：任何使用大模型辅助开发的软件项目

1. 什么是 Harness Engineering

Harness Engineering（驾驭工程/缰绳工程） 是一种面向大模型辅助开发的工程范式。其核心思想是：

不比拼模型能力，而是比拼"缰绳"设计。

将大模型视为一匹爆发力极强的野马——Prompt Engineering 是教它听懂指令，RAG 是给它补充地图，而 Harness Engineering 是给它设计缰绳、马鞍、围栏和赛道系统。

三代范式演进

阶段	核心	局限
Prompt Engineering	单次输入的"魔法咒语"	无法处理长周期、多步骤任务
Context Engineering	如何高效填充上下文窗口	只解决"输入什么"，不解决"如何运转"
Harness Engineering	设计智能体的运行环境与制度体系	需要系统性架构思维

2. 核心原则

2.1 渐进式披露（Progressive Disclosure）

给 AI 的文档应该是地图，而非百科全书。

❌ 错误：把所有信息塞进一个 2000 行的 AGENTS.md
✅ 正确：100 行的 CLAUDE.md + 专题化的 docs/ 目录

2.2 状态外化（State Externalization）

黄金法则：状态必须外化到文件系统，上下文窗口不是存储。

AI 的"记忆"应该写入文件，而非依赖对话历史
长周期任务必须在文件系统中留下状态痕迹
每次会话开始时从文件系统恢复，而非从对话历史恢复

2.3 分离做事与评判（Separation of Concerns）

角色	职责
Planner	拆解任务、识别依赖、制定方案
Generator	编写代码、执行操作
Evaluator	审查输出、检测违规、打分反馈

即使是单人开发，也应在流程中显式区分这三个角色。

2.4 约束即生产力（Constraints as Productivity）

架构边界通过代码和配置强制执行，而非文档约定
白名单机制优于黑名单机制
每个约束都是对"模型不能做什么"的假设编码

2.5 熵管理（Entropy Management）

Harness 自身会随时间腐化：

文档漂移（代码改了，文档没改）
规则过时（模型进化了，旧约束不再必要）
依赖膨胀（引入后不再使用的包）

必须建立定期的 Harness 健康检查机制。

3. 最小可行 Harness（MVH）

任何项目都可以在 30 分钟内 建立最小可行 Harness：

project-root/
├── CLAUDE.md                    # AI 地图（必读）
├── docs/
│   ├── architecture.md          # 系统架构
│   ├── contracts.md             # 接口/契约登记
│   └── decisions/               # 技术决策记录
├── scripts/
│   └── audit-harness.js         # 健康检查脚本
└── memory/                      # AI 状态外化
    └── session-state.md         # 会话状态恢复

3.1 CLAUDE.md 模板

# [项目名] — AI 开发地图

## 1. 项目定位
- 一句话描述项目解决什么问题
- 目标用户是谁

## 2. 技术栈锁定
| 层级 | 技术 | 版本 |
|:---|:---|:---|
| 前端 | React | 18 |
| 后端 | Go | 1.21 |
| 数据库 | PostgreSQL | 15 |

## 3. 架构边界
- 服务 A 负责什么，服务 B 负责什么
- 不可逾越的边界规则

## 4. 核心约束（Golden Constraints）
- 通信协议约束
- 安全约束
- 构建约束
- 代码约束

## 5. 目录结构约定

6. 开发流程

规划 → 2. 编码 → 3. 审查 → 4. 同步文档 → 5. 提交

7. 已知限制

技术债务、环境限制、外部依赖风险

8. 何时更新本文件

技术栈变更
架构边界调整
新增核心约束


### 3.2 健康检查脚本核心检查项

| 检查项 | 目的 |
|:---|:---|
| 核心文档存在性 | 确保 CLAUDE.md 和契约文档不丢失 |
| 配置死引用 | 检测已删除但仍在配置中引用的文件 |
| 契约同步 | 确保代码中的接口与契约文档一致 |
| 依赖冗余 | 发现可能未使用的包 |
| 代码风格 | ESLint/Prettier 配置完整性 |

---

## 4. 文件体系详解

### 4.1 CLAUDE.md — AI 地图

**定位**：AI 每次会话的第一份阅读材料。

**设计原则**：
- **不超过 200 行**。超过则意味着信息过载，需要拆分。
- **只放"地图"级信息**：方向、边界、约束、约定。
- **不放"百科全书"**：具体 API 签名、详细数据格式应放在 `docs/` 下。

**必须包含的章节**：
1. 项目定位（1-2 句话）
2. 技术栈锁定（表格形式）
3. 架构边界（文字 + ASCII 图）
4. 核心约束（编号列表）
5. 目录结构约定
6. 开发流程
7. 已知限制
8. 更新触发条件

### 4.2 docs/contracts.md — 接口契约

**定位**：所有跨边界接口的权威登记簿。

**适用场景**：
- 前后端 API 接口
- 微服务间 gRPC/消息队列接口
- Electron IPC 通道
- 数据库表结构约定

**每条契约必须包含**：
| 属性 | 说明 |
|:---|:---|
| 名称 | 接口标识 |
| 方向 | 调用方 → 被调用方 |
| 模式 | SYNC / ASYNC / EVENT |
| 参数 | 类型和必填性 |
| 返回值 | 类型和结构 |
| 副作用 | 是否有状态变更 |
| 安全级别 | 🟢安全 🟡受限 🔴高危 |

**新增接口 checklist**：
- [ ] 在契约文档中登记
- [ ] 在代码中实现对应的校验/白名单
- [ ] 更新 CLAUDE.md 中的接口概述
- [ ] 运行健康检查验证同步

### 4.3 docs/decisions/ — 技术决策记录

**ADR（Architecture Decision Record）格式**：

```markdown
# ADR-001: 使用 Electron 而非 Tauri

## 状态
已接受

## 背景
需要桌面端应用，候选方案：Electron、Tauri、Flutter Desktop。

## 决策
选择 Electron 22。

## 理由
1. 团队熟悉 Node.js 生态
2. 需要加载远程网页，WebView 能力是刚需
3. Tauri 的 WebView2 在 Windows 7 支持上有问题

## 后果
- 包体积较大（接受）
- 内存占用较高（通过精简依赖缓解）

4.4 memory/session-state.md — 会话状态

定位：跨 AI 会话的状态恢复点。

内容示例：

# 会话状态 — 2026-05-29

## 当前进行中的任务
- 价格评估引擎从客户端迁移到服务端（已完成 80%）

## 已完成的近期变更
- 精简了 12 个废弃依赖
- 移除 WebSocket，统一走 IPC

## 待解决问题
- libs/ 下还有 15 处 console.log 待迁移到 logger.js

## 下次会话建议入口
1. 读取 CLAUDE.md
2. 查看 docs/ipc-contracts.md 是否有变更
3. 继续价格评估引擎优化

4.5 scripts/audit-harness.js — 健康检查

运行频率：

每次提交前：快速检查（文档存在性 + 契约同步）
每周一次：完整检查（+ 依赖冗余 + 代码风格）
每次模型升级后：压力测试 Harness（看看哪些约束可以简化）

退出码约定：

0：检查通过
1：发现阻塞性问题（死引用、契约不同步）
2：仅警告（风格问题、建议优化）

5. 使用工作流

5.1 日常开发工作流

┌─────────────────┐
│  1. 读取 CLAUDE.md  │ ← 每次新会话必做
└────────┬────────┘
         ▼
┌─────────────────┐
│  2. 读取 session-state │ ← 恢复上下文
└────────┬────────┘
         ▼
┌─────────────────┐
│  3. 规划（Planner）   │ ← 复杂任务先用 /plan
└────────┬────────┘
         ▼
┌─────────────────┐
│  4. 编码（Generator）  │ ← 执行实现
└────────┬────────┘
         ▼
┌─────────────────┐
│  5. 审查（Evaluator）  │ ← 运行 audit-harness.js
└────────┬────────┘
         ▼
┌─────────────────┐
│  6. 同步文档         │ ← 更新 CLAUDE.md / contracts.md
└────────┬────────┘
         ▼
┌─────────────────┐
│  7. 更新 session-state │ ← 记录完成和待办
└─────────────────┘

5.2 新增接口工作流

在 docs/contracts.md 中设计契约（先写文档，后写代码）
在代码中实现接口
在边界处添加校验（白名单、类型检查）
运行 audit-harness.js 验证同步
更新 CLAUDE.md 中的接口概述
提交代码 + 文档变更

5.3 代码清理工作流

识别废弃代码/依赖
删除代码
同步删除配置中的引用（package.json files、import 语句等）
运行 audit-harness.js 确认无死引用
更新 CLAUDE.md 中的目录结构（如需要）
提交

6. 最佳实践

6.1 文档即代码（Docs as Code）

所有 Harness 文档使用 Markdown，与代码同仓库管理
文档变更走与代码相同的 PR/MR 流程
使用 audit-harness.js 自动化验证文档与代码的同步

6.2 约束的机械化执行

约束类型	执行方式	示例
模块边界	目录结构 + ESLint `no-restricted-imports`	禁止 `renderer/` 引用 `main/` 的模块
接口边界	契约文档 + 运行时白名单	Electron `validChannels` 数组
构建边界	CI 检查 + 配置白名单	`build.files` 数组
代码风格	Linter + Prettier + Git Hooks	`npm run lint` 在提交前自动运行

6.3 模型进化时的 Harness 简化

反常识：Harness 不是越复杂越好。模型的进化会让某些组件"失效"。

每次底层模型升级后，审视现有约束是否仍有必要
如果模型已经能稳定处理某类任务，移除对应的约束
保持 Harness 的"最小必要复杂度"

6.4 多 Agent 协作的最小实现

即使没有多 Agent 框架，也可以在单个 AI 会话中模拟：

用户：请帮我实现 XX 功能

AI（Planner）：先制定计划，列出步骤和依赖
用户：确认计划

AI（Generator）：按计划执行编码

用户：请审查刚才的代码
AI（Evaluator）：切换到审查角色，检查边界条件、错误处理、代码风格

AI（Generator）：根据审查意见修复

7. 常见问题

Q1: Harness 会不会增加太多开发负担？

A: MVH 只需要 30 分钟搭建，日常维护每次 5 分钟。相比之下，AI 因上下文丢失而重复犯错、因边界不清而产生 bug 的代价要高得多。

Q2: 小项目（1-2 人）也需要 Harness 吗？

A: 越是小项目越需要。大团队有 code review 和架构评审来弥补，小团队只有 Harness 能防止 AI "自由发挥"导致的技术债务。

Q3: CLAUDE.md 和 README.md 有什么区别？

A: README 面向人类用户（安装、使用、贡献），CLAUDE.md 面向 AI（架构、约束、约定、状态）。两者可以互相链接，但受众不同。

Q4: 如何处理敏感信息？

永远不要把密钥、密码写入任何 Harness 文档
使用 .env.example 记录环境变量名（不含真实值）
在 CLAUDE.md 中标注"敏感信息通过环境变量注入，不在代码中硬编码"

Q5: 健康检查脚本报 "可能未使用的依赖"，但实际在用？

A: 轻量级检查基于 require() / import 的文本搜索。某些依赖通过 CLI 脚本使用（如 eslint、jest），需要加入脚本的白名单正则中。

8. 演进路线图

Level 1: 文档化（当前）

✅ CLAUDE.md
✅ 接口契约
✅ 健康检查

Level 2: 自动化

[ ] Git Hooks：提交前自动运行 audit-harness.js
[ ] CI 集成：PR 时自动检查契约同步
[ ] 文档自动生成：从代码注释生成 API 文档

Level 3: 智能化

[ ] AI 自审：提交前让 AI 以 Evaluator 角色审查自己的输出
[ ] 约束推断：AI 自动从代码中推断并建议契约登记
[ ] 熵预测：AI 识别哪些文档/约束可能已过时

Level 4: 生态化

[ ] 跨项目 Harness 复用：同一技术栈的项目共享基础 Harness
[ ] Harness 市场：开源社区共享经过验证的约束模板
[ ] 模型自适应 Harness：根据当前模型能力自动调整约束强度

附录：快速启动命令

# 1. 创建 CLAUDE.md
# 复制本指南中的模板，填入项目信息

# 2. 创建 docs/ 目录结构
mkdir -p docs/decisions scripts memory

# 3. 创建健康检查脚本
# 复制本指南配套脚本（Node.js / PowerShell / Python 版本）

# 4. 首次运行检查
node scripts/audit-harness.js

# 5. 集成到 package.json
npm pkg set scripts.audit="node scripts/audit-harness.js"

参考资源（平台禁止使用外链，文章可自行搜索）

Harness Engineering: 驾驭大模型的工程新范式
从上下文工程到 Harness Engineering
OpenAI Harness Engineering — Plans as Code
Conventional Commits
Architecture Decision Records

最后

本篇harness总结为本人真实项目踩坑浪费了很多token后凝练出来的原创制作，引用时请注明来源，谢谢