Harness Engineering 不是 AGENTS.md 或 CLAUDE.md
Harness engineering is not AGENTS.md理解 Harness Engineering 之后，一个很自然的问题是：
如果我已经给项目写了 AGENTS.md 或 CLAUDE.md，是不是就算给 Agent 准备好了工作条件？
并不是。
这些文件很重要，但它们主要解决的是：
Agent 进入项目时，应该先知道什么？
一套真正的 Harness 还要继续解决：
它去哪里找信息、怎样完成任务、哪些边界不能越过，以及做完后如何检查和恢复。
AGENTS.md 不是越详细越好
OpenAI 在实践中尝试过把大量项目知识和规则塞进一份巨大的 AGENTS.md。
结果并不好。
文件太大，会挤占真正执行任务所需的 Context；规则太多，Agent 反而难以区分重点；内容也很容易过期，而 Agent 未必知道哪些信息仍然可信。
所以他们后来保留了一份较短的 AGENTS.md，主要把它当成项目地图，再指向更具体的产品说明、架构文档和执行计划。
OpenAI 对此的概括是：
给 Agent 一张地图，而不是一本一千页的说明书。
Anthropic 对 CLAUDE.md 的建议也很接近。
CLAUDE.md 适合保存每次进入项目都需要知道的稳定信息，例如构建命令、项目约定、架构决策和常见工作流。
但只对特定文件生效的规则，可以放到分目录规则里；只在某类任务中需要的流程，可以放到 Skill 里。Anthropic 还建议单个 CLAUDE.md 尽量控制在 200 行以内。
更重要的是，Anthropic 明确说明：
CLAUDE.md 是提供给模型的 Context，不是强制执行的系统配置。
Claude 会尝试遵守，但不能保证每次都严格做到。真正不能违反的规则，需要进一步变成权限、自动检查或执行前确认。
所以，AGENTS.md 和 CLAUDE.md 更像入职说明。
它们是 Harness 的入口，却不是 Harness 的全部。
一套 Harness 还需要什么？
如果不使用太多工程术语，我会把它分成五部分。
1. 一个可信的项目入口
Agent 首先需要知道：
这个产品解决什么问题；当前以哪份文档为准；代码和资料如何组织；哪些决定已经确认；哪些方向已经放弃；遇到不同问题应该去哪里找答案。
重点不是把所有资料一次性塞给它。
而是让它知道：
哪些信息可信，以及如何继续找到相关信息。
否则，项目里即使有几十份文档，Agent 也可能读到一份已经过期的说明，然后非常认真地执行错误方向。
2. 一个清楚的当前任务
知道整个项目是什么，还不等于知道现在要做什么。
Agent 每次开工，最好能明确看到：
这次只解决哪个问题；哪些内容在任务范围内；哪些内容不要顺手修改；怎样才算完成；最终需要留下什么证据。
例如，与其只写：
优化注册流程。
不如写清楚：
修复企业用户注册后收不到验证邮件的问题。不要重构其他注册逻辑。完成后分别测试普通用户和企业用户，并提供测试结果。
这里的关键不只是 Prompt 写得更长，而是把任务范围和验收条件变成项目中可以持续追踪的状态。
Anthropic 在长任务实验中，也通过功能清单、进度文件和 Git 记录，让不同 session 能看到上一轮完成了什么、项目是否处于正常状态，以及下一步应该做什么。
3. 完成任务需要的工具
Agent 能读写代码，只代表它能修改项目。
不代表它能判断产品是否真的正常。
根据任务不同，它还可能需要：
启动应用；操作浏览器；创建测试账号；查看错误日志；读取测试数据库；运行完整用户流程；比较修改前后的结果。
如果它只能看代码，很多时候就只能根据代码推测结果。
如果它能打开产品、复现问题、完成操作并读取日志，就更有机会发现：
代码虽然能运行，但真实流程仍然有问题。
4. 真正能够执行的边界
有些规则写在文档里就够了，例如：
文件如何命名；草稿放在哪里；提交前运行哪个测试。
但有些边界不能只靠一句提醒：
不能操作生产数据；不能直接发送客户邮件；不能删除关键文件；添加新依赖前必须确认；涉及付款时必须交给人。
这类边界最好由权限、自动检查或确认流程真正落实。
例如：
“不要修改生产数据库”写在 AGENTS.md 里，是行为指导。
如果 Agent 本身根本没有生产数据库的写入权限，才是系统边界。
两者都重要，但可靠程度不同。
5. 检查、隔离和恢复
Agent 修改了代码，不代表任务已经完成。
它还需要知道：
必须运行哪些测试；是否要走完整用户流程；如何检查已有功能没有被破坏；最后要提供截图、日志还是测试结果；如果修改错误，怎样撤回。
另外，过程文件也需要有明确去处。
Agent 工作时经常会生成：
临时脚本；测试数据；截图；日志；草稿；中间导出文件。
如果这些内容散落在项目根目录里，时间久了，人和 Agent 都很难区分：
哪些是正式交付物；哪些只是过程文件；哪些已经没有用了。
所以，隔离也可以是最小 Harness 的一部分：
临时脚本放进固定目录；截图和测试输出单独保存；正式文件与中间产物分开；任务结束后检查是否需要清理。
版本记录同样重要。
保留清楚的 diff、较小的 commit 和可回滚状态，可以避免 Agent 在一次错误修改上继续叠加更多工作。
个人项目需要搭得这么复杂吗？
不需要。
OpenAI 的案例来自一个规模很大、由 Agent 长时间参与开发的代码库，不能直接照搬到每个个人项目。OpenAI 自己也强调，他们获得的 Agent 自主能力高度依赖为该项目特别设计的结构、工具和反馈机制。
个人项目可以先从一个很轻的版本开始：
- 一份简短的 AGENTS.md 或 CLAUDE.md，作为项目入口；
- 一份可信的当前计划，区分已确认、待决定和已放弃的内容；
- 每次任务有明确范围和验收条件；
- 写清楚如何启动、测试和检查项目；
- 标明不能修改的内容和必须确认的操作；
- 给临时文件、截图和测试输出固定的隔离目录；
- 使用 Git 查看修改，并保留可以恢复的版本。
任务越短、结果越容易肉眼检查，这些准备可以越轻。
但当任务跨越多个文件、多个 session，或者 Agent 开始拥有更大的操作权限时，只靠一份 Prompt 和一个入口文档，就越来越不够了。
AGENTS.md 或 CLAUDE.md 告诉 Agent如何进入项目。
Harness Engineering 关心的，是它进入以后，怎样找到信息、完成任务、遵守边界、检查结果，并在做错时退回来。