Agent Harness实战：用Markdown文件搭AI工作框架
Agent = 模型 + Harness
大多数人把AI Agent用不好归结为「模型不够聪明」。换个更强的模型试试就好了？实战中真正拖后腿的往往不是模型的理解能力，而是模型工作的环境。
作者的核心论点很简单：
Agent = 模型 + Harness（操作框架）
到了一定复杂度之后，Harness才是真正的瓶颈。好消息是，构建一个好的Harness不需要复杂的框架或代码层面的编排——只需要在仓库里放好几个Markdown文件。
Harness的五个子系统
经过多个项目实践后，作者把Harness拆解为五个子系统。缺任何一个，Agent用起来都会别扭——就像一辆没有仪表盘或刹车的车。
1. 指令（Instruction）
一个入口文件（AGENTS.md 或 CLAUDE.md），包含：
- 项目概述（一句话+目标受众）
- 技术栈和版本号
- 首次启动命令（从头拉代码到能跑起来）
- 硬规则（「永远不要修改这个文件」「生产环境必须过代码审查」）
2. 工具（Tools）
给Agent足够的权限去做实事。禁用Shell「为了安全」导致Agent连 pip install 都做不了，就像雇了一个工程师然后没收了他的键盘。
原则是最小权限，不是零权限。
3. 环境（Environment）
一个能自我描述的环境：锁定依赖、固定运行时版本、可复现的容器。Agent如果在一个broken的环境里挣扎，它的注意力会浪费在错误的战场上。
4. 状态（State）
记录完成了什么、进行中什么、卡住了什么。让工作跨会话延续。最简单的实现就是PROGRESS.md文件。
5. 反馈（Feedback）
这是ROI最高的子系统——给Agent明确的命令来判断自己的输出是否正确。这个子系统决定了Agent是「猜自己完成了」还是「可以自己检查」。
如果只加一个子系统，加这个。
仓库即规范
If it isn’t in the repository, it does not exist to the agent.
这句是整个文章最核心的一句话。一个AI Agent在一个结构混乱的仓库里，就像一个有才华的新员工没有任何入职培训——精力都浪费在找方向上了。
但如果你给它一张清晰的地图——一个入口路由文件、与代码同位的文档、准确的验证命令——同一个模型可以从20%的成功率跳到接近完美。
真实项目中，大量知识存在于：
- Slack 聊天记录
- 早已过时的 Confluence 页面
- 零散的代码注释
- 两三个核心成员的脑子里
每一条对Agent来说都是盲区。每个盲区都迫使它做一次猜测。
测试方法： 打开一个全新的Agent会话，只给它仓库，问五个关于项目的问题。如果它答不出或答错，说明你的仓库作为规范不合格。
验证块：十分钟最高ROI的投入
在AGENTS.md里放一个验证命令块，十分钟的工作能改变一切：
## Verification Commands
- Tests: pytest tests/ -x
- Type check: mypy src/ --strict
- Lint: ruff check src/
- Full check: make check # runs all of the above
作者把所有验证路由到 make targets。这样Agent不需要猜项目用npm、yarn、poetry还是pipenv——Harness提供一个统一入口。
如何给Agent画一张好地图
入口文件要短
AGENTS.md控制在200行以内。不是所有信息都塞进去——它只做路由和核心规则。
知识放在代码旁边
数据库Schema写在SQL迁移文件里而不是单独的文档里。API路由写在路由定义文件旁边而不是Wiki里。Agent不需要翻Wiki，它只需要翻代码。
删除冗余指令
每条指令加入前问自己：「如果删了这一行，Claude会犯错吗？」如果不会，删掉。CLAUDE.md底部的指令经常被忽略——保持简短才是真正让重要内容生效的方式。
补充与反思
最让我认同的观点
作者关于反馈子系统的判断是整篇文章最有价值的部分。给Agent一个能自己验证的命令，比给它一万字的指令文件有用得多。因为Agent能自己回答「我做对了没有」，不需要每次都等你检查。
一个被弱化的点
作者假设Agent能自动发现并理解Markdown文件的结构。实际上，对于文件多、层次深的仓库，即使有AGENTS.md做入口，Agent仍然可能在导航过程中丢失上下文。入口文件控制在200行以内、硬规则放在最前面，是目前实践中最有效的缓解措施。
实用建议
如果你正在用Claude Code或类似Agent工具做开发，花一小时改善仓库的AGENTS.md和验证体系，是本周ROI最高的技术投资。
从反馈子系统开始——先让Agent能自己验证结果。不要一上来就想搭完整的五子系统。
总结
Harness的核心思路——用Markdown文件做Agent的工作框架——可以在任何项目中直接复用，不需要重写任何代码。五个子系统中，反馈的ROI最高，也最容易见效。
从今天开始：打开你的AGENTS.md，删掉30%不需要的指令，加一个 make check 的统一验证入口。Agent的工作质量会立刻提升。