这是群里老姚发起的话题，我让 opus爆肝了一下午写出来的文章，看了一下质量很高，就没有再润色加工，不是什么权威论述，只是希望这篇综述似的最佳实践能给大家节约一些时间
摘要
Harness Engineering 指的是：coding agent = AI model(s) + harness。
这里的 harness 不是单一工具，而是围绕编码 Agent 构建的配置层与运行时环境，通常包括指令文件、工具/MCP、Skills、Sub-agents、Hooks、反压机制等。
它的目标不是“让模型更聪明”，而是通过工程化手段减少错误、提升可验证性、控制上下文消耗，并把正确行为变成默认行为。
HumanLayer 的表述是：Harness Engineering 描述的是利用这些配置点来定制和改进编码 Agent 输出质量和可靠性的实践。
Mitchell Hashimoto 的表述是：任何时候你发现 agent 犯了一个错误，你都应该花时间设计一个解决方案，使 agent 不会再犯同样的错误。
核心发现表
| # | 主题 | 核心发现 |
|---|---|---|
| 1 | Harness 定义 | coding agent = AI model(s) + harness，重点在配置层与运行时环境。 |
| 2 | 指令文件 | 命令优先、完成定义、任务组织、升级规则、短小精悍最有效。 |
| 3 | 信息披露 | 不要一次塞满上下文；把 AGENTS.md 做成目录，Skills 按需加载。 |
| 4 | Sub-agents | 最重要价值是上下文隔离，而不是简单角色分工。 |
| 5 | Hooks | 用于通知、审批、集成、验证；它们是确定性控制流。 |
| 6 | 反压机制 | 验证能力越强，Agent 越容易成功；成功输出必须尽量静默。 |
| 7 | 长期运行 Harness | Initializer + Coding Agent 的双阶段方案更适合长任务。 |
| 8 | 工作模式 | One-Shot、Plan、Spec-Driven、Multi-Agent 需要分级使用。 |
| 9 | 项目脚手架 | 高代码健康度与“Code SEO”会显著提升 Agent 效能。 |
| 10 | 执行流水线 | 任务设计与上下文汇编往往比模型本身更关键。 |
| 11 | 质量控制 | 需要三层审查、工具兼容性管理和 MCP 约束。 |
| 12 | 反模式 | 散文式规则、模糊指令、过多工具、无验证路径都很危险。 |
| 13 | 路线图 | 先基础、再核心、后成熟、最后优化，逐步收敛。 |
| 14 | 迁移原则 | 从“写更多代码”转向“构建更可靠的 Harness”。 |
来源索引
| # | 来源 | 标题 | 日期 | 评级 | URL |
|---|---|---|---|---|---|
| 1 | HumanLayer | Skill Issue: Harness Engineering for Coding Agents | 2026-03 | ⭐⭐⭐ | www.humanlayer.dev/blog/skill-… |
| 2 | Anthropic | Effective Harnesses for Long-Running Agents | 2025-11 | ⭐⭐⭐ | www.anthropic.com/engineering… |
| 3 | Blake Crosley | AGENTS.md Patterns: What Actually Changes Agent Behavior | 2026-02 | ⭐⭐⭐ | blakecrosley.com/blog/agents… |
| 4 | Vitthal Mirji | Build the harness, not the code | 2026-02 | ⭐⭐⭐ | vitthalmirji.com/2026/02/bui… |
| 5 | Jason Robert | Patterns for AI-Assisted Development | 2026-03 | ⭐⭐ | jasonrobert.dev/blog/2026-0… |
| 6 | OpenAI | Harness Engineering: Leveraging Codex | 2026-02 | ⭐⭐ | 无公开 URL |
| 7 | vibecoding.app | AGENTS.md Complete Guide | 2026-03 | ⭐⭐ | vibecoding.app/blog/agents… |
| 8 | builder.io | Improve your AI code output with AGENTS.md | 2025-09 | ⭐⭐ | www.builder.io/blog/agents… |
| 9 | ClaudeTab | CLAUDE.md vs AGENTS.md 完整指南 | 2026-03-26 | ⭐⭐⭐ | claudelab.net/en/articles… |
| 10 | Vibe Coding | AGENTS.md Guide | 2026-03-12 | ⭐⭐ | vibecoding.app/blog/agents… |
| 11 | Marmelab | Agent Experience: 40+ Best Practices | 2026-01-21 | ⭐⭐⭐ | marmelab.com/blog/2026/0… |
| 12 | CodeScene | Agentic AI Coding Best Practice Patterns | 2026-02-20 | ⭐⭐⭐ | codescene.com/blog/agenti… |
| 13 | Codegen | How to Build Agentic Coding Workflows | 2026-03-10 | ⭐⭐ | codegen.com/blog/how-to… |
| 14 | AI Hero | A Complete Guide to AGENTS.md | 2026-01-18 | ⭐⭐ | www.aihero.dev/a-complete-… |
第一章：核心概念 — 什么是 Harness Engineering
定义
核心定义是：coding agent = AI model(s) + harness。
Harness 是围绕 AI 编码 Agent 构建的配置层和运行时环境。它负责把模型能力、工具调用、流程约束、上下文结构和验证机制组织成一个可控系统。
为什么重要
Harness Engineering 的关注点不是单纯增加模型参数或更换模型，而是通过工程设计改变 Agent 的行为边界：
- 让正确动作更容易发生。
- 让错误更难重复发生。
- 让验证更便宜。
- 让上下文更聚焦。
关键引述
HumanLayer：Harness Engineering 描述的是利用这些配置点来定制和改进编码 Agent 输出质量和可靠性的实践。
Mitchell Hashimoto：任何时候你发现 agent 犯了一个错误，你都应该花时间设计一个解决方案，使 agent 不会再犯同样的错误。
结论
Harness Engineering 的本质是把经验教训产品化、系统化，并通过工具链固化成默认行为。
第二章：指令文件最佳实践（AGENTS.md / CLAUDE.md）
ETH Zurich 研究结论
研究给出的信号很直接：
- LLM 自动生成的 agentfile 反而降低性能，同时增加 20%+ 成本。
- 人类编写的 agentfile 仅改善约 4%。
- Agent 处理指令文件时多花 14-22% reasoning tokens，并引入更多步骤和工具调用。
- 代码库概述和目录列表完全无用；Agent 自己能探索仓库结构。
什么有效 ✅
1. 命令优先（Command-first）
每条指令都应落到可执行命令。
## Build and Test Commands
- Install: `pip install -r requirements.txt`
- Lint: `ruff check . --fix`
- Test: `pytest -v --tb=short`
- Full verify: `ruff check . && ruff format --check . && pytest -v`
2. 定义“完成”（Closure definitions）
任务完成必须可验证。
## Definition of Done
A task is complete when ALL of the following pass:
1. `ruff check .` exits 0
2. `pytest -v` exits 0 with no failures
3. `mypy app/ --strict` exits 0
3. 按任务组织（Task-organized）
让规则跟任务类型绑定，而不是把所有规则堆在一起。
## When Writing Code
- Run `ruff check .` after every file change
## When Reviewing Code
- Check for security issues: `bandit -r app/`
## When Releasing
- Run full suite: `pytest -v && ruff check . && mypy app/`
4. 升级规则（Escalation rules）
告诉 Agent 卡住时该怎么办。
## When Blocked
- If tests fail after 3 attempts: stop and report
- Never: delete files to resolve errors, force push, or skip tests
5. 保持简短
短文件更有效：
- 单个 section < 50 行。
- 整个文件 < 150 行。
- HumanLayer 的 CLAUDE.md 只有 60 行以下。
什么无效 ❌
- 散文段落：例如“我们重视整洁、经过良好测试的代码……”这类内容通常会被忽略。
- 模糊指令：例如“尽量小心”“在可能时”“优雅地处理”。
- 矛盾的优先级：没有显式排序的多个约束会让 Agent 无法决策。
- 无法验证的风格指南：没有 lint 命令支撑的风格要求很难落实。
编写优先级
- 构建和测试命令。
- “完成”定义。
- 升级规则。
- 按任务组织的 sections。
- 目录作用域（仅 monorepo）。
AGENTS.md vs CLAUDE.md 对比表
| 维度 | AGENTS.md | CLAUDE.md |
|---|---|---|
| 目标 | 面向多工具/多 Agent 的通用指令入口 | Claude Code 的独立指令格式 |
| 作用方式 | 原生支持，适合跨工具协作 | Claude Code 原生格式，独立于 AGENTS.md |
| 推荐形态 | 作为目录与索引，连接更细的文档 | 保持简短，强调可执行规则 |
| 典型内容 | 构建、测试、完成定义、升级规则 | 工作流规则、约束、验证命令 |
| 最佳实践 | 按作用域拆分，monorepo 可多文件 | 文件更短、更聚焦，避免堆积说明 |
第三章：渐进式信息披露
核心原则
不要把所有知识一次性塞进上下文窗口。
AGENTS.md 作为目录而非百科全书
OpenAI 仓库使用 88 个独立的 AGENTS.md 文件：通常是 monorepo 中每个服务/包一个文件。
Root AGENTS.md 约 100 行，只做索引，详细内容放在 docs/ 子目录。
Skills 机制
Skills 也体现渐进式披露：
- 只有当 Agent 决定需要时才加载。
- 每个 Skill 有自己的目录，可捆绑多个 markdown 文件。
- 主 SKILL.md 负责告诉 Agent 目录里有什么，以及何时读取。
结论
最优做法不是“给更多”，而是“给得更晚、更准、更少”。
第四章：Sub-agents — 上下文防火墙
核心洞察
Sub-agents 的价值主要不是角色分工，而是上下文隔离。
HumanLayer 观察到：“前端工程师”sub-agent 和“后端工程师”sub-agent 这种角色化切法不起作用。
有效用途 ✅
- 定位代码库中的特定定义或实现。
- 分析代码库以识别特定工作的模式。
- 追踪信息在服务边界间的流动。
- 通用代码、文档、Web 研究任务。
无效用途 ❌
- 仅按职位名称切分，期待自动协作。
- 把子 Agent 当作“更小的主 Agent”来复制完整上下文。
- 在父线程中保留过多中间搜索与推理过程。
上下文防火墙
上下文防火墙的关键是：
- 父 Agent 只看到 sub-agent 的 prompt 和最终结果。
- 中间工具调用、搜索结果不会污染父线程。
- 主线程留在“智能区域”(Smart Zone)。
- 返回结果应极度精炼，同时附带
filepath:line引用。
成本控制
- 父线程使用昂贵模型负责规划与编排。
- Sub-agents 使用更便宜模型处理具体任务。
结论
Sub-agents 不是为了“拆人设”，而是为了“拆上下文”。
第五章：Hooks — 确定性控制流
核心原则
CLAUDE.md 的规则是建议，Hook 是强制执行。
四种用途
- 通知：任务完成时播放声音或发送 Slack 消息。
- 审批：自动批准或拒绝工具调用，例如阻止运行 migration。
- 集成：创建 GitHub PR、设置预览环境。
- 验证：每次 Agent 停止时运行 typecheck + lint，有错误则强制继续修复。
静默成功 / 显性失败
最关键模式是：
- 成功时 hook 完全静默，不消耗上下文。
- 失败时只输出错误信息。
- exit code 2 告诉 harness 重新启动 Agent 修复问题。
结论
Hooks 把原本“可建议”的行为变成“可执行、可阻断、可重试”的控制流。
第六章：反压机制
核心判断
Agent 成功解决问题的可能性，与其验证自身工作的能力强相关。
验证机制类型
- Typecheck + build。
- 单元测试 / 集成测试。
- 代码覆盖率报告。
- UI 交互测试（Playwright, agent-browser）。
输出精简的教训
早期运行完整测试套件会产生 4000 行通过结果，淹没上下文，导致 Agent 丢失任务。
因此现在的做法是：
- 吞掉成功输出，只显示错误。
- 构建成功时静默，失败时详细输出。
结论
反压机制的目标是让验证信息足够、但不淹没主任务。
第七章：长期运行 Agent 的 Harness（Anthropic 官方）
两部分解决方案
1. Initializer Agent
首次运行时设置环境，包括：
- 创建
init.sh脚本。 - 创建
claude-progress.txt进度日志。 - 创建初始 git commit。
- 生成全面的功能需求列表（JSON 格式）。
2. Coding Agent
每次后续运行做增量进度，包括：
- 读取 git log 和 progress file 了解当前状态。
- 一次只做一个功能。
- 用 git commit 记录进度。
- 用浏览器自动化工具做端到端测试。
- 离开时确保代码处于“干净状态”。
关键模式
- 功能列表用 JSON 而不是 Markdown，减少 Agent 不当修改。
- 每次会话开始：
pwd→ 读 git log → 读 progress → 读 feature list → 选择下一个任务。 - 增量工作，每次只做一个功能。
结论
长期运行场景下，Harness 需要把“初始化”和“持续推进”分开。
第八章：工作模式分级
4 模式表
| 模式 | 时间 | 适用场景 |
|---|---|---|
| One-Shot | ~1 min | 明确的小改动 |
| Plan Mode | ~2-3 min | 多文件变更，先看方案 |
| Spec-Driven | ~5-10 min | 中大型任务，团队需可审查的计划 |
| Multi-Agent | ~10-30 min | 大型功能，复杂代码库，质量门控 |
Spec-Driven 细节
- 生成代码前先生成 markdown 规格文件。
- 规格文件签入仓库并 code review。
- 结构化规格帮助模型和人类同样多。
Multi-Agent 评审循环
- Architect Agent → Content Reviewer（打分 0-100） → 低于 90 则返回修改 → Readability Reviewer。
- 评审循环通常 2-3 次，复杂情况可达 5-6 次。
结论
工作模式不是单一选择，而是按任务复杂度分层。
第九章：Agent 友好的项目脚手架
代码健康度研究
CodeScene 的研究显示：
- Agent 在代码健康度 ≥ 9.5/10 的代码上表现非线性提升。
- 健康度 7.0 时，准确度约 60%，且 token 消耗较高。
- 健康度 9.5+ 时，准确度约 95%，效率更高。
结论是：先改善代码质量，再引入 Agent。
Code SEO
Marmelab 给出的“代码 SEO”原则是让 Agent 更容易搜索：
- 使用同义词注释：客户 = 用户 = 账户。
- 避免重复文件名：多个
index.ts会混淆 Agent。 - 完整词优于缩写：
userProfile优于usr_prof。 - 文件和类添加标签注释。
// [feature:user-management] [domain:account] [pattern:service-layer]
// Related: src/repos/UserRepository.ts, src/tests/user.test.ts
8 大 Agent 友好模式
- 域知识嵌入代码：AGENTS.md + 代码注释 + 文件夹级 README。
- 代码 SEO：同义词、一致命名、标签。
- 简洁性：函数 < 100 行，文件 < 300 行。
- 偶然发现：交叉引用、标签、内嵌文档。
- 可测试性：TDD、覆盖率 ≥ 80%、mock 隔离。
- 遵循约定：成熟框架、设计模式、ADR。
- 防护栏：Hooks、MCP safeguards、CI 检查。
- 使用说明：工作示例、Context7 MCP、合理默认值。
结论
脚手架不是“让项目更漂亮”，而是让 Agent 更容易理解、定位与验证。
第十章：执行流水线与任务设计
Codegen 5 层架构
1️⃣ 任务输入（结构化的 Agent-Ready 任务）
↓
2️⃣ 上下文汇编（从 Linear/GitHub Issues 抽取）
→ 接受标准 + 关联文档 + 冲刺背景
↓
3️⃣ 沙箱执行（完全隔离）
→ Agent 读全代码库，生成提交和 PR
↓
4️⃣ PR 输出（自动化 + 人工审查）
→ AI 审查 FIRST → 人工审查
↓
5️⃣ 反馈循环
→ 审查问题追踪到原始任务 → 更新规范
Codegen 的判断是：80% 的 agentic 工作流失败发生在第 1-2 层，也就是任务设计和上下文，而不是 Agent 本身。
Agent-Ready 任务的 4 部分结构
- 清晰的成功定义，而不是只写“构建什么”。
- 显式的作用域：哪些文件、哪些禁区。
- Agent 无法从代码推断的约束。
- 相关背景：设计文档、示例实现、相关工单。
对比示例
| 差 ❌ | 好 ✅ |
|---|---|
| 给用户列表添加分页 | 在 /api/users 添加基于游标的分页。页大小：25。参考 /api/orders 模式。不要修改认证中间件。验证： GET /api/users?cursor=X 返回 25 个用户和 next_cursor。 |
结论
任务设计越结构化，Agent 越少走弯路。
第十一章：质量控制
代码审查三层防护
1️⃣ 实时审查（生成时）→ Code Health MCP
2️⃣ 提交前审查（本地）→ pre_commit_code_health_safeguard
3️⃣ PR 预检查（分支 vs 基线）→ analyze_change_set
跨工具兼容性矩阵
| 工具 | 原生文件 | 读取 AGENTS.md? |
|---|---|---|
| Codex CLI | AGENTS.md | 原生支持 |
| Cursor | .cursor/rules | 原生支持 |
| GitHub Copilot | .github/copilot-instructions.md | 原生支持 |
| Windsurf | .windsurfrules | 原生支持 |
| Claude Code | CLAUDE.md | 否（独立格式） |
| OpenCode | AGENTS.md | 原生支持 |
| Gemini CLI | GEMINI.md | 可配置 |
| Aider | CONVENTIONS.md | 需手动 flag |
MCP 工具注意事项
- 工具过多会填满上下文，加速进入“愚蠢区域”。
- 如果 CLI 已在训练数据中有良好覆盖，直接用 CLI 比 MCP 更好。
- 例如 GitHub、Docker、数据库：优先用 CLI + grep/jq，而不是 MCP。
- HumanLayer 的实践是：Linear MCP 替换为自定义 CLI + 6 个示例用法，从而节省数千 tokens 的工具定义。
结论
质量控制不是后置检查，而是贯穿生成、提交、PR 的三层护栏。
第十二章：反模式集合
AGENTS.md 反模式
1. 散文式描述
- 问题：可读但不可执行，Agent 容易忽略。
- 修复：改成命令、条件、退出标准。
2. 模糊词汇
- 问题：“尽量”“优雅地”“必要时”无法形成决策。
- 修复：改成明确命令与阈值。
3. 矛盾约束
- 问题：多个要求没有优先级时，Agent 无法判断。
- 修复：写出排序。
4. 无法验证的风格要求
- 问题：没有 lint/test 支持，规则落不了地。
- 修复：把风格要求绑定到检查命令。
5. 过长文件
- 问题：section 太长会增加阅读成本。
- 修复：保持短小，分文件、分作用域。
6. 把百科全书塞进单文件
- 问题：信息过载，降低有效 token 密度。
- 修复：AGENTS.md 只做索引，详细内容下沉到文档。
工作流反模式
1. 只按“角色”切 Sub-agent
- 问题：角色名不能解决上下文污染。
- 修复：按具体信息任务拆分。
2. Hook 里输出大量成功日志
- 问题：成功信息占满上下文。
- 修复：成功静默，失败才输出。
3. 测试通过输出淹没上下文
- 问题：4000 行成功输出会丢失主任务。
- 修复：吞掉成功输出，只保留错误。
结论
反模式的共同点是：它们都让 Agent 更难做出确定、可验证的动作。
第十三章：实施路线图
周 0：基础
- 用一句话描述项目目的。
- 列出非标准构建/typecheck 命令。
- 记录 3-5 个 Agent 最常犯的错误。
周 1：核心
- 添加“做”和“不做”（具体示例）。
- 添加文件级命令（typecheck、lint、test 单文件）。
- 定义“完成”（显式退出码）。
- 添加 1-2 个参考实现示例。
周 2-4：成熟
- 按任务类型组织（编码、审查、发布）。
- 添加升级路径。
- 设置代码健康度检查（MCP）。
- 可选：单体库嵌套 AGENTS.md。
第 1 个月：优化
- 测量 PR 质量。
- 反馈循环：差 PR → 更新任务规范。
- 裁剪 AGENTS.md（删除被忽视的规则）。
- 按作用域拆分为多文件。
结论
实施应当渐进推进：先让规则可执行，再让规则可维护，最后让规则可扩展。
附录 A：核心参考 URL
- www.humanlayer.dev/blog/skill-…
- www.anthropic.com/engineering…
- blakecrosley.com/blog/agents…
- vitthalmirji.com/2026/02/bui…
- jasonrobert.dev/blog/2026-0…
- 无公开 URL
- vibecoding.app/blog/agents…
- www.builder.io/blog/agents…
- claudelab.net/en/articles…
- vibecoding.app/blog/agents…
- marmelab.com/blog/2026/0…
- codescene.com/blog/agenti…
- codegen.com/blog/how-to…
- www.aihero.dev/a-complete-…
附录 B：术语表
Harness
围绕 AI 编码 Agent 的配置层与运行时环境，包括指令文件、工具/MCP、Skills、Sub-agents、Hooks、反压机制等。
AGENTS.md
用于给 Agent 提供可执行规则和目录索引的指令文件格式。
Progressive Disclosure
渐进式信息披露；把信息分层按需提供，而不是一次性灌入上下文。
Sub-agent
用于处理局部任务、并通过隔离上下文来控制污染的辅助 Agent。
Context Firewall
一种让父线程只接收精炼结果、隔离中间过程的上下文防火墙机制。
Hook
在特定事件上强制执行动作的确定性控制流机制。
Back-Pressure
通过验证与输出压缩来防止上下文被成功结果或噪声淹没的机制。
Smart Zone
父 Agent 保持专注与推理质量的上下文区域。
Spec-Driven Development
先写规格，再生成代码，并把规格纳入审查与版本控制的开发方式。
MCP
模型上下文协议相关工具接口；在本报告中强调工具数量、描述长度与上下文成本。
Agent-Ready Task
对 Agent 友好的任务描述，应包含成功定义、作用域、约束和背景。
Code Health
代码健康度；反映代码库结构、可读性和可维护性的指标。
Code SEO
让代码更容易被 Agent 搜索、理解与定位的一组命名、注释和结构策略。
One-Shot
适合一次性完成的小任务模式。
Plan Mode
先产出计划，再执行的中等复杂度模式。
Multi-Agent
多个专用 Agent 协同或串联完成复杂任务的模式。
Initializer Agent
长期运行场景中负责首次环境设置和初始化工件的 Agent。
Coding Agent
负责后续增量编码与推进的执行型 Agent。
Definition of Done
对“任务完成”的可验证定义，通常由命令退出码和测试结果构成。
