type
status
date
slug
summary
tags
category
icon
password
wechat_gate
notion image
你的 AI Agent 又搞砸了。
报错、乱改文件、无视代码规范、跑到一半突然不知道自己在做什么。你换了模型，好了两天，又开始出问题。
下一步，你打算换第四个模型。
这里有一个错觉需要打破：Agent 的质量，70% 由 Harness 决定，不是模型。
Harness 是围绕模型的一切——提示词、工具、上下文策略、钩子、子 Agent、反馈回路、恢复路径。裸模型不是 Agent，它只有接上 Harness 才能真正干活。
一个成熟的 Harness + 普通模型，稳定跑赢顶配模型 + 烂 Harness。
这不是观点，这是现在一线工程团队正在验证的结论。

Agent = 模型 + Harness

最简洁的定义来自工程师 Trivedy：
Agent = 模型 + Harness。
如果你不是模型，你就是 Harness。
Harness 包括：
  • 工具调用、MCP 服务器，以及工具的技术说明
  • 文件系统、沙盒、无头浏览器等运行环境
  • 子 Agent 的编排逻辑、任务分发、切换机制
  • Hooks：代码检查、格式校验、权限拦截等确定性执行层
  • 日志、成本监控、延迟追踪等可观测性工具
看着多，但这整块都是你的地盘，不是模型提供商的。
Claude Code、Cursor、Codex、Cline——这些工具底层可能跑着同一个模型，但你体验到的效果由 Harness 决定。不同的 Harness，不同的 Agent 表现。
这也解释了为什么很多人抱怨"Claude 变笨了"——模型没变，是他们的 Harness 落后了。
notion image

大多数人把 Harness 问题误诊成模型问题

你遇到过这种情况：
Agent 忽略了某个约定，你觉得"它没理解我的意思"。 Agent 运行了一个危险命令，你觉得"这个模型太激进了"。 Agent 在 40 步任务里迷路，你觉得"它不够聪明"。
都不是。
如果 Agent 忽略了某个约定，把它加进 AGENTS.md。如果它运行了危险命令，写个 Hook 拦截。如果它在长任务里迷路，把架构拆成 Planner + Executor 两个 Agent。
HumanLayer 团队有一句话说得很直接："不是模型问题，是配置问题（It's not a model problem. It's a configuration problem.）"
把失败归咎于模型，是最省力但也最没用的反应。

Context Engineering：上下文不是越多越好

Harness 里有一个层面经常被低估：上下文管理。
很多人以为喂给 Agent 的信息越多越好——项目文档、代码文件、API 文档全部塞进去。
恰恰相反。
Google 工程总监 Antonio Gullí 在《Agentic Design Patterns》里定义了一个概念叫 Context Engineering：
不做信息堆砌，做的是精心筛选、裁剪、打包上下文。
要让 AI 达到最高准确率，必须给它短小、聚焦、有力的上下文。
举一个具体例子：用户要在两个地点之间找咖啡店。
信息堆砌做法：把地图 API 的全部返回数据喂给 Agent，让它自己判断。
Context Engineering 做法：Agent 调完地图工具，自己判断"下一步只需要街道名称"，把返回数据裁剪成一个短列表，再喂给本地搜索工具。
每一步都在做信息降噪。
你的 CLAUDE.md、你的 Skill 文件、你的工具描述——这些都是在做 Context Engineering，只是很多人没意识到。
写进去的每一行，都在影响 Agent 每次推理的上下文质量。写进去的噪音越多，推理质量越低。
notion image

最重要的原则：棘轮

