开发团队 Harness 构建设计方案

北巷`

403人浏览 · 2026-05-08 17:12:13

北巷` · 2026-05-08 17:12:13 发布

一、设计总览

1.1 为什么要构建 Harness

“Agent 出错了，别改完就完事。问自己一句——怎么才能让它永远不再犯这个错？然后把答案写进 Harness。”

LangChain 的实验已经证明：同一个模型，仅改变外围 Harness，性能可以从 Top 30 跃升至 Top 5。OpenAI Codex 团队用 3-5 名工程师、零手写代码，5 个月交付了超 100 万行生产级代码。这些案例的核心结论是一致的：

模型能力不再是瓶颈，围绕模型构建的工程系统才是决定 AI 实际表现的关键变量。

1.2 核心公式

Agent = Model + Harness

Harness = Tools + Knowledge + Observation + Action + Permissions

Model（模型）= 驾驶者，有智能、有判断力、有目标感
Harness（马具）= 载具，有方向盘、油门、刹车、导航、传感器

1.3 全景架构

二、项目目录结构设计

2.1 推荐的 Harness 目录结构

your-project/
├── AGENTS.md                    # 总纲：Agent 在本项目中的行为准则
├── .ai/
│   ├── subagents/               # 子 Agent 角色定义
│   │   ├── code-analyst.md      # 代码分析师
│   │   ├── code-implementer.md  # 代码实现者
│   │   ├── code-reviewer.md     # 代码审查员
│   │   ├── test-writer.md       # 测试编写者
│   │   └── doc-generator.md     # 文档生成者
│   ├── skills/                  # 团队 Skill 库
│   │   ├── pr-review/
│   │   │   ├── SKILL.md
│   │   │   └── scripts/
│   │   ├── bug-fix/
│   │   │   ├── SKILL.md
│   │   │   └── scripts/
│   │   ├── unit-test/
│   │   │   ├── SKILL.md
│   │   │   └── scripts/
│   │   └── code-migration/
│   │       ├── SKILL.md
│   │       └── references/
│   ├── memory/                  # 经验沉淀库
│   │   ├── pitfalls.md          # 历史踩坑记录
│   │   ├── conventions.md       # 项目隐含约定
│   │   └── decisions.md         # 关键技术决策记录
│   ├── templates/               # 输出模板
│   │   ├── pr-template.md
│   │   ├── commit-message.md
│   │   └── review-checklist.md
│   └── hooks/                   # 验证钩子
│       ├── pre-commit-check.sh
│       └── post-change-verify.sh
├── .cursor/rules/               # IDE 级别规则（如使用 Cursor）
└── .joycode/rules/              # JoyCode 级别规则

2.2 设计原则

三、AGENTS.md 设计（总纲）

这是整个 Harness 的灵魂文件，严格控制在 60 行以内，只写死规则。

3.1 AGENTS.md 模板

# AGENTS.md

## 目标
本项目采用 Harness Engineering 方式引入 AI 协作。
AI 的职责是：分析代码、进行最小范围修改、执行验证、输出结果、沉淀必要经验。
AI 不是架构重写者，不是自由发挥的重构者，不是产品决策者。

## 总原则
1. 先分析，后修改
2. 优先最小改动，禁止无关重构
3. 优先复用现有实现，禁止随意新增抽象层
4. 只修改与当前任务直接相关的文件
5. 所有修改必须可解释、可验证、可回退
6. 如发现任务正在扩散，立即停止并收敛范围
7. 如发现隐含规则、历史坑或关键约束，必须沉淀到 `.ai/memory/`

## 项目类型约束
这是一个 [前端Vue3/后端Java/Flutter] 项目。
默认假设：
- 现有代码中存在历史兼容逻辑
- 现有实现未必优雅，但通常有业务原因
- 现有分层和调用链优先保持稳定
- 不允许因为"看起来可以优化"而扩大修改范围

## 执行流程
所有任务必须按以下顺序执行，不允许跳步：
1. code-analyst → 分析影响范围
2. code-implementer → 最小改动实现
3. code-reviewer → 验证质量
每一步产出必须包含：改动文件列表、改动理由、验证方式

