Agent 跑偏真相：Harness Engineering 入门

最近 lopopolo/harness-engineering 在 GitHub Trending 拿到 2167 stars，它把”如何在 AI 编码代理下写出可维护软件”这件事系统化了。仓库收录了 Ryan Lopopolo 多年来与 Claude Code、Cursor、Aider 等 Agent 协作的实战经验：CLAUDE.md 模板、上下文压缩策略、agent prompt 调优、错误恢复流程——统称为 Harness。这不是新的 Agent 框架，而是一套”约束 Agent 行为”的工程方法论。在 LLM 编码助手全面铺开的 2026 年，谁能把 Harness 写好，谁就能让 Agent 从”玩具”变成”初级工程师”。

Q1：Harness Engineering 到底在解决什么问题？

很多人以为让 Agent 写代码就是给它一段 prompt。但 LLM 本身是无状态的——它不记得你昨晚改了哪个函数，也不会主动验证自己的改动是否破坏了其他模块。Harness 就是包裹 Agent 的一层”操作系统”：负责加载上下文、裁剪历史、执行工具调用、校验产物。lopopolo 把这层抽象总结为 “harness = context + tools + loop”——context 决定 Agent 看到什么，tools 决定它能做什么，loop 决定它怎么迭代。理解了这三件套，你就理解了为什么同样的 Claude 模型，套上不同 Harness 后表现天差地别。

Q2：为什么 CLAUDE.md 比 prompt 更重要？

Harness Engineering 强调：上下文是 Agent 的”工作记忆”。CLAUDE.md（或 AGENTS.md、.cursorrules）就是这份记忆的入口。仓库里给出了一个最小可用模板：

# Project Context
- Tech stack: TypeScript + Next.js 15 + Postgres
- Build: `pnpm build` 必须以 exit code 0 结束才能 commit
- Test: `pnpm test` 必须覆盖 src/** 下所有改动文件
- Style: 优先使用函数组件，禁止 `any`

# Non-goals
- 不要修改 /generated 下的任何文件
- 未经许可不得新增顶层依赖

# Workflow
- 每次编辑后跑 `pnpm lint --fix` 然后 `pnpm typecheck`
- 在宣称任务完成前必须给出 diff 摘要

把这类规则放进文件而不是塞进 prompt 的好处是：上下文持续存在、不被聊天历史稀释、可以进 git review 接受团队评审，也能在 PR 里被追溯。

Q3：Agent 跑长任务上下文丢失怎么办？

这是 HN 和 Reddit 上最常被吐槽的点。Agent 跑了 50 个 tool call 后开始 hallucinate，忘记了最初的约束。Harness Engineering 的解法是”分阶段 + 显式 checkpoint”：

1. 把大任务拆成 ≤ 10 步的小任务，每个任务独立调用一次 Agent；
2. 每完成一个子任务，把结果写回磁盘（JSON / markdown），而不是堆在上下文里；
3. 下一次 Agent 调用时只读 checkpoint 文件，让模型”重新建立工作记忆”。

仓库里 patterns/checkpoint.md 给出了一个最小循环实现：

def run_with_checkpoint(agent, task):
    state = load_checkpoint(task.id) or {"done": [], "todo": task.steps}
    while state["todo"]:
        step = state["todo"][0]
        result = agent.run(step, context=state)
        state["done"].append({"step": step, "result": result})
        state["todo"].pop(0)
        save_checkpoint(task.id, state)
    return state

这套循环让 Agent 不会”记性变差”，因为它根本不依赖记性——状态全在磁盘上。

Q4：Agent 改坏了我的代码怎么办？

r/ClaudeAI 上每周都有人贴”Claude Code 把我的项目搞坏了”的求助帖。根因往往是缺少”产物校验”环节。Harness Engineering 要求每个 Harness 都有 verifier：在 Agent 声明完成前，自动跑 build + test + lint，把结果作为新的 tool result 喂回去。失败就强制重规划。仓库里收录的 verifier-loop.md 推荐用 JSON Schema 约束 Agent 的输出：

{
  "type": "object",
  "required": ["files_changed", "tests_passed", "lint_passed"],
  "properties": {
    "files_changed": {"type": "array", "items": {"type": "string"}},
    "tests_passed": {"type": "boolean"},
    "lint_passed": {"type": "boolean"}
  }
}

Agent 必须填齐这三项才能进入下一阶段。这就是把”模型自觉”转化成”工程约束”的精髓——你不要相信 LLM 自称”改完了”，你要让 CI 当裁判。

Q5：Harness 跟 prompt engineering 到底有什么区别？

这是一个反共识点：很多人花大量时间微调 system prompt，但收效甚微。Harness Engineering 认为 prompt 只是 harness 的一个组件，不是全部。一个完整的 harness 至少包含：context files、tool definitions、loop policy、verifier、recovery strategy。光改 prompt 不动其他四样，就像只踩油门不换轮胎。lopopolo 在 README 里说得很直接：“Don’t blame the model, audit your harness.” 所以下次 Agent 跑偏，先别升级模型，回去看 harness 缺了哪一块——很多时候答案根本不在 GPT-5 还是 Claude 4，而在你有没有写好那份 CLAUDE.md。

Sources

• GitHub Trending 2026-07-23: lopopolo/harness-engineering
• r/ClaudeAI: “Claude Code broke my repo” 讨论串（2026 年 6 月）
• Hacker News: “Harness Engineering” 主题讨论
• 仓库内 patterns/、examples/、CLAUDE.md 目录
• Ryan Lopopolo 个人博客：关于 agent context 的系列文章