🚀 Harness Engineering Bible

AI Agent 开发实战指南 — 从理论到实践，让 AI 智能体可靠地完成工作

核心洞察："Agents aren't hard; the Harness is hard." — Ryan Lopopolo (OpenAI, 2026)

🎯 这是什么

Harness Engineering Bible 是一本 AI Agent 开发实战指南，教你如何设计约束系统，让 AI 智能体可靠地完成工作。

不是理论书，是实战手册。

📊 真实案例：OpenAI 内部实践

案例：3人团队，5个月，100万行代码

团队配置：

3 名工程师（后扩展到 7 人）
0 行手写代码
全部由 Codex 生成

产出数据：

代码量：~100 万行
PR 数量：~1500 个
人均 PR：每天 3.5 个
单次运行：持续 6+ 小时（人类睡眠期间）

效率对比：

指标	传统开发	Harness Engineering	提升
PR 周期	3-7 天	分钟-小时	95%
代码审查	人工	自动化	100%
人均产出	0.2 PR/天	3.5 PR/天	17.5 倍
工作时间	8 小时/天	24 小时/天	3 倍

关键成果：

✅ 零手写代码，全部由 AI 生成
✅ 人类只负责设计约束和验证结果
✅ 扩展到 7 人后吞吐量仍在增长
✅ AI 可在人类睡眠时持续工作

💡 什么是 Harness Engineering？

Harness Engineering 是 OpenAI 在 2026 年 2 月提出的工程范式变革。

核心理念

工程师不再写代码，而是设计环境、明确意图、构建反馈回路，让 AI 智能体可靠地完成工作。

范式对比

graph LR
    subgraph "传统软件工程"
        A1[人类写代码] --> A2[人工 Code Review]
        A2 --> A3[手动测试]
        A3 --> A4[部署]
    end
    
    subgraph "Harness Engineering"
        B1[人类设计约束] --> B2[AI 生成代码]
        B2 --> B3[自动化验证]
        B3 --> B4[自动部署]
    end
    
    style B1 fill:#4CAF50,stroke:#388E3C,stroke-width:2px,color:#fff
    style B2 fill:#4CAF50,stroke:#388E3C,stroke-width:2px,color:#fff
    style B3 fill:#4CAF50,stroke:#388E3C,stroke-width:2px,color:#fff
    style B4 fill:#4CAF50,stroke:#388E3C,stroke-width:2px,color:#fff

维度	传统软件工程	Harness Engineering
核心工作	写代码	设计约束系统
验证方式	人工 Code Review	机械化验证
PR 周期	数天/周	分钟/小时
智能体角色	辅助工具	主要代码生产者
人类角色	执行者	架构师/掌舵者

🎬 实战案例

案例 1：电商后台重构

背景：

遗留代码：5 万行 PHP
技术债务：无测试、无文档、无类型
目标：迁移到 TypeScript + Next.js

使用 Harness Engineering：

第 1 步：设计约束（AGENTS.md）

# 重构约束

## 目标
- 保持 API 兼容性
- 100% 测试覆盖率
- 类型安全

## 禁止
- 修改数据库 schema
- 删除现有 API
- 引入新依赖（未经批准）

## 验证
- `npm test` 必须通过
- `npm run type-check` 必须通过
- `npm run lint` 必须通过

第 2 步：AI 执行

# AI 自动生成代码
codex refactor --input src/legacy --output src/new

# 自动化验证
npm test && npm run type-check && npm run lint

第 3 步：人类验证

# 查看差异
git diff

# 验证功能
npm run dev

结果：

重构时间：3 天（传统方式需要 3 个月）
代码质量：100% 测试覆盖率
Bug 数量：0 个（自动化验证）
人工工作：设计约束 2 小时 + 验证 4 小时

案例 2：API 文档自动生成

背景：

50 个 API 接口
文档过时
手动维护成本高

使用 Harness Engineering：

第 1 步：设计约束

// api.schema.ts
export interface APIEndpoint {
  method: 'GET' | 'POST' | 'PUT' | 'DELETE';
  path: string;
  params: Record<string, ParamType>;
  response: ResponseType;
  example: Example;
}

第 2 步：AI 生成文档

codex generate-docs --input src/api --output docs/api.md

第 3 步：自动化验证

# 验证文档和代码一致性
npm run validate-docs

结果：

生成时间：5 分钟（传统方式需要 2 天）
准确率：100%（代码即文档）
维护成本：0（自动同步）

案例 3：多语言国际化

背景：

支持 10 种语言
1000+ 翻译条目
手动翻译易出错

