一、什么是 Harness Engineering
1.1 一句话定义
Harness Engineering（缰绳工程）是围绕 AI Agent 构建的"脚手架"工程------通过上下文传递、工具接口、验证循环、记忆系统和安全沙箱，让 Agent 从"能聊天"变成"能可靠地干活"。
1.2 直观类比
| 类比 | 说明 |
|---|---|
| 计算机体系结构 | LLM = CPU （算力），Context Window = RAM （工作记忆），Harness = OS （调度管理），Skill = App（具体功能） |
| 发动机 vs 变速箱 | 模型是发动机，Harness 是变速箱。500 马力的发动机没有变速箱一样跑不动 |
| 仓库 = Agent 的操作系统 | Agent 只能看到仓库里的东西。不在仓库里的约定，对 Agent 等于不存在 |
| Agent = 刚入职的博士 | 很聪明，但缺乏企业级经验。凡是没明说的部分，Agent 大概率"自行合理化" |
1.3 四层范式递进
Prompt Engineering → "我该怎么说，它才懂？" （点状：单次对话质量）
↓ 包含
Context Engineering → "它该知道什么，才能说对？" （面状：信息流完整性）
↓ 包含
Harness Engineering → "我该如何闭环，它才可靠？" （体状：业务链路健壮性）
↓ 包含
Environment Engineering→ "如何在真实世界中安全运行？" （域状：物理/数字世界桥梁）每一层包含前一层，而非替代。核心公式：Agent = Model + Harness------Harness 管的是"非确定性"。
1.4 为什么 Harness 比模型更重要
来自 17 篇高阅读量文章（总阅读 21 万+）的一致结论：
"同一个 Opus 模型，无 Harness 花 9 产出不可用代码，有完整 Harness 花 200 构建出可运行应用。" ------ learn-harness-engineering (8.1K stars)
"强的 Harness 框架比顶级模型更重要------使用 Kimi K2.5 配合精心设计的 Harness，成本仅为 Opus 的 1/20，效果相当。" ------ 麓行《Harness Engineering 长程自动化实践》(7,694 阅读)
"LangChain 仅修改 Agent 周围的脚手架代码（不换模型），TerminalBench 得分从 52.8% 飙升至 66.5%。" ------ 鹏赋（7,157 阅读）
核心公式：Agent 可靠性 = 模型智能 x Harness 质量
反直觉发现：强 Harness + 弱模型 > 弱 Harness + 强模型（成本差 20 倍，效果相当）
二、Harness 的 5 个核心要素
综合 10 篇 文章和 5 个 GitHub 项目，Harness 工程可提炼为 5 个核心要素：
┌─────────────────────────┐
│ 1. 上下文工程 │ ← Agent 能"看到"什么
│ (Context Engineering) │
└────────────┬────────────┘
│
┌────────────────┼────────────────┐
│ │ │
▼ ▼ ▼
┌────────┐ ┌────────────┐ ┌────────────┐
│2. 约束 │ │3. 验证循环 │ │4. 记忆系统 │
│编码化 │ │(Feedback │ │(Memory) │
│(Rules) │ │ Loop) │ │ │
└────────┘ └────────────┘ └────────────┘
│ │ │
└────────────────┼────────────────┘
│
┌────────────┴────────────┐
│ 5. 可观测与安全 │ ← 人能"看到"Agent在干什么
│ (Observability) │
└─────────────────────────┘要素 1：上下文工程 ------ 让 Agent 看到正确的信息
核心问题：Agent 的行为完全由它收到的上下文决定。上下文错了，行为一定错。
标准分层：
| 层级 | 内容 | 加载方式 | 示例 |
|---|---|---|---|
| L1 常驻层 | 身份、核心约束、禁止项 | 每次对话自动加载 | SOUL.md / CLAUDE.md |
| L2 规范层 | 行为规范、踩坑记录 | 每次对话自动加载 | AGENTS.md（<100行索引） |
| L3 按需层 | 领域知识、操作手册 | 匹配到任务时加载 | Skills / SKILL.md |
| L4 运行时层 | 环境信息、git 状态 | 动态注入 | 分支信息、构建命令 |
| L5 记忆层 | 历史经验、错误教训 | 语义检索 | MEMORY.md / experience.jsonl |
关键原则：
- 常驻信息要短（AGENTS.md < 100 行），做索引指路而非堆砌细节
- System Prompt 恒定，领域知识以 User Prompt 动态注入------避免认知冲突
- 上下文退化是真实存在的：长任务后期质量下降时，做上下文重置
要素 2：约束编码化 ------ 让规则自动执行
核心问题：写在文档里的规范 Agent 会忽略，编码进 Linter/Hook/CI 的约束才有执行力。
期望 → 写成文档 → 还是会被违反
期望 → 编码为 Linter/Hook/CI → 机械强制执行 ✓| 约束类型 | 实现方式 | 效果 |
|---|---|---|
| 架构边界 | lint-deps 脚本 | 高层 import 低层可以，反之报错 |
| 编码规范 | lint-quality 脚本 | 命名、复杂度自动检查 |
| 操作合法性 | verify_action 脚本 | 事前验证，2 次交互搞定 |
| 完整性 | validate 管道 | build → lint → test → verify |
关键原则：
- 事前预防 > 事后检查（事前 2 次交互 vs 事后 10 次 tool call 修复）
- linter 的报错信息就是教学------好的报错让 Agent 自愈
- 永远改代码而非禁用规则
要素 3：验证循环 ------ 让 Agent 知道做对没有
核心问题：没有反馈循环的 Agent 无法自我改进，就像没有方向盘的车。
标准验证管道：
代码完成 → 构建验证 → 静态分析 → 单元测试 → 集成测试 → 功能验证
│ │
│ ← 失败则自动修复（Ralph Loop，最多 3 轮） ← │闭环五模块（来自 HelixVerify 项目，114 次 AI 自主迭代验证）：
- 端到端测试：让 AI 能"看懂"系统
- 标准化评测：给 AI 统一的量化尺子（metric.txt + detail.txt）
- Badcase 自动诊断：数据驱动而非"直觉"
- TP 对抗验证：新规则不能误杀正确样本
- 阶梯式验证：小样本 3min → 中样本 → 全量 60min
实证效果 ：闭环前迭代 5-7 天/轮，闭环后 3-4 小时/轮------提升 30-40 倍。
要素 4：记忆系统 ------ 让 Agent 越用越好
核心问题：没有记忆的 Agent 每次从零开始，和 chatbot 没区别。
标准分层：
L1 身份层 SOUL.md（不可变）
L2 长期记忆 MEMORY.md（提炼精华，<3000 tokens）
L3 中期记忆 memory/YYYY-MM-DD.md（按日期）
L4 短期记忆 .learnings/（即时记录错误和收获）
L5 持久化 经验库 JSONL + 向量检索 + 知识图谱关键机制：
- 六步迭代循环：触发事件 → 即时记录 → 每日反思 → 验证 ≥3 次 promote 到长期记忆 → 下次加载 → 行为改进
- 混合检索：70% 向量相似度 + 30% 关键词权重
- Agent 可以更新记忆，但绝不能修改 SOUL.md
要素 5：可观测与安全 ------ 让人能看到和控制
核心问题：看不见 Agent 在做什么，就无法干预和改进。
| 维度 | 机制 |
|---|---|
| 事件追踪 | tool_start / tool_end / turn_end 全链路 |
| 权限控制 | Allow / Deny / Ask 三行为模型 |
| 沙箱隔离 | 操作系统级隔离（bubblewrap） |
| 错误自愈 | 14 种错误分类 + 预设恢复策略 |
| Hook 系统 | 20+ 种可编程拦截点 |
三、Harness 标准工程结构
综合文章 + GitHub 5 个实战模板（agentrules-architect 122 stars、ai-harness-template、claude-harness-template、Harness-for-claude、harness-engineering），提炼出标准工程结构：
project-root/
│
├── CLAUDE.md # 主上下文文件（必须，<200 行）
├── AGENTS.md # 跨工具规范（可 symlink → CLAUDE.md，只维护一份）
│
├── .claude/ # Agent 运行时配置
│ ├── settings.json # 权限(allow/deny) + hooks
│ ├── settings.local.json # 个人覆盖(git-ignored)
│ ├── rules/ # 作用域规则（用 globs: frontmatter 限定范围）
│ │ ├── code-quality.md # 代码质量规则
│ │ └── tdd.md # TDD 规则
│ ├── commands/ # 项目级斜杠命令
│ │ ├── bootstrap.md # /bootstrap 初始化
│ │ └── check.md # /check 质量检查
│ ├── hooks/ # 生命周期 hooks
│ │ ├── session-start-context # SessionStart: 注入仓库状态
│ │ └── stop-check # Stop: 结束前自动验证
│ ├── agents/ # 子 agent 角色定义（可选）
│ ├── skills/ # 技能包（按需加载）
│ │ └── skill-a/
│ │ ├── SKILL.md
│ │ ├── references/
│ │ ├── scripts/
│ │ └── templates/
│ └── memory/ # 记忆文件
│ ├── MEMORY.md
│ └── *.md
│
├── scripts/ # 标准化入口脚本
│ ├── bootstrap # 环境初始化 / 依赖安装
│ ├── check # 全量检查（lint + typecheck + test）
│ ├── test # 运行测试
│ └── verify.sh # 强制验证门（AI 结束前必须通过）
│
├── gates/ # 质量门脚本（大型项目用）
│ ├── check-secrets.sh # 密钥泄露检测
│ ├── check-boundaries.sh # 架构边界检查
│ ├── check-complexity.sh # 复杂度检查
│ └── check-security.sh # 安全扫描
│
├── docs/ # 详细文档（按需加载）
│ ├── ARCHITECTURE.md
│ ├── decisions.md # 架构决策日志
│ └── workflow.md
│
└── .learnings/ # 即时学习记录
├── ERRORS.md
└── LEARNINGS.md3.1 "三脚架"强制执行模式
来自 GitHub 5 个项目的一致实践------三层机械防护确保 AI 无法跳过检查：
scripts/check（或 verify.sh） ← 主动验证
+
pre-commit hooks ← 提交时拦截（密钥扫描、文件大小、自动文档生成）
+
Stop hook ← AI 结束前强制运行验证（退不出去除非通过）3.2 settings.json 标准模板
json
{
"permissions": {
"allow": [
"Bash(scripts/bootstrap)", "Bash(scripts/check)", "Bash(scripts/test)",
"Bash(git status)", "Bash(git diff:*)", "Bash(git log:*)", "Bash(rg:*)"
],
"deny": [
"Read(.env)", "Read(.env.*)", "Read(**/.env)", "Read(**/secrets/**)",
"Bash(*$(*)*)", "Bash(*`*`*)",
"Bash(git push --force*)", "Bash(rm -rf /)", "Bash(rm -rf ~)"
]
},
"hooks": {
"SessionStart": [{"hooks": [{"type": "command",
"command": "$CLAUDE_PROJECT_DIR/.claude/hooks/session-start-context"}]}],
"Stop": [{"hooks": [{"type": "command",
"command": "$CLAUDE_PROJECT_DIR/.claude/hooks/stop-check"}]}]
}
}关键设计 ：deny 列表比 allow 列表更重要------必须阻止命令注入（$() 和反引号）、密钥读取、强制推送。
3.3 SessionStart hook 要克制
最佳实践（来自 Harness-for-claude）：只在有未提交改动或不在 main 分支时才注入上下文，避免浪费 token。
3.4 AGENTS.md / CLAUDE.md 标准写法
markdown
# CLAUDE.md --- [项目名]
## 概览
[项目名] 是 [一句话描述]。技术栈: [语言/框架/数据库]
## 必要命令
- 构建: `mvn compile` / `npm run build`
- 测试: `mvn test` / `npm test`
- 验证（每次改动后必须运行）: `bash scripts/check`
## 架构
L0 数据层 → L1 核心逻辑 → L2 集成 → L3 接口 → L4 测试
高层可 import 低层，反之不行。详细说明: docs/ARCHITECTURE.md
## 强制规则
- 每 3-5 个编码任务执行一次增量编译
- 外部依赖不存在的方法禁止直接调用
- 不允许硬编码密钥
- 测试优先：先写测试，再实现
## 已知陷阱（最重要的部分）
- [P001] Spring Bean 未注册导致 NPE → 新建 Service 必须检查配置注册
- [P002] 接口变更未同步 DTO → 先改 DTO 再改接口
## 审查清单
- [ ] 没有超过 300 行的文件
- [ ] 测试通过
- [ ] 陷阱章节已更新（如发现新的非显性行为）写法原则 ：如果 AI 不知道这条信息会写出错误 代码 → 放进来；如果只是写出不够好的代码 → 放 docs/。
四、AI Coding 中的 Harness 最佳实践
4.1 标准 SOP（六阶段全流程）
每个阶段建议在独立会话中运行：
recon（侦察）→ explore（探索）→ proposal（提案）→ apply（实施）→ code-review → security-review| 阶段 | 做什么 | 关键产出 |
|---|---|---|
| recon | 存量代码侦察：架构考古、Git 热点、脆弱性评分 | 代码地图 + 五维脆弱性评分卡 |
| explore | 需求分析：强行把 Agent 从"收到就干"拽回来 | 分析报告 + 可行性评估 |
| proposal | 生成提案：Proposal → Specs → Design → Tasks | GIVEN/WHEN/THEN 可测场景 |
| apply | 按规范实施：TDD + 三门验证 + 合规矩阵 | 代码 + changes.json |
| code-review | 范围偏移检测 + 结构审查 + 测试覆盖 | 审查报告 + 置信度校准 |
| security-review | 注入/认证/数据/加密扫描 | 安全审计报告 |
4.2 三角色 Agent 分离
Planner（规划）→ Developer（执行）→ Evaluator（验证）
│ │ │
└── 各运行在上下文"甜区"（~40% 窗口占用）──┘关键：上下文超 40% 后模型表现开始下降（Context Rot），中间信息易被遗忘（Lost in the Middle 效应）。
4.3 四个反模式必须避免
| 反模式 | 表现 | 正确做法 |
|---|---|---|
| "软约束"陷阱 | Prompt 里写 5000 字 DO NOT | 编码为 Linter/Hook 机械执行 |
| "军火库"陷阱 | 给 Agent 塞 20 个 API 让它自己挑 | 按任务精准提供 3-5 个工具 |
| "盲打"陷阱 | 暴力死循环重试 | 分级退化 + 已试策略簿 |
| "官僚主义"陷阱 | 强制万字设计文档 | 渐进式披露，按需展开 |
4.4 AGENTS.md 写法（地图而非手册）
判断标准 ：如果 AI 不知道这条信息就会写出错误 的代码 → 放 AGENTS.md；如果只是写出不够好的代码 → 放详细文档。
约 200 行，只写两类内容：
- 理解项目全貌的必要信息（技术栈、仓库结构、核心模块）
- 违反会直接导致问题的硬性规则（命名约定、分层依赖、禁止项）
4.5 日常编码场景（单人 + 单 Agent）
| 实践 | 做法 |
|---|---|
| CLAUDE.md 四层分离 | 全局偏好 → 项目规范 → 个人私有 → 按文件类型规则 |
| Skills 按需加载 | 不放进 System Prompt，匹配任务时 User Prompt 注入 |
| 编译驱动开发 | 每改 3-5 个文件执行一次编译，失败立即修 |
| Git Worktree 隔离 | 并行任务使用独立工作树 |
| 反思 cron | 每日 23:00 自动整理 .learnings/ 到 MEMORY.md |
| 按需加载规则 | 不一次性加载所有规则，条件化生效减少上下文消耗 |
4.6 中型需求场景（多 Agent 协作）
| 实践 | 做法 |
|---|---|
| 协调者不写代码 | 协调者只管规划/委派/汇总，执行者做实际编码 |
| 标准化数据协议 | Agent 间通过 JSON 文件交接（如 changes.json） |
| 渐进式门控 | 硬门控（阻断）+ 软门控（警告）+ 自修复（Loop） |
| 独立会话运行 | 每个阶段在独立会话中执行，通过文件传递成果 |
| 交叉 Review | 用不同模型做 Review，避免同模型"视而不见" |
4.7 Rubric 评测体系
| 分级 | 含义 | 权重 |
|---|---|---|
| Essential | 必须满足 | 最高 |
| Important | 应当满足 | 中等 |
| Optional | 锦上添花 | 低 |
| Pitfall | 必须规避 | 扣分 |
四层质量模型：L1 功能正确性(40%) + L2 健壮性(25%) + L3 UI 呈现(20%) + L4 交互体验(15%)
4.8 选型原则（奥卡姆剃刀）
能用 Single Agent 解决的 → 不上 Multi-Agent
知识不够用的 → 先加 Skills，不加 Agent
单 Agent 成功率 > 45% 后 → 加 Agent 的收益边际递减4.9 组织级关键发现
- 编码快了但交付周期没降------瓶颈已从代码转移到流程（审批/环境占 50-80%）
- 文档与编码的精力分配比从 1:3 变为 3:1------设计文档变成最重要的投入
- AI 千行代码缺陷率、AI 代码生存率成为新的质量度量指标
五、团队现状对比分析
5.1 团队方案概述
团队构建了 AI Software Factory------一个基于 CrewAI 的 7 步自闭环流水线，包含需求评估 → 编码 → 验收 → 自修复 → 经验沉淀的完整链路，配备 7 个专业 Agent 角色。
5.2 逐要素对比
要素 1：上下文工程
| 对比项 | 行业最佳实践 | 团队现状 | 评价 |
|---|---|---|---|
| 规范文件 | AGENTS.md < 100 行做索引 | SKILL.md 定义 Agent 行为（各 Agent 独立） | 符合：每个 Agent 有独立 SKILL.md，职责清晰 |
| 分层加载 | 常驻短 + Skills 按需 + 运行时注入 | SKILL.md + references/ + knowledge/ 分层 | 符合：遵循 Anthropic Agent Skills 渐进式披露标准 |
| 上下文压缩 | 三层渐进式压缩 | 无明确压缩机制 | 待补充：长任务可能遇到上下文退化 |
| 项目级 CLAUDE.md | 四层分离（全局/项目/个人/文件类型） | 未使用 CLAUDE.md 体系 | 可优化：目标项目可增加 CLAUDE.md 沉淀通用规范 |
要素 2：约束编码化
| 对比项 | 行业最佳实践 | 团队现状 | 评价 |
|---|---|---|---|
| 架构边界检查 | lint-deps 脚本自动拦截 | code-executor 的"不可跳步约束"+ 编码拓扑排序 | 部分符合：有流程约束，但非 linter 机械执行 |
| 构建验证 | 每 3-5 个任务增量编译 | 编码每 3-5 个任务 mvn compile |
完全符合 |
| 门控系统 | 事前预防 + 分级门控 | 六维评估硬门控 + 领域软门控 + 短路门禁 | 超越：门控体系比行业实践更完整 |
| 操作预检 | verify_action.py 事前验证 | 无显式事前验证 | 可补充：可在编码前增加操作合法性预检 |
要素 3：验证循环
| 对比项 | 行业最佳实践 | 团队现状 | 评价 |
|---|---|---|---|
| 反馈闭环 | 验证失败 → 自动修复 → 重新验证 | Ralph Loop（最多 3 轮） | 完全符合 |
| 多维度验收 | 构建 → 静态分析 → 单测 → 集成 → 功能 | Inspector 9 维质检 + Verifier 5 层验证 | 超越：9 维 + 5 层比行业通用方案更全面 |
| 标准化评测 | metric.txt + detail.txt 双输出 | acceptance-report.json + .md 双格式 | 完全符合 |
| 阶梯式验证 | 小样本 → 中样本 → 全量 | 短路门禁（3+ blocking 跳过后续） | 变体实现：用短路代替阶梯，思路一致 |
要素 4：记忆系统
| 对比项 | 行业最佳实践 | 团队现状 | 评价 |
|---|---|---|---|
| 经验沉淀 | JSONL + 向量检索 + KM 同步 | ExperienceCollector + KM Sync | 完全符合 |
| 经验复用 | 混合检索注入上下文 | 本地关键词 + KM 语义检索混合 | 完全符合 |
| 分层记忆 | L1-L5 五层 | 本地 JSONL + 远程 KM 两层 | 可增强：缺少即时学习层（.learnings/）和每日反思机制 |
| 反思循环 | 每日反思 cron + promote 机制 | 无自动反思 | 待补充：可增加自动反思整合机制 |
要素 5：可观测与安全
| 对比项 | 行业最佳实践 | 团队现状 | 评价 |
|---|---|---|---|
| 事件追踪 | 全链路 tool_start/end | SSE Dashboard + events.jsonl | 完全符合 |
| 实时监控 | Agent 工作可见可追踪 | SSE 实时推送 + Agent 思考过程展示 | 超越：Dashboard 可视化超出行业一般水平 |
| 错误处理 | 14 种错误分类 + 自动恢复 | PipelineHaltedException + 降级策略 | 部分符合：有降级但错误分类不够细 |
| 沙箱隔离 | OS 级沙箱 + 权限引擎 | Git Worktree 隔离 | 部分符合：有工作区隔离，缺 OS 级沙箱 |
5.3 综合评分
| 要素 | 得分 | 说明 |
|---|---|---|
| 上下文工程 | 7/10 | Skills 分层好，缺 CLAUDE.md 体系和上下文压缩 |
| 约束编码化 | 8/10 | 门控体系优秀，可补充 linter 级机械约束 |
| 验证循环 | 9/10 | Ralph Loop + 9 维 + 5 层验证，行业领先 |
| 记忆系统 | 7/10 | 经验沉淀完整，缺即时学习和自动反思 |
| 可观测与安全 | 8/10 | Dashboard 优秀，可增强错误分类和沙箱 |
| 综合 | 8/10 | 整体处于行业前列，在验证循环和门控方面领先 |
5.4 改进建议（按优先级）
P0：快速见效（1 周内）
-
为目标项目增加 CLAUDE.md
- 在目标项目根目录创建 CLAUDE.md，沉淀构建命令、分支策略、架构约束
- 让日常 AI Coding（不走工厂流水线时）也能受益于规范约束
-
增加 .learnings/ 即时学习
- 在 Agent 执行过程中即时记录错误和收获
- 为后续反思机制做数据准备
P1：系统增强（1 个月内）
-
增加自动反思机制
- 每日 cron 整合 .learnings/ 到长期经验
- 验证 ≥ 3 次的 pattern 自动 promote
-
增加 lint 级架构约束
- 为目标项目编写 lint-deps 脚本，将"编码拓扑排序"从 SKILL.md 文字约束变为机械执行
- linter 报错信息设计为教学性质
P2：长期演进
-
上下文压缩机制
- 长任务中监控上下文使用比例，超 50% 时自动压缩
- 保留压缩优先级：架构决策 > 已修改文件 > 验证状态
-
Harness 自进化飞轮
- Agent 执行 → 验证抓问题 → Critic 分析模式 → Refiner 更新规则 → 下一个 Agent 受益
- 成功轨迹编译为确定性脚本
六、团队方案的独特优势
值得强调的是，团队方案在某些方面超越了行业通用实践：
| 优势 | 说明 |
|---|---|
| 全链路自动化 | 从 PRD → 代码 → 验收的端到端自动化，行业多数只做编码环节 |
| 六维需求评估 | 在编码之前评估 PRD 质量，有效避免"垃圾进垃圾出" |
| 编译驱动修复 | Ralph-fix-agent 先获取完整错误列表再批量修复，比"修一个编译一次"高效 |
| 多后端适配 | qodercli/opencode/cursor/claude 四后端统一抽象，不绑定单一工具 |
| Agent Skills 标准兼容 | SKILL.md 遵循 Anthropic 开放标准，可跨工具复用 |
| SSE Dashboard | 实时可视化 Agent 思考过程，超出行业一般可观测水平 |