一、Harness Engineering 的定义与核心命题
- Harness Engineering：为 AI 编程 Agent 设计一套可靠工作的工程环境，使其能在真实代码库中持续、可验证地交付。
- 核心命题：模型能力强 ≠ 执行可靠。同一模型在不同 Harness 下，产出质量可能天差地别。
- 优化重点不是“让模型更聪明”，而是“让环境更可靠”。
- Harness 不是提示词工程。提示词工程优化单次输入；上下文工程管理上下文；Harness Engineering 设计整个工作系统。
- Harness 的本质是一个闭环：指令 → 状态 → 执行 → 验证 → 更新状态 → 下一轮。
二、AI Agent 的典型失败模式
- 语法正确，但业务语义错误。
- 过早宣告完成，实际未通过测试。
- 跨会话遗忘目标、决策和进度。
- 范围蔓延：顺手重构、扩展需求、改无关文件。
- 破坏架构边界，引入循环依赖。
- 复制仓库中已有的坏模式。
- 上下文污染：把无关信息塞进上下文，挤占有效推理空间。
- 文档与代码脱节，文档腐烂。
- 依赖记忆而非仓库工件。
- 盲目信任模型自述，缺少外部验证信号。
三、Harness 五大子系统
| 子系统 | 作用 | 关键知识 |
|---|---|---|
| Instructions 指令 | 告诉 Agent 做什么、按什么顺序做、开始前读什么 | 渐进式披露；短入口，深层链接 |
| State 状态 | 记录做了什么、在做什么、下一步是什么 | 状态写磁盘；跨会话恢复 |
| Verification 验证 | 确立“只有测试通过才算完成” | 可执行验证流水线；外部信号 |
| Scope 范围 | 约束一次只做一个功能 | 功能列表；明确边界；禁止蔓延 |
| Session Lifecycle 会话生命周期 | 定义开始初始化与结束清理 | 开始恢复状态，结束保存状态 |
四、核心工件与文件
1. AGENTS.md
- 是 Agent 的仓库导航入口，不是百科全书。
- 理想长度约 100 行，作为“目录页”。
- 应包含：
- 项目一句话概述。
- 快速命令：安装、开发、测试、lint、构建。
- 关键目录地图。
- 核心约定与禁止事项。
- 当前目标或当前迭代方向。
- 指向深层文档的链接。
- 深层文档可包括：架构、约定、工作流、领域知识、决策记录、质量评分。
2. init.sh
- 负责会话开始时的环境初始化。
- 职责包括：检查依赖、安装依赖、校验环境、启动服务、输出下一步。
- 目标是让每次会话从干净、可复现的状态开始。
3. feature_list.json
- 功能列表与状态追踪。
- 状态机通常为：
pending、in_progress、blocked、done、verified。 - 每个功能应包含：ID、标题、状态、验收标准、备注。
- 只有
verified才算真正完成。
4. progress.md / claude-progress.md
- 每次会话的进度日志。
- 记录：当前目标、已完成、进行中、下一步、阻塞、关键决策、验证结果。
- 状态必须写到磁盘，不能留在聊天历史里。
五、指令系统知识
- 仓库即唯一真实来源：不在仓库里的东西，对 Agent 就不存在。
- 地图而非手册：
AGENTS.md是目录页，指向更详细文档。 - 渐进式披露：只加载当前任务需要的上下文。
- 避免巨型指令文件，避免一次性塞满上下文窗口。
- 指令应明确：目标、顺序、边界、完成标准、禁止事项。
- 文档应靠近代码，并随代码更新。
- 文档会腐烂，但 lint 规则和结构测试不会。
六、状态系统知识
- 状态必须外置、版本化、结构化。
- 状态文件是跨会话连续性的唯一保障。
- 会话开始：读取
AGENTS.md、progress.md、feature_list.json，运行init.sh。 - 会话结束：更新进度、更新功能状态、提交或发起 PR、清理环境。
- 状态记录应包含决策原因，避免下次会话重复推理。
- 状态应能回答三个问题：做了什么、在做什么、下一步做什么。
七、验证系统知识
- 完成定义 = 验证通过。Agent 不能自证完成。
- 验证必须是可执行的流水线，例如：
- 格式检查 / lint
- 类型检查
- 单元测试
- 集成测试
- 端到端测试
- 构建
- 运行时冒烟测试
- 安全与依赖扫描
- 验证前置：任务开始前定义验收标准。
- 验证失败时，错误信息应可操作，最好内嵌修复指令。
- 反馈循环要短：失败 → 可读错误 → 修复 → 重跑。
- 不跳过失败测试，不把“偶发失败”当默认借口。
- 运行时反馈很重要：日志、截图、实际行为、边界条件。
八、范围控制知识
- 一次只做一个功能。
- 功能列表驱动工作，避免多任务并行。
- 明确任务边界，禁止顺手重构、扩展需求、改无关文件。
- 小步提交，小 PR，降低审查和回滚成本。
- 范围蔓延是 Agent 常见失败模式，需机械化约束。
- 任务拆分应到可独立验证的粒度。
九、会话生命周期知识
- 会话开始：
- 读入口文档。
- 读进度和功能列表。
- 运行初始化脚本。
- 确认当前目标与边界。
- 会话结束：
- 运行验证。
- 更新进度文件。
- 更新功能状态。
- 提交或发起 PR。
- 清理临时状态。
- 目标是给下次会话留下干净、可恢复的重启路径。
十、仓库与代码库工程知识
- 为 Agent 的可读性和推理能力优化代码库。
- 模块化、明确边界、依赖方向清晰。
- 小文件、小函数、明确命名、显式接口。
- 类型系统有助于约束 Agent 行为。
- 优先选择“无聊”的技术栈：API 稳定、训练数据丰富、行为可预测。
- 有时重新实现一个子集，比包装不透明上游行为更划算。
- 架构决策应记录为 ADR 或文档，并提交到仓库。
- 测试应快速、确定、可复现，错误信息可操作。
- 代码库中的坏模式会被 Agent 复制，因此需定期清理。
十一、上下文工程知识
- 上下文窗口有限，必须管理。
- 只加载相关文件，用指针而非全文。
- 用摘要、状态文件、进度日志减少上下文负担。
- 避免上下文污染：无关信息会降低推理质量。
- 任务开始前应有明确的阅读顺序。
- 深层知识放在文档中，按需加载。
- 地图式入口优于手册式全量说明。
十二、自动化与 Lint 知识
- 文档会腐烂，Lint 规则不会。
- 用自定义 linter 和结构测试守护架构边界。
- 可自动检查：
- 依赖方向
- 模块边界
- 导入规则
- 命名约定
- 文件位置
- 文档链接有效性
- 错误信息中直接内嵌修复指令，让 Agent 能自我纠正。
- 机械化规则比口头约定更可靠。
- 结构测试可作为架构的“免疫系统”。
十三、吞吐量、PR 与合并知识
- Agent 吞吐量可能远超人类注意力。
- 在安全网充足时：纠错成本低，等待成本高。
- PR 生命周期应短，小 PR 快速合并。
- 自动 CI 是关键安全网。
- 回滚应容易。
- 审查重点：架构、安全、业务语义，而非格式。
- 测试偶发失败可通过重跑解决，但必须区分真失败与假失败。
- 合并理念从“慢而稳”转向“快而可恢复”。
十四、熵管理与质量评分
- Agent 会复现仓库中已有模式，包括坏模式。
- 技术债是“高息贷款”，会加速熵增。
- 需要定期垃圾回收：
- 扫描偏差
- 更新质量评分
- 发起重构 PR
- 清理过时文档
- 修复架构违规
- 质量评分可度量：
- 测试覆盖率
- lint 违规数
- 复杂度
- 重复率
- 依赖新鲜度
- 文档腐烂程度
- 架构偏差
- PR 大小与合并时间
- 返工率
- 上下文丢失事件
- 熵管理不是一次性任务，而是持续过程。
十五、反模式
- 巨型提示词 / 巨型
AGENTS.md。 - 状态留在聊天历史中。
- 无验证或验证不可执行。
- 多任务并行，范围蔓延。
- 不提交状态和决策到仓库。
- 依赖记忆而非工件。
- 跳过测试，盲目信任 Agent 自述。
- 文档与代码脱节。
- 让 Agent 自由发挥架构。
- 包装不透明上游行为。
- 忽视坏模式传播。
- 把偶发失败当常态。
十六、核心原则清单
- 仓库即唯一真实来源。
- 地图而非手册。
- 文档会腐烂，Lint 规则不会。
- 为 Agent 的推理能力优化。
- 吞吐量改变合并理念。
- 熵管理就是垃圾回收。
- 验证定义完成。
- 状态必须外置。
- 一次只做一个功能。
- 会话有始有终。
- 错误信息应内嵌修复指令。
- 小 PR、快合并、易回滚。
- 坏模式会被复制，必须主动清理。
- 人类负责目标、边界、验收标准和 Harness 维护。
十七、最小知识框架
一个可工作的 Harness 至少包含四个工件：
| 文件 | 职责 |
|---|---|
AGENTS.md | Agent 的操作入口与仓库导航 |
init.sh | 环境初始化、依赖安装、启动与校验 |
feature_list.json | 功能列表、状态与验收标准 |
progress.md | 会话进度、决策、阻塞与下一步 |
更完整的资源包还包括：仓库骨架、质量文档、执行计划、架构文档、约定文档、工作流文档、ADR、结构测试和自定义 lint 规则。
一句话总结：Harness Engineering 把软件工程从“人写代码”扩展为“人设计环境，Agent 在环境中可靠交付”。
参考：https://walkinglabs.github.io/learn-harness-engineering/zh/