使用 Harness Engineering：

第 1 步：设计约束

// i18n.schema.json
{
  "type": "object",
  "required": ["en", "zh", "ja", "ko"],
  "properties": {
    "en": { "type": "string" },
    "zh": { "type": "string" },
    "ja": { "type": "string" },
    "ko": { "type": "string" }
  }
}

第 2 步：AI 翻译

codex translate --input locales/en.json --output locales/

第 3 步：自动化验证

# 验证所有语言的 key 一致
npm run validate-i18n

结果：

翻译时间：10 分钟（传统方式需要 1 周）
准确率：95%（人工校对 5%）
成本节省：¥5000（翻译费用）

📚 六大核心概念

1. Repo as Source of Truth（代码库即真理）

核心思想： 所有规则必须内嵌在代码库，可机械化验证。

落地工具：

AGENTS.md：智能体导航文件
ESLint 规则：代码风格约束
TypeScript：类型约束

示例：

# AGENTS.md

## 代码风格
- 使用 2 空格缩进
- 函数名使用 camelCase
- 类名使用 PascalCase

## 验证
- `npm run lint` 必须通过

2. Mechanical Enforcement（机械化执行）

核心思想： 用 linter、测试、CI/CD 强制执行，不依赖人工。

落地工具：

Pre-commit：提交前自动检查
GitHub Actions：CI/CD 自动化
Husky：Git hooks

示例：

# .github/workflows/ci.yml
name: CI
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - run: npm install
      - run: npm test
      - run: npm run lint
      - run: npm run type-check

3. Entropy & GC（熵增与清理）

核心思想： 系统会自然熵增，需定期清理技术债务。

落地工具：

自动化 GC 脚本
技术债务看板
定期重构

示例：

# gc.sh
# 删除未使用的依赖
npm prune

# 删除未使用的代码
npx ts-prune

# 更新过时的依赖
npm outdated

4. Agent Readability（智能体可读性）

核心思想： 代码首先给智能体看，其次给人看。

落地方法：

明确命名
固定分层结构
详细注释

示例：

// ❌ 不好：命名不清晰
function f(x: any) {
  return x * 2;
}

// ✅ 好：命名清晰
function doubleNumber(input: number): number {
  return input * 2;
}

5. Throughput Changes Merge（吞吐量优先合并）

核心思想： PR 生命周期短，偶发失败重跑。

落地方法：

自动化重跑
短周期 PR (<200 行)
快速合并

示例：

# .github/workflows/auto-merge.yml
name: Auto Merge
on:
  pull_request:
    types: [opened, synchronize]
jobs:
  auto-merge:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - run: npm test
      - uses: pascalgn/automerge-action@v0.15.6
        if: success()

6. Humans Steer, Agents Execute（人类掌舵，智能体执行）

核心思想： 人类负责设计约束和验证结果，AI 负责执行。

落地方法：

约束设计
意图明确
结果验证

示例：

# 人类：设计约束
## 目标
- 实现用户登录功能
- 支持邮箱和手机号登录
- 密码加密存储

## 约束
- 使用 bcrypt 加密
- 密码长度 >= 8 位
- 登录失败 5 次锁定账号

# AI：执行
[生成代码...]

# 人类：验证
- 测试登录功能
- 检查密码加密
- 验证锁定逻辑

🗺️ 项目导航

本项目包含 理论 + 实战 + 案例 + 工具：

harness-engineering-bible/
├── 📘 concepts/           # 核心理论（必读）
│   ├── 00-overview.md     # ⭐ 六大核心概念总览
│   ├── 01-repo-as-source-of-truth.md
│   ├── 02-mechanical-enforcement.md
│   ├── 03-entropy-and-garbage-collection.md
│   ├── 04-agent-readability.md
│   └── 05-throughput-changes-merge.md
├── 🛠️ practice/           # 实战项目（可运行）
│   ├── hello-world-agent/   # ⭐ 5 分钟入门
│   ├── micro-saas-boilerplate/ # 生产级模板
│   └── legacy-refactor/     # 真实重构案例
├── 📝 feedback/           # 踩坑记录（避坑指南）
│   ├── template.md
│   └── case-*.md
├── 🏆 works/              # 可展示作品
│   └── harness-engineering-guide.md
├── 🤖 AGENTS.md           # 智能体专用导航
└── 📖 README.md           # 本文件

🚀 快速开始

方式 1：5 分钟入门（推荐）

# 1. 克隆项目
git clone https://github.com/AIPMAndy/harness-engineering-bible.git
cd harness-engineering-bible/practice/hello-world-agent

