Harness Engineering 01｜从 Prompt Engineering 到 Harness Engineering
activity-dev-harness 项目的 Prompt 调优阶段，团队在 system prompt 上反复打磨了三周：角色定义、输出约束、few-shot 示例、CoT 引导。每改一版，跑几个 case 看起来都有进步。
第三周末拉全量 35 个 case 回归，通过率 45%，波动范围 30%-65%。也就是说，同一份 Prompt，今天跑 65% 明天跑 30%。
后来真正让通过率稳定到 78%（波动 72%-85%）的，不是某一版"更好的 Prompt"。而是一系列跟 Prompt 文案完全无关的改动：固定上下文拼装顺序、限定工具集从 12 砍到 5、给 Reviewer 加独立评测脚本、每轮 findings 累积管理。
这让我意识到一件事：当 AI 从"回答问题"变成"执行任务"，优化对象就从"表达"变成了"系统"。这个系统层面的工程方法，就是 Harness Engineering。
三层演进：Prompt → Context → Harness
┌─────────────────────────────────────────────────────────────────────────┐
│ AI 工程方法的三层演进 │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ Layer 1: Prompt Engineering │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ 关注点：怎么跟模型说话 │ │
│ │ 手段：角色设定、输出约束、CoT、few-shot │ │
│ │ 天花板：表达再精确，也管不住执行过程 │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │ 发现"光说不够，还得管模型看到什么" │
│ ▼ │
│ Layer 2: Context Engineering │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ 关注点：模型看到什么 │ │
│ │ 手段：RAG 检索、上下文拼装、记忆管理、token 预算分配 │ │
│ │ 天花板：输入控好了，执行链路、权限、验证依然没人管 │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │ 发现"看到的对了，但做的过程不可控" │
│ ▼ │
│ Layer 3: Harness Engineering │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ 关注点：这套系统怎么跑、怎么控、怎么测 │ │
│ │ 手段：环境设计、权限分层、工具约束、评测回归、轨迹追溯、 │ │
│ │ 人工接管、版本治理 │ │
│ │ 目标：把不确定的模型能力放进可控制、可验证的执行系统 │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
│ 越往下走，优化对象越不像"调模型"，越像"做系统工程" │
└─────────────────────────────────────────────────────────────────────────┘三层不是替代关系，是包含关系。Harness 层依然需要好的 Prompt 和好的 Context，但它补上了前两层完全覆盖不了的东西：执行过程的可控性和结果的可验证性。
Agent 不是模型，是被 Harness 的系统
很多团队默认"Agent = 更强的模型"，然后习惯性地把所有问题归因到模型能力。activity-dev-harness 的数据打破了这个假设：
线上问题归因统计（累计 4 个项目，67 次故障）：
归因类别 占比 典型案例
────────────── ────── ──────────────────────────────────
上下文构造问题 28% 拼装顺序错误导致空壳代码
知识供应链问题 22% 旧版规则未退场，新版未入索引
工具/环境问题 19% pytest 超时无重试，dry-run 脚本路径硬编码
评测/反馈缺失 15% 改了 Prompt 但没跑回归，退化三天后才发现
版本治理问题 9% 模型+Prompt+规则同时变更，无法归因
模型能力本身 7% 真正需要更强模型才能解决的
──────────────────────────────────────────────────────────────────93% 的问题出在模型周围的系统层。 这意味着：把 Agent 当模型调，90% 的时间花在错误的地方。
Agent 的正确理解方式：模型是决策核心，但决策核心外面必须有一整套执行系统------环境告诉它能做什么，约束限制它不能做什么，反馈让它知道做得对不对。这套系统就是 Harness。
最小闭环：意图、环境、反馈
所有 Harness 工程实践，最终都可以映射到三个元素：
┌─────────────────────────────┐
│ 意 图 Intent │
│ 任务目标 / 成功标准 / │
│ 失败条件 / 输出边界 │
└──────────────┬──────────────┘
│ 定义
▼
┌──────────────────────────────┐
│ Agent 决策与执行 │
└───────┬──────────────┬───────┘
│ │
提供资源+约束 产生信号
│ │
┌─────────────┴──┐ ┌──────┴──────────────┐
│ 环境 │ │ 反馈 │
│ Environment │ │ Feedback │
│ │ │ │
│ 仓库结构 │ │ 工具返回状态 │
│ 工具集+权限 │ │ 测试 PASS/FAIL │
│ 检索知识源 │ │ 评测分数变化 │
│ 可编辑范围 │ │ 轨迹记录 │
│ 运行状态 │ │ 人工审核结论 │
└────────────────┘ └─────────────────────┘
│ │
└──────┬───────┘
│ 纠偏
▼
闭环：做完能验证、
验证能纠偏、纠偏能积累这三个元素不是并列概念，是闭环关系。缺任何一个，系统都会退化成不同的失败模式：
缺失的元素 系统退化模式 真实表现
────────── ──────────────────── ──────────────────────────
缺意图 目标漂移 Agent 越做越偏，输出看似合理
但离验收标准越来越远
缺环境 能力幻觉 模型"会"但做不到------找不到文件、
调不对工具、改了不该改的目录
缺反馈 黑箱运行 看起来在跑，但没人知道对不对，
退化三天后偶然发现错误示范 vs 正确示范：同一个 Bug 修复任务
❌ 只有 Prompt，没有 Harness
任务："修复 calculateDamage 函数的暴击伤害计算错误"
Prompt 里写了：
- 请先分析问题再修改
- 尽量少改文件
- 改完运行测试
实际发生了什么：
1. Agent 改了 calculateDamage ✓
2. 顺手重构了 calculateDefense（没人要求）
3. 测试？没找到测试入口，直接说"已修复"
4. 引入了一个新依赖（Prompt 没说不能引入）
结果：通过率在"能用"和"完全不能用"之间随机波动
✅ Prompt + Harness
同样的 Prompt，但加了 Harness：
意图层：
┌──────────────────────────────────────────────┐
│ 目标：修复 calculateDamage 暴击倍率 │
│ 成功标准：test_damage.py 全部 PASS │
│ 边界：只允许改 combat/ 目录 │
│ 约束：不允许新增依赖 │
└──────────────────────────────────────────────┘
环境层：
┌──────────────────────────────────────────────┐
│ 可编辑范围：combat/*.lua │
│ 工具集：file_read, file_write, pytest, grep │
│ 测试入口：pytest tests/test_damage.py │
└──────────────────────────────────────────────┘
反馈层：
┌──────────────────────────────────────────────┐
│ 自动验证：修改后强制跑 pytest │
│ diff 检查：变更文件不在 combat/ 内 → 自动拒绝 │
│ 回归：跑完后对比 gold case 通过率是否下降 │
└──────────────────────────────────────────────┘
结果：通过率 82%，波动范围 ±5%区别不是 Prompt 写得好不好，而是系统有没有兜底。
四个项目的 Harness 需求热力图
不同系统需要的 Harness 完全不同。理解这张图，才能避免"所有项目照搬同一套 Harness"：
Harness 维度 activity-dev AIReview 配置表风险 Crashsight
harness 评估
───────────── ─────────── ───────── ───────── ──────────
意图结构化 ████ ███ ██ ███
仓库可读性(Repo) ████ ██ █ ██
工具权限分层 ████ ███ ██ ███
评测回归(Eval) ████ ████ ████ ████
轨迹追溯(Trace) ████ ███ ██ ████
检索验证(RAG) ██ ████ ████ ████
安全与边界(Safety) ████ ███ ███ ███
人工接管(HITL) ███ ██ ████ ██
████ = 核心瓶颈 ███ = 重要 ██ = 有但不是主要矛盾 █ = 几乎不涉及activity-dev-harness 的核心挑战在多 Agent 编排和仓库可读性；AIReview 的核心挑战在检索精度；配置表的核心挑战在批处理成本和人工接管；Crashsight 的核心挑战在历史数据质量和轨迹追溯。
没有万能 Harness，只有匹配场景的 Harness 组合。
三元框架映射：后续每篇在补哪一环
意图 环境 反馈
──── ──── ────
02 Repo Harness ████
让仓库对 Agent 可读 (可读性/可导航)
03 Eval & Trace ████
验证和追溯 (可验证/可观测)
04 Tool & RAG ████
能力可靠性工程 (动作可靠/知识有效)
05 Safety & HITL ████ ████ ████
边界、接管与回滚 (风险边界) (权限约束) (治理反馈)
06 Harness Platform ████ ████ ████
平台化沉淀 (全局治理) (环境标准化) (反馈体系化)Safety & HITL 覆盖三元框架的全部维度，这也是为什么它在 Harness Engineering 中最独特------手记系列完全没有覆盖这块。
与手记系列的分工
AI 工程化手记（7 篇） Harness Engineering（6 篇）
───────────────────── ──────────────────────────────
基建视角 方法论视角
拆每一层是什么、怎么做 拆这些层怎么组成可控系统
手记 01: AI 工程全景 Harness 01: 三层演进 + 三元框架
手记 02: 推理服务 Harness 02: Repo Harness（独有）
手记 03: 评测与观测 Harness 03: Eval & Trace 的 Harness 组织方式
手记 04: RAG Harness 04: 工具+检索的可靠性工程
手记 05: 上下文工程 Harness 05: Safety & HITL（独有）
手记 06: Tool Use & Agent Harness 06: 平台化沉淀的 Harness 视角
手记 07: 版本治理
手记回答"每层长什么样" Harness 回答"这些层怎么围成闭环"Harness Engineering 的核心判断：Prompt Engineering 管表达，Context Engineering 管输入，Harness Engineering 管系统------环境、约束和反馈回路才是 AI 从"能用"到"可交付"的决定性因素。