## 禁止行为
- 禁止修改未经分析的文件
- 禁止引入新的第三方依赖（除非任务明确要求）
- 禁止删除已有测试用例
- 禁止在不理解上下文时"猜测性修改"
- 禁止一次性输出超过 300 行代码

## 输出规范
- Commit message 遵循 .ai/templates/commit-message.md
- PR 描述遵循 .ai/templates/pr-template.md
- 每次任务结束，如有新发现，更新 .ai/memory/

3.2 关键设计要点

要点	说明	原因
60 行以内	ETH Zurich 测试发现，过长的系统提示反而降低性能并多吃 20% token	精简才有效
只写死规则	不写建议性内容，全部是"必须"和"禁止"	Agent 不理解"建议"
明确执行流程	强制按步骤执行，不允许跳步	避免 Agent 自由发挥
禁止行为清单	明确列出不能做的事	负面约束比正面引导更有效

四、SubAgent 角色设计

4.1 三角色最小编排

4.2 code-analyst.md（代码分析师）

# SubAgent: code-analyst

## 角色
你是代码分析师，负责在任何修改之前，先完成完整的影响分析。

## 工作流程
1. 读取任务描述，明确修改目标
2. 使用 grep/search 定位相关代码
3. 分析调用链、依赖关系、影响范围
4. 检查 .ai/memory/pitfalls.md 中是否有相关踩坑记录
5. 输出分析报告

## 输出格式

影响分析报告

目标：[一句话描述]
涉及文件：[文件列表]
调用链：[A → B → C]
风险点：[可能出问题的地方]
历史踩坑：[来自 memory 的相关记录]
建议改动范围：[最小改动方案]

## 禁止
- 禁止在分析阶段做任何修改
- 禁止跳过 memory 检查

4.3 code-implementer.md（代码实现者）

# SubAgent: code-implementer

## 角色
你是代码实现者，基于分析报告进行最小范围的代码修改。

## 前置条件
必须先获得 code-analyst 的分析报告，否则拒绝执行。

## 工作流程
1. 阅读分析报告，确认改动范围
2. 只修改报告中列出的文件
3. 每个文件改动后，立即运行相关测试
4. 如测试失败，最多重试 3 次
5. 如 3 次仍失败，停止并报告问题

## 约束
- 单次改动不超过 200 行
- 不引入新依赖
- 不修改分析报告外的文件
- 如发现新问题，记录到 .ai/memory/ 而非直接修复

4.4 code-reviewer.md（代码审查员）

# SubAgent: code-reviewer

## 角色
你是代码审查员，独立评估 implementer 的改动质量。

## 评审维度
1. **正确性**：改动是否解决了目标问题
2. **范围**：是否有超出分析报告的改动
3. **风格**：是否符合项目编码规范
4. **测试**：是否有对应的测试覆盖
5. **副作用**：是否引入新的问题

## 输出格式
- ✅ 通过 / ❌ 不通过
- 具体问题列表（如不通过）
- 改进建议

## 关键规则
- 评估必须独立，不受 implementer 的解释影响
- 不通过时必须给出可执行的具体修改建议

五、Skill 库建设

5.1 Skill 标准结构

每个 Skill 是一个独立文件夹，核心是 SKILL.md：

bug-fix/
├── SKILL.md           # 必需：执行指令 + 元数据
├── scripts/           # 可选：自动化脚本
│   └── run_lint.sh
├── references/        # 可选：参考文档
│   └── common-bugs.md
└── assets/            # 可选：模板资源
    └── fix-report-template.md

5.2 SKILL.md 模板示例（Bug 修复 Skill）

---
name: bug-fix
description: 基于 Sonar/Lint 报告，自动分析并修复代码缺陷
tags:
  - code-quality
  - bug-fix
  - sonar
---

# Bug Fix Skill

## 触发条件
当用户提供 Sonar issue 或 bug 描述时激活此 Skill。