# 2. 安装依赖
npm install

# 3. 运行测试
npm test

# 4. 启动智能体
npm start

方式 2：学习路径

阶段	内容	时间	产出
Phase 1	阅读 `00-overview.md`	30 分钟	理解核心概念
Phase 2	运行 `hello-world-agent`	15 分钟	体验完整流程
Phase 3	研读 `01-05` 概念文档	2 小时	掌握落地方法
Phase 4	使用 `micro-saas-boilerplate`	1-2 小时	构建生产级项目
Phase 5	阅读 `feedback/` 案例	30 分钟	避坑指南
Phase 6	阅读 `works/` 实战指南	1 小时	系统化认知

🎯 谁应该阅读？

✅ AI 产品负责人：想落地 AI 智能体协作流程
✅ 资深工程师：想转型为"约束架构师"
✅ 技术团队 Leader：想提升团队 AI 协作效率
✅ AI 智能体开发者：想理解如何设计可靠的 Agent 环境
✅ 开源贡献者：想参与构建下一代软件工程范式

🛠️ 推荐工具链

类别	推荐工具	作用
智能体	OpenAI Codex, Claude Code, Cursor	代码生成与修改
约束执行	ESLint, Prettier, Pre-commit	强制执行规则
CI/CD	GitHub Actions, GitLab CI	自动化验证
测试	Jest, Vitest, Pytest	功能正确性保障
监控	Prometheus, Datadog, Sentry	运行状态监控
文档	AGENTS.md, README.md	智能体导航入口

📊 效果对比

开发效率提升

指标	传统开发	Harness Engineering	提升
代码生成速度	100 行/小时	1000 行/小时	10 倍
PR 周期	3-7 天	分钟-小时	95%
人均产出	0.2 PR/天	3.5 PR/天	17.5 倍
Bug 率	5-10%	<1%	90%

成本节省

项目	传统开发成本	Harness Engineering 成本	节省
电商后台重构	¥150,000（3 个月）	¥15,000（3 天）	90%
API 文档生成	¥10,000（2 天）	¥100（5 分钟）	99%
多语言国际化	¥20,000（1 周）	¥5,000（10 分钟）	75%

🤝 如何贡献？

我们欢迎所有形式的贡献！

贡献方式：

✅ 修正文档错别字
✅ 修复代码 Bug
✅ 分享你的踩坑案例
✅ 翻译为其他语言
✅ 新增实战项目

贡献流程：

Fork 本项目
创建分支：git checkout -b feature/amazing-feature
提交更改：git commit -m 'Add some amazing feature'
推送分支：git push origin feature/amazing-feature
开启 Pull Request

📜 许可证

本项目采用 MIT 许可证 - 详见 LICENSE 文件。

🙏 致谢

Ryan Lopopolo (OpenAI) - Harness Engineering 概念提出者
OpenAI Codex Team - 提供强大的 AI 代码生成能力
所有贡献者 - 让这个项目不断进化

⭐ 如果这个项目对你有帮助

请给个 Star，让更多人看到！

人类掌舵，智能体执行

Made with 🚀 by Andy | AI酋长

让每个工程师都成为 AI Agent 架构师

Name		Name	Last commit message	Last commit date
Latest commit History 6 Commits
.github		.github
concepts		concepts
feedback		feedback
practice		practice
works		works
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
PROJECT_SUMMARY.md		PROJECT_SUMMARY.md
README.md		README.md

Folders and files

Latest commit

History

Repository files navigation

🚀 Harness Engineering Bible

🎯 这是什么

📊 真实案例：OpenAI 内部实践

案例：3人团队，5个月，100万行代码

💡 什么是 Harness Engineering？

核心理念

范式对比

🎬 实战案例

案例 1：电商后台重构

案例 2：API 文档自动生成

案例 3：多语言国际化

📚 六大核心概念

1. Repo as Source of Truth（代码库即真理）

2. Mechanical Enforcement（机械化执行）

3. Entropy & GC（熵增与清理）

4. Agent Readability（智能体可读性）

5. Throughput Changes Merge（吞吐量优先合并）

6. Humans Steer, Agents Execute（人类掌舵，智能体执行）

🗺️ 项目导航

🚀 快速开始

方式 1：5 分钟入门（推荐）

方式 2：学习路径

🎯 谁应该阅读？

🛠️ 推荐工具链

📊 效果对比

开发效率提升

成本节省

🤝 如何贡献？

📜 许可证

🙏 致谢

⭐ 如果这个项目对你有帮助

About

Resources

License

Code of conduct

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages