什么是 Harness Engineering

Harness Engineering 不是某个具体产品，而是一套工程方法。

它的核心目标是把“让 AI 写代码”这件事，从随机的、单次的、不可复现的对话，变成结构化的、可重复的、可验证的工程流程。

核心定义

Harness Engineering 是把 AI、工具、规则、上下文和验证机制组织成一套可重复执行、可验证、可维护的工程支撑系统的方法。

它和普通“用 AI 写代码”的区别

维度	普通使用方式	Harness Engineering
项目上下文	每次临时解释	固化到 AGENTS.md / topics
提示词	每次手写	沉淀为 skills / commands
执行控制	混合在一起	plan / build / explore 分层
结果验证	靠经验判断	有 checklist 和回归流程
知识沉淀	留在对话记录里	写入文档，团队可复用

为什么需要它

1. 每次都要重新解释项目背景——效率低
2. 提示词不可复用——每轮都是新开始
3. 输出结果不稳定——同样的需求，不同结果
4. 分析、修改、验证混在一起——容易误改
5. 没有知识沉淀——经验和对话一起消失

在 AI 工具场景下的含义

围绕各类 AI 编码工具构建一套工程化支撑体系，使程序员可以：

1. 稳定调用模型
2. 自动加载项目记忆
3. 执行结构化任务
4. 复用通用技能
5. 对结果进行验证与沉淀

通常包含五个层面：

1. 模型接入层 — provider、模型、认证、协议兼容
2. 上下文记忆层 — AGENTS.md、项目记忆、专题文档、规则
3. 技能与代理层 — skills、agents、commands、权限
4. 执行控制层 — 任务拆分、流程控制、只读分析、修改实施
5. 工程闭环层 — 构建、测试、回归、知识更新

---

目标架构

┌─────────────────────────────────────────────────┐
│ 工程闭环层                                        │
│ 构建 / 测试 / 回归 / 知识更新                    │
├─────────────────────────────────────────────────┤
│ 执行控制层                                        │
│ 任务拆分 / plan/build/explore / 验证             │
├─────────────────────────────────────────────────┤
│ 技能与代理层                                      │
│ skills / agents / commands / permissions         │
├─────────────────────────────────────────────────┤
│ 上下文记忆层                                      │
│ AGENTS.md / topics / 规则                        │
├─────────────────────────────────────────────────┤
│ 模型接入层                                        │
│ provider / model / auth / baseURL                │
└─────────────────────────────────────────────────┘

---

下图展示了 Harness Engineering 五层架构的协作流程：

flowchart TD
    A["模型接入层<br/>provider / model / auth"] --> B["上下文记忆层<br/>AGENTS.md / topics / 规则"]
    B --> C["技能与代理层<br/>skills / agents / commands"]
    C --> D["执行控制层<br/>plan / build / explore / 验证"]
    D --> E["工程闭环层<br/>构建 / 测试 / 回归 / 知识更新"]
    E --> F["✅ 任务完成"]

分阶段执行计划

阶段一：基础环境建立

目标：让 AI 工具在本地稳定启动，连接至少一个可用模型。

工作内容：

1. 确认工具安装方式与版本
2. 配置 provider 与模型
3. 配置认证方式
4. 进行最小测试调用

产出物：

1. 可工作的配置文件（如 opencode.jsonc、claude_desktop_config.json 等）
2. 至少一个可用 provider
3. 至少一个可用模型
4. 一条最小验证流程：启动 → 选模型 → 对话成功

验收标准：

1. 能正常启动
2. 模型列表可正常获取
3. 对话不报协议错误

---

阶段二：全局工作流规范

目标：形成一套通用的执行规范。

建议规则：

1. 大于 3 步的任务先进入 plan
2. 多文件联动的改动先做结构定位
3. 涉及公共模块改动时必须附带验证步骤
4. 涉及新能力沉淀时必须同步补 skill 或 topic

产出物：

1. 一份执行检查清单

---

阶段三：项目记忆体系

目标：让 AI 工具能快速理解项目，而不是依赖临时提示。

建议专题目录：

1. 架构说明
2. 路由与模块
3. 数据流
4. 服务层职责
5. 模型定义
6. 构建部署
7. i18n 规则
8. 常见暗坑

产出物：

1. AGENTS.md
2. topics/*.md
3. 记忆更新约定

---

阶段四：技能体系

目标：把高频任务抽象成 skill。

建议首批 skill：

1. 路由定位
2. i18n 定位
3. API / 数据流排查
4. 条件判断模式

skill 设计要求：

1. 目录名与 name 严格一致
2. 命名使用小写加连字符
3. 描述清楚“何时使用”
4. 内容包含关键文件与步骤

产出物：

1. .agents/skills/*/SKILL.md
2. skills-index.md

---

阶段五：Agent 分层

建议角色：

1. plan — 方案设计、代码审查
2. build — 实现、修改、验证
3. explore — 快速检索、只读分析
4. 自定义 agent — 特定任务专用

工作内容：

1. 明确职责边界
2. 配置权限
3. 配置模型偏好
4. 形成调用约定

---

阶段六：命令模板

建议首批 commands：

1. /review-change — 代码审查
2. /trace-feature — 功能链路定位
3. /find-i18n — 中文字段查找

---

阶段七：验证与回归

建议验证项：

1. 编译是否通过
2. 关键页面是否可打开
3. 路由是否可达
4. 翻译 key 是否存在
5. 数据流是否接通
6. 日志是否有新增错误

---

最小落地版本

如果希望最快建立一套可用的体系：

1. 一个稳定 provider
2. 一个稳定模型
3. 一份 AGENTS.md
4. 三个高频 skill
5. 两个常用 command
6. 一份验证清单

---

成功标准

当满足以下条件时，视为体系已建立：

1. AI 工具能稳定使用
2. 新项目能快速建立上下文
3. 高频任务可自动复用 skill
4. 分析与实现职责清晰
5. 每次任务有验证闭环
6. 团队成员可以共享和维护