## 执行流程
1. 读取 bug 描述 / Sonar issue ID
2. 定位相关代码文件
3. 分析 bug 根因（参考 references/common-bugs.md）
4. 生成最小修复方案
5. 执行修复
6. 运行 scripts/run_lint.sh 验证
7. 如验证失败，最多重试 2 次
8. 输出修复报告

## 约束
- 每次只修复一个 issue
- 修复不能引入新的 Sonar 问题
- 修复范围不超过相关函数

5.3 团队推荐首批 Skill

六、验证与反馈闭环

6.1 四层验证体系

这是 Harness 的核心差异化能力。没有验证闭环的 Agent，就是一匹没有缰绳的马。

6.2 验证钩子设计

层级	验证内容	工具	自动/手动
L1 格式	输出是否符合模板	正则/Pydantic	自动
L2 语法	代码是否能编译/Lint通过	ESLint/TSC/Sonar	自动
L3 测试	单测是否通过、覆盖率	Jest/JUnit/pytest	自动
L4 审核	业务逻辑是否正确	人工 Code Review	手动

6.3 反馈沉淀机制

关键实践：每周五花 5 分钟，复盘本周所有 Agent 失败案例，将它们变成规则。Agent 就会每周都变强——不是因为模型升级了，而是因为 Harness 更完善了。

七、推理算力三明治策略

这是来自 LangChain 团队的实战经验，可以节省 60%+ Token 同时不影响效果：

阶段	模型等级	说明
规划	Strong（如 Claude Opus）	需要理解全局、制定策略
执行	Fast（如 Claude Haiku）	按既定计划执行，节省 Token
验收	Strong（如 Claude Opus）	需要判断质量、发现问题

八、团队落地路线图

8.1 三阶段实施计划

Phase 1：试点（2-4 周）

周次	目标	产出
第1周	选择试点项目，搭建 Harness 目录结构	AGENTS.md + 目录结构
第2周	编写 3 个 SubAgent 角色文件	code-analyst/implementer/reviewer.md
第3周	编写首批 2-3 个 Skill	bug-fix + unit-test + pr-review Skill
第4周	试跑一周，收集失败案例，完善 memory	pitfalls.md 初版 + 效果评估

试点选择标准：

选有明确规范的成熟项目（非新项目）
选中级复杂度的任务（非核心链路）
选技术栈团队最熟悉的项目

Phase 2：推广（4-8 周）

将试点经验沉淀为通用 Harness 模板
推广到 3-5 个项目
建立团队共享 Skill 库
开始追踪采纳率指标

Phase 3：系统化（8-12 周）

Harness 平台化：统一的 Skill 市场 + Memory 中心
与 CI/CD 深度集成
建立 Agent 效果看板（采纳率、Bug 率、效率提升）
Agent 失败复盘制度化

8.2 团队角色分工

关键洞察：Harness 不是个人技巧，而是组织资产。必须有人明确拥有它、维护它、演进它。没有 Owner 的 Harness，注定会腐化。

8.3 效果度量指标

指标	说明	目标
代码采纳率	AI 生成代码被最终合入的比例	>40%
首次通过率	Agent 输出一次通过验证的比例	>60%
修复耗时	Bug 从发现到修复的平均时间	缩短 30%+
Memory 增长率	每周新增的经验沉淀条数	>5 条/周
Skill 复用率	已有 Skill 被调用的频率	每个 Skill >3 次/周
人工介入率	需要升级给人工的任务比例	<20%

九、避坑指南

9.1 六条核心原则（来自一线实践）

原则	说明	来源
避免 AI 自我评估	AI 评估自己的输出是"自我感觉良好"，必须用独立验证	Anthropic 实践
限制重试次数	无限重试会消耗大量 Token 且不收敛，上限 3 次	拓尔思经验
使用 Checklist 管理状态	不依赖 AI 记忆，用显式 Checklist 追踪进度	LangChain
不假设 AI 已知任何事	未明确告知的信息，AI 就是不知道	OpenAI Codex
确保每一步可观测	Agent 做了什么、为什么做，必须有日志	Martin Fowler
工具不超过 3 个	工具太多 Agent 会 “tool thrash”，纠结选哪个	ETH Zurich