这是 Harness Engineering 里我认为最有价值的一个机制。
棘轮的特点是只能往前，不能倒退。
Harness 的棘轮逻辑：每次 Agent 犯错，就设计一个永久的解决方案，让它不再犯同样的错误。
不是重试。不是希望下次运气好。是永久修复。
举个真实场景：Agent 提交了一个带注释掉测试代码的 PR，被合进了主分支。
错误的反应：手动改掉，下次注意。
棘轮反应：
  1. AGENTS.md 加一条："永远不要注释掉测试；要么修复，要么删除。"
  1. pre-commit Hook 自动检测 .skip( 出现在 diff 中，直接拦截。
  1. Reviewer 子 Agent 的指令里加一条：注释掉的测试属于阻断项，不得合并。
三道防线，同一个错误不会再发生。
棘轮还有另一面：规则应该在你观察到真实失败时添加，在模型进化让它失效时删除。 一个好的系统提示词不会无限膨胀，它是活的。
notion image

CLAUDE.md 不是说明书，是失败日志

这是大多数人用错的地方。
他们把 CLAUDE.md 写成"写给 AI 的项目介绍"，里面堆满代码规范、技术栈列表、架构说明。这些东西有用，但不够。
真正成熟的 CLAUDE.md，每一行规则都能追溯到一次真实的失败。
"不要使用 any 类型，除非明确授权" → 来自某次 TypeScript 检查失败，导致了生产 Bug。
"提交前运行完整测试套件，即使只改了一行" → 来自某次修一个小 Bug 时顺手改了相关逻辑，没跑测试，第二天发现回归。
"处理文件操作时，先备份，再修改" → 来自某次 Agent 覆盖了不该覆盖的配置文件。
规则不是编出来的，是磨出来的。
如果你的 CLAUDE.md 里有一条规则，你说不出它来自什么事故——它大概率是没用的噪音，反而在稀释有效规则的权重。

.claude 文件夹：团队大脑 + 个人大脑

Claude Code 有一个设计相当聪明：两套 .claude 目录分开管理。
项目级 .claude/（放在项目根目录，进 Git）
团队共享的规则、工具、钩子、安全策略全在这里。新成员 clone 代码，自动继承整套 Agent 行为规范，不用重新配置。这套配置应该视作工程资产，跟代码一样维护。
全局 ~/.claude/（个人目录，不进 Git）
你的个人编码风格偏好、跨项目适用的全局规则、私人工具快捷入口。
分开的好处是团队标准化和个人自由化互不干扰。你的奇怪习惯不会污染生产配置，新人也不需要花半天研究你的个人设置。

Bun 案例：一个 Harness 成熟度的基准

想知道一套成熟的 Harness 能做到什么程度？
去年 Bun 团队用 Claude Code 做了一件事：把 75 万行代码从 Zig 迁移到 Rust，11 天完成合并，测试通过率 99.8%。
这件事的关键不是"Claude Code 很强"。
关键是：他们围绕这个任务设计了足够成熟的 Harness——把任务拆成数十个子 Agent 并行处理，有人专门扫 Bug，有人处理迁移，有人做代码审查。每个子 Agent 都有清晰的职责和约束。
没有 Harness 设计，75 万行迁移让单个 Agent 扛，不可能跑通。

停止问"哪个模型更聪明"

说实话，我评估 AI 工具的方式变了。
以前的问题：这个模型支持多少上下文？代码能力排名多少？
现在的问题：这套 Harness 有多成熟？失败反馈机制完不完善？错误恢复路径有没有设计？
这不是说模型不重要，是当下大多数场景里模型已经足够好了。
Anthropic 有一句话很精准：
今天的模型理论上能做的，和你实际看到它做的，中间那段距离——几乎全是 Harness 问题。
换句话说，模型的上限够高，你的 Harness 是否到位，决定了你能发挥出多少。

你现在可以做的第一件事

打开你的 CLAUDE.md，或者新建一个。
想想上周你的 AI 工具犯了什么错误。
把那个错误变成一条规则，写进去，加上来源说明。
就这一条。
这是棘轮的第一个齿。接下来每次 Agent 犯错，再加一条。不用一次性设计完美系统，Harness 本来就是磨出来的。
三个月后，你的 CLAUDE.md 会变成你们合作历史的压缩版——每一行规则背后，都是一次没有重复犯过的错误。
 
写 AI，写成长，偶尔写投资。 关注沐风，不定期更新，全是干货。
 
2026.06.08 23:30 沪·赵巷
📌 声明：本文由 AI 辅助完成