1 什么是Harness Engineering
针对agent的设计和构建约束机制、反馈回路、工作流控制和持续改进循环的系统工程实践。解决agent 1）无有效的实时评测，不稳定。2）输出一致性不强。3）不好长期维护的问题。
注：仅做自己的学习笔记用
2 harness的工程架构
2.1 架构介绍
Harness Engineering 并不是凭空出现的，它是Prompt Engineering和Context Engineering的自然延伸。三者构成嵌套关系。
harness engineering有四大支柱：
- 上下文工程
实践中分为三层记忆：
三层上下文体系：
|---------------|-------------------|------------------------------|-------|
| 层级 | 加载时机 | 内容示例 | 上下文占用 |
| Tier 1：会话常驻 | 每次会话自动加载 | AGENTS.md / CLAUDE.md，项目结构概览 | 最小 |
| Tier 2：按需加载 | 特定子 Agent 或技能被调用时 | 专业化 Agent 的上下文、领域知识 | 中等 |
| Tier 3：持久化知识库 | Agent 主动查询时 | 研究文档、规格说明、历史会话 | 按需 |
- agent专业化
将agent根据领域进行技能划分，子agent只要获取相关上下文即可，通用性agent由于上下文巨大反而不利于扩展，子agent化有利于扩展。
实践中的角色分工：
|----------|---------------|----------------------|
| Agent 角色 | 职责范围 | 工具权限 |
| 研究 Agent | 探索代码库、分析实现细节 | 只读（Read, Grep, Glob） |
| 规划 Agent | 将需求分解为结构化任务 | 只读，无写入权限 |
| 执行 Agent | 实现单个具体任务 | 限定范围的读写权限 |
| 审查 Agent | 审计完成的工作，标记问题 | 只读 + 标记权限 |
| 调试 Agent | 修复审查发现的问题 | 限定范围的修复权限 |
| 清理 Agent | 对抗熵积累，清理低质量代码 | 读写权限 |
- 持久化记忆
核心原则：进度持久化在文件系统上，而非上下文窗口中。每次新 Agent 会话从零开始，通过文件系统制品重建上下文。
* Linter 错误消息即修复指令：
传统 Linter 错误消息仅标记违规。OpenAI 的自定义 Linter 在错误消息中直接包含修复方法------Agent 在遇到违规时同时获得了"教学"。
- 结构化执行
核心原则：将思考与执行分离。研究和规划在受控阶段进行，执行基于验证过的计划，验证通过自动化反馈（测试、Linter、CI）和人类审查完成。
Harness 模板可能包含：
自定义 Linter 规则
结构测试
基础上下文和知识文档
额外的上下文提供者
预配置的 CI/CD 管道
2.2 最佳实践总结
2.2.1 立即可行的行动清单
创建并维护 AGENTS.md：不是一次性任务，而是每当 Agent 犯错时都更新的活文档。
在仓库中建立单一事实源：所有团队知识作为版本控制的制品存放在代码仓库中，不放在 Slack、Wiki 或 Google Docs。
构建自定义 Linter 并在错误消息中嵌入修复指令：工具在 Agent 工作时同时"教会"它。
为 Agent 提供端到端测试工具：浏览器自动化（如 Puppeteer MCP）显著提升验证质量。
实施增量执行策略：每次会话只处理一个功能，完成后提交 git 和进度更新。
分层管理上下文：避免将所有信息堆叠在单个文件中，使用 Tier 1/2/3 渐进式披露。
上下文利用率保持在 40% 以下：更多 token 不代表更好的结果。
建立定期"垃圾回收"机制：自动化 Agent 定期清理技术债、检查文档一致性。
2.2.2 Harness 成熟度评估模型
|-------------------|------------------------------|------------------|
| 阶段 | 特征 | 工程师角色 |
| Level 0：无 Harness | 直接给 Agent prompt，无结构化约束 | 手动写代码+偶尔使用 AI |
| Level 1：基础约束 | AGENTS.md + 基础 Linter + 手动测试 | 主要写代码，AI 辅助 |
| Level 2：反馈回路 | CI/CD 集成 + 自动化测试 + 进度追踪 | 规划+审查为主，部分 AI 编码 |
| Level 3：专业化 Agent | 多 Agent 角色分工 + 分层上下文 + 持久化记忆 | 环境设计+管理为主 |
| Level 4：自治循环 | 无人值守并行化 + 自动化熵管理 + 自修复 | 架构师+质量把关者 |
2.2.3 关键 Harness 组件检查清单
|----------------------------|----------------|-----|
| 组件 | 用途 | 优先级 |
| AGENTS.md / CLAUDE.md | 会话常驻上下文，动态反馈循环 | P0 |
| 自定义 Linter + 结构测试 | 机械化执行架构约束 | P0 |
| CI/CD 管道 | 自动化测试和验证反馈 | P0 |
| 进度文件 (progress.txt / JSON) | 跨会话的持久化记忆 | P1 |
| 功能列表文件 (feature_list.json) | 结构化完成标准 | P1 |
| 浏览器自动化 (Puppeteer MCP) | 端到端测试验证 | P1 |
| 可观测性集成 | Agent 可查询日志/指标 | P2 |
| 熵管理 Agent | 定期清理低质量代码 | P2 |
| 专业化子 Agent | 分工协作减少上下文污染 | P2 |
| MCP 工具集成 | 连接外部工具和数据 | P2 |