当前位置：首页 > news >正文

Harness Engineering 快速入门：让 AI Coding Agent 在你的项目里稳定工作

news 2026/6/24 21:55:33

Harness Engineering 快速入门：让 AI Coding Agent 在你的项目里稳定工作

截至 2026 年 4 月 5 日，公开资料里对 Harness Engineering 讲得最清楚的几条线，基本来自：

OpenAI，2026-02-11，Harness engineering: leveraging Codex in an agent-first world
Anthropic，2026-01-09，Demystifying evals for AI agents
Anthropic，2025-11-26，Effective harnesses for long-running agents
Martin Fowler，2026-04-02，Harness engineering for coding agent users

这些文章放在一起看，可以得到一个非常实用的结论：

决定 Agent 上限的，不只是模型，也不是 prompt，而是你给它搭了什么样的 harness。

Fowler 把它压缩成一句很好的公式：

Agent = Model + Harness

如果你想快速理解 Harness Engineering，并把它用到自己的项目里，这篇文章只讲三件事：

Harness Engineering 到底是什么
它的最小架构应该长什么样
你今天就能怎么落地

一、Harness Engineering 是什么

简单说：

Harness Engineering 就是为 Agent 设计工作环境。

这个工作环境不只是提示词，还包括：

它能读到什么上下文
它在哪个工作区执行
它怎么跑检查和测试
它失败后如何恢复
你怎么判断它是真的完成了任务

所以 Harness Engineering 不是“更高级的 Prompt Engineering”，而是把下面这些东西系统化：

仓库知识
执行脚本
检查规则
Git 工作流
状态恢复
评估方法

如果只给 Agent 一段很长的系统提示词，但没有检查、没有恢复、没有评估，那通常还不算 Harness。

二、为什么 2026 年大家都在讲 Harness Engineering

因为 Agent 已经不再只做 30 秒的小任务了。

现在更常见的场景是：

连续工作数小时
读完整个代码仓库
修改多个模块
调工具、跑测试、修错误
中途暂停后继续
最后还要做回归验证

到了这个阶段，单靠 prompt 会遇到 4 个明显问题：

上下文会漂
会话越长，Agent 越容易忘记真正的约束和目标。
执行环境不稳定
没有统一入口脚本、没有隔离工作区，Agent 很容易把仓库弄脏。
反馈信号太弱
如果没有 lint、test、结构检查、日志和 trace，Agent 往往不知道自己错在哪。
结果难以比较
没有 eval harness，你没法知道新的 Agent 设置到底比旧的好还是差。

所以 2026 年的主线已经很明确：

不要只优化模型输出，要优化模型工作的系统。

三、Harness Engineering 的最小架构

如果只保留最核心的部分，我建议把 Harness 理解成 5 层。

目标与规则↓
执行环境↓
反馈回路↓
恢复机制↓
评估系统

下面逐层讲。

1. 目标与规则层

这层回答两个问题：

Agent 应该遵守什么规则？
Agent 去哪里找这些规则？

最佳实践不是写一个超长的 AGENTS.md，而是：

用一个短的 AGENTS.md 做目录
把详细内容拆到 docs/、standards/、runbooks/ 里
把结构化信息写成配置或 JSON，而不是全放在自然语言里

这层的目标是让仓库成为 system of record。

最小建议：

AGENTS.md
docs/architecture.md
docs/dev-workflow.md
docs/testing.md
project-profile.json 或同类结构化文件

2. 执行环境层

这层回答：

Agent 在哪里工作？
它如何启动项目？
它拥有什么工具？

比较稳的做法是：

每个任务一个独立 worktree 或分支
有统一的初始化脚本，比如 scripts/init-agent.sh
有统一的检查入口，比如 scripts/check.sh
Agent 不直接依赖“人工口头说明怎么启动项目”

最小建议：

git worktree
scripts/init-agent.sh
scripts/dev.sh
scripts/check.sh

3. 反馈回路层

这层是 Harness 的核心。

它回答：

Agent 改完代码后，系统如何告诉它哪里错了？

这一层最好优先使用确定性信号，因为它们便宜、稳定、容易自动化：

lint
unit test
type check
build check
architecture rule check
file size / dependency boundary check

你可以把这层理解成 Fowler 说的 sensors。

没有这一层，Agent 只能“猜自己有没有做对”。

4. 恢复机制层

长任务一定会中断，所以你必须回答：

Agent 下次怎么继续？
什么信息会被保留下来？

Anthropic 在 long-running agent 的实践里很强调这一点。常见手段包括：

进度文件
checkpoint commit
task log
任务级 worktree
可重复执行的初始化脚本

最小建议：

tasks/<task-id>.md 记录当前目标、约束、下一步
每完成一个阶段就 checkpoint 一次
所有“恢复所需信息”都放在仓库里，而不是只放在聊天记录里

5. 评估系统层

这一层经常被忽略，但其实越来越重要。

它回答：

这个 harness 真的让 Agent 变好了吗？

Anthropic 在 evals 的文章里把关键点说得很直接：
你需要任务、trial、grader、outcome，而不是只凭感觉说“这次看起来不错”。

最小建议：

准备一组真实任务样本
同一个任务多跑几次
为每次运行保存 transcript 或结果摘要
用脚本或 grader 统一判分

如果没有 eval，你其实不知道自己是在优化，还是在自我安慰。

四、把 Harness Engineering 落到项目里，最少要做什么

如果你想今天就开始，不需要一次性做大系统。
最小可用版可以按下面 6 步搭起来。

第一步：写一个短 `AGENTS.md`

它只做 3 件事：

说明项目目标
告诉 Agent 先看哪些文件
告诉 Agent 哪些命令是标准入口

不要把所有规范都塞进去。
让它像目录，不要像百科全书。

第二步：统一启动和检查入口

至少有这两个脚本：

./scripts/init-agent.sh
./scripts/check.sh

其中：

init-agent.sh 负责安装依赖、准备环境、打印项目入口
check.sh 负责跑 lint、test、build、typecheck 或结构检查

Agent 最怕“每个项目都有一套不同的手工启动方式”。

第三步：每个任务独立工作区

推荐直接使用：

git worktree add ../task-login -b task/login

这样做的好处很直接：

不同任务互不覆盖
可以并行跑多个 Agent
恢复时不会污染主工作区

第四步：把进度写进仓库

最简单的方式是每个任务一个文件：

tasks/login.md

内容只要包括：

任务目标
当前状态
已完成事项
下一步
已知风险

这比把所有状态寄托在会话历史里可靠得多。

第五步：把确定性检查接进本地和 CI

最低要求：

本地能一键跑 check.sh
PR 上也会自动跑同样检查

一旦 Agent 输出不稳定，确定性检查就是你最重要的护栏。

第六步：准备一个小型 eval 集

先不要追求大而全。
挑 10 到 20 个真实任务就够了，比如：

修一个已知 bug
新增一个 API
改一个前端表单
做一次重构

每次改 harness 后，拿这组任务复跑，你才能知道到底有没有进步。

五、一个适合大多数项目的最小目录模板

如果你想快速开工，可以直接参考下面这个骨架：

.
├── AGENTS.md
├── docs/
│   ├── architecture.md
│   ├── dev-workflow.md
│   └── testing.md
├── scripts/
│   ├── init-agent.sh
│   ├── dev.sh
│   └── check.sh
├── tasks/
│   └── active-task.md
├── evals/
│   ├── cases/
│   └── graders/
└── .github/workflows/└── ci.yml

这个结构已经够你搭一个能跑起来的最小 harness 了。