Agent Harness 是什么？和 AGENTS.md 有什么关系？

你会学到：Agent Harness 不是一个必须马上安装的新工具，而是一套让 AI agent 稳定工作的外部结构。新手可以先用 AGENTS.md、任务卡和验收清单做最小版本。

先看结论

一句话：

模型负责思考和生成，Harness 负责给它边界、工具、反馈和验收环境。

如果你刚开始用 Codex，不需要先搭一个复杂平台。先做这 3 件事就够了：

1. 写一份短的 AGENTS.md，告诉 agent 这个项目怎么协作。
2. 每次任务前写任务卡，限制目标和可改范围。
3. 每次任务后按验收清单检查 diff、命令结果和风险。

你也可以直接用本站的 AGENTS.md 生成器 生成第一版。

为什么会出现 Harness 这个词？

很多人第一次用 AI 编程时，会把注意力放在“提示词怎么写”。但真实项目里，光有提示词不够。

AI agent 还需要知道：

• 它能看哪些文件。
• 它能不能运行命令。
• 哪些目录和操作禁止碰。
• 改完以后怎么证明结果是对的。
• 如果失败了，应该怎么复盘和重试。

这些规则、工具、反馈和检查环境合在一起，就可以理解成一个最小的 Agent Harness。

它和 AGENTS.md 的关系

AGENTS.md 是 Harness 的入口说明，不是全部 Harness。

可以这样理解：

组成	给新手的解释	最小做法
AGENTS.md	告诉 agent 进项目后先读什么、怎么协作	写项目边界、禁止事项、验收方式
任务卡	告诉 agent 这一次只做什么	写目标、范围、不能碰的文件
验收清单	告诉你怎么判断结果是否可接受	看 diff、跑命令、检查页面
工具和命令	给 agent 可用的手和眼睛	只开放必要命令
日志和截图	让 agent 能观察问题	新手先手动截图或记录错误
回滚方式	出错时能撤回	用 Git 或复制练习目录

所以，AGENTS.md 更像地图。Harness 是地图、工具、检查和反馈循环的总和。

新手的最小 Harness

不要一开始就追求“全自动 agent”。先做一个能保护你的最小版本。

1. 项目说明

写清楚项目是什么。

这是一个 VitePress 教程网站，主要内容是 Markdown 页面。
优先修改 guide/、questions/、practice/、reference/。

2. 安全边界

写清楚哪些不能碰。

不要修改密钥、Cookie、token、账号、付款、DNS、备案、仓库权限。
不要删除文件或批量改目录，除非用户明确确认。

3. 任务卡

每次只给一个小任务。

目标：补一页小白教程。
允许修改：questions/what-is-agent-harness.md。
禁止修改：配置、部署、账号、统计脚本。
完成标准：页面能构建，内链可打开。

4. 验收清单

改完以后不要只看 agent 说“完成了”。

- 改了哪些文件？
- diff 是否只在允许范围内？
- 构建、测试或页面检查是否通过？
- 还有哪些风险？

Codex、Claude Code、Cursor 都需要这件事

不同工具的入口不一样，但稳定协作的底层问题一样：

• Codex 需要知道 repo 规则和验收方式。
• Claude Code 需要知道终端命令、目录边界和权限边界。
• Cursor 需要知道编辑器内的上下文、可改范围和人工验收标准。

所以不要只比较“哪个更强”。先问：

我有没有给 agent 一个可执行、可检查、可撤回的工作环境？

这就是 Harness 思维。

什么时候需要更复杂的 Harness？

下面这些情况，才需要更系统的 Harness：

• 任务会持续几十分钟或更久。
• agent 需要自己跑测试、看日志、截图、修复、再验证。
• 团队里有多人或多个 agent 协作。
• 项目需要沙盒、临时环境、自动化评审、CI、监控和回滚。
• 你希望 agent 不只是改文件，而是能完整处理 issue、PR、测试和反馈。

如果你只是第一次用 Codex，先不要做这么复杂。先把最小三件套做好：

AGENTS.md + 任务卡 + 验收清单

常见误区

• 误区 1：把 Harness 理解成某个固定产品。它更像一套工作结构。
• 误区 2：以为提示词越长越好。过长的规则会挤占上下文，也更容易过期。
• 误区 3：把所有知识都塞进 AGENTS.md。更好的做法是短入口加清晰链接。
• 误区 4：直接让 agent 碰生产项目。新手应该先在低风险练习目录里试。
• 误区 5：只看生成速度，不看验证和回滚。

你现在该做什么？

如果你还没有任何规则：

1. 打开 AGENTS.md 生成器。
2. 填项目类型、允许范围、禁止事项和检查命令。
3. 复制生成的 AGENTS.md 到练习项目根目录。
4. 用任务卡让 Codex 做一个 README 或文档小任务。
5. 按验收清单看 diff 和检查结果。

完成标准

读完这一页，你应该能做到：

• 能用一句话解释 Agent Harness。
• 知道 AGENTS.md 是 Harness 的入口，不是全部。
• 知道新手先做 AGENTS.md + 任务卡 + 验收清单。
• 知道什么时候才需要更复杂的沙盒、日志、CI 和自动评审。

推荐下一步

• 直接动手：AGENTS.md 生成器
• 理解协作说明：AGENTS.md 写给 agent
• 控制风险：任务边界和安全目录
• 学会验收：怎么看 diff 和验证结果

来源与复核

• 官方来源：OpenAI Harness engineering 讨论了 Codex agent-first 工作流、仓库知识、反馈循环和 agent 可读性。
• 相关工程讨论：Anthropic Managed Agents 与 Cognition Cloud Agents 都强调 agent 需要执行环境、状态、隔离和反馈。
• 社区信号：awesome-agent-harness 正在整理 Agent Harness 工程资源。
• 本站建议：小白先做最小 Harness，不要直接追求全自动。
• 复核日期：2026-06-10。