https://xedczq.cn/tags/harness/Recent content in Harness on XEDCZQ的博客Hugo -- gohugo.iozh-cnTue, 19 May 2026 11:29:42 +0800https://xedczq.cn/post/agent_harness%E5%B7%A5%E7%A8%8B/Tue, 19 May 2026 11:29:42 +0800https://xedczq.cn/post/agent_harness%E5%B7%A5%E7%A8%8B/<h1 id="harness-engineering-到底是什么"><a href="#harness-engineering-%e5%88%b0%e5%ba%95%e6%98%af%e4%bb%80%e4%b9%88" class="header-anchor"></a>Harness Engineering 到底是什么 </h1><p>我对这几篇文章交叉看完后的结论是：</p> <p>Harness Engineering 不是“写更好的 prompt”这么简单，而是把 <strong>模型之外的所有工程化能力</strong> 设计成一个可迭代系统，让 Agent 在长任务里稳定地产生可验证结果。</p> <p>一句话总结：</p> <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="cl">Agent = Model + Harness </span></span><span class="line"><span class="cl">Harness = 状态管理 + 工具系统 + 约束规则 + 反馈回路 + 执行编排 </span></span></code></pre></div><p>也就是说，模型负责“智能”，Harness 负责“让智能可用、可控、可复用”。</p> <h2 id="共同观点跨文章对齐"><a href="#%e5%85%b1%e5%90%8c%e8%a7%82%e7%82%b9%e8%b7%a8%e6%96%87%e7%ab%a0%e5%af%b9%e9%bd%90" class="header-anchor"></a>共同观点（跨文章对齐） </h2><table> <thead> <tr> <th>主题</th> <th>共识</th> </tr> </thead> <tbody> <tr> <td>Harness 定义</td> <td>不是模型本身，而是围绕模型的代码、配置、流程、工具和验证机制</td> </tr> <tr> <td>目标</td> <td>降低监督成本，提高首轮正确率，支持长时间连续执行</td> </tr> <tr> <td>关键方法</td> <td>把失败模式工程化沉淀：规则、工具、测试、回路</td> </tr> <tr> <td>长任务核心矛盾</td> <td>上下文有限、会话中断、状态漂移、过早“宣告完成”</td> </tr> <tr> <td>解决方向</td> <td>增量任务拆分、状态交接、自动验证、可观测反馈、持续纠偏</td> </tr> </tbody> </table> <h3 id="我理解的-5-个核心组成"><a href="#%e6%88%91%e7%90%86%e8%a7%a3%e7%9a%84-5-%e4%b8%aa%e6%a0%b8%e5%bf%83%e7%bb%84%e6%88%90" class="header-anchor"></a>我理解的 5 个核心组成 </h3><ol> <li>任务脚手架</li> </ol> <ul> <li>明确任务拆分策略（一次只做一个 feature）</li> <li>明确完成定义（DoD），避免“看起来做完了”</li> </ul> <ol start="2"> <li>状态与记忆</li> </ol> <ul> <li>可恢复状态：进度文件、提交记录、变更说明</li> <li>会话切换时有 handoff，不靠模型“猜”历史</li> </ul> <ol start="3"> <li>工具与环境</li> </ol> <ul> <li>给 Agent 快速、确定性的工具（测试、lint、截图、日志查询）</li> <li>让 Agent 能自助获取上下文，而不是人工复制粘贴</li> </ul> <ol start="4"> <li>反馈与传感器</li> </ol> <ul> <li>计算型传感器：lint/typecheck/unit/e2e（快、确定）</li> <li>推理型传感器：LLM review/语义 QA（慢、贵、但能看语义质量）</li> </ul> <ol start="5"> <li>调度与治理</li> </ol> <ul> <li>失败后不是“再试一次”，而是补能力</li> <li>沉淀规则模板（AGENTS.md/docs/checklist），把经验组织化</li> </ul> <h2 id="普通用户做-webcoding-的-harness-流程"><a href="#%e6%99%ae%e9%80%9a%e7%94%a8%e6%88%b7%e5%81%9a-webcoding-%e7%9a%84-harness-%e6%b5%81%e7%a8%8b" class="header-anchor"></a>普通用户做 WebCoding 的 Harness 流程 </h2><p>对于普通用户的学习，尤其是在找工作和刚刚进入职场的朋友一上来就用最规范的框架肯定是无法适应的。开发者也需要一个逐渐熟练使用harness的阶段。</p> <h3 id="第-0-步先定义完成"><a href="#%e7%ac%ac-0-%e6%ad%a5%e5%85%88%e5%ae%9a%e4%b9%89%e5%ae%8c%e6%88%90" class="header-anchor"></a>第 0 步：先定义“完成” </h3><p>先写一页 <code>SPEC.md</code>（需求规格说明文档，Specification），每个功能包含：</p> <ul> <li>用户场景</li> <li>输入输出</li> <li>验收标准</li> <li>失败场景</li> </ul> <p>没有这一步，后面 Agent 很容易“自我感觉良好”。</p> <h3 id="第-1-步建立最小-harness-文件"><a href="#%e7%ac%ac-1-%e6%ad%a5%e5%bb%ba%e7%ab%8b%e6%9c%80%e5%b0%8f-harness-%e6%96%87%e4%bb%b6" class="header-anchor"></a>第 1 步：建立最小 Harness 文件 </h3><p>建议至少有这 4 个文件：</p> <ul> <li><code>AGENTS.md</code>：仓库工作规则（命令、目录约定、禁改区域、提交规范）</li> <li><code>TASKS.md</code>：功能清单，状态用 <code>todo/doing/done</code></li> <li><code>PROGRESS.md</code>：每轮 Agent 执行后写入“做了什么/没做完什么/下一步”</li> <li><code>CHECKLIST.md</code>：统一验收项（构建、测试、UI、性能、安全）</li> </ul> <h3 id="第-2-步一轮只做一个-feature"><a href="#%e7%ac%ac-2-%e6%ad%a5%e4%b8%80%e8%bd%ae%e5%8f%aa%e5%81%9a%e4%b8%80%e4%b8%aa-feature" class="header-anchor"></a>第 2 步：一轮只做一个 Feature </h3><p>执行策略：</p> <ul> <li>从 <code>TASKS.md</code> 取一项</li> <li>给 Agent 一个明确边界任务</li> <li>禁止“一次性做完整站点”</li> </ul> <p>这样能显著降低上下文混乱和回归风险。</p> <h3 id="第-3-步让-agent-先改再自证"><a href="#%e7%ac%ac-3-%e6%ad%a5%e8%ae%a9-agent-%e5%85%88%e6%94%b9%e5%86%8d%e8%87%aa%e8%af%81" class="header-anchor"></a>第 3 步：让 Agent 先改，再自证 </h3><p>每轮要求 Agent 固定输出：</p> <ul> <li>改了哪些文件</li> <li>为什么这样改</li> <li>跑了哪些命令</li> <li>哪些检查通过/失败</li> <li>风险点和回滚点</li> </ul> <p>这一步等价于把“隐性思考”转成“显性审计线索”。</p> <h3 id="第-4-步双层验证计算型优先"><a href="#%e7%ac%ac-4-%e6%ad%a5%e5%8f%8c%e5%b1%82%e9%aa%8c%e8%af%81%e8%ae%a1%e7%ae%97%e5%9e%8b%e4%bc%98%e5%85%88" class="header-anchor"></a>第 4 步：双层验证（计算型优先） </h3><p>每轮至少跑：</p> <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">npm run lint </span></span><span class="line"><span class="cl">npm run <span class="nb">test</span> </span></span><span class="line"><span class="cl">npm run build </span></span></code></pre></div><p>如果是前端页面改动，再加：</p> <ul> <li>关键路径截图对比</li> <li>关键交互手测清单</li> <li>主要断点的响应式检查</li> </ul> <p>规则是：先过计算型传感器，再上推理型审查。</p> <h3 id="第-5-步失败即沉淀为-harness-资产"><a href="#%e7%ac%ac-5-%e6%ad%a5%e5%a4%b1%e8%b4%a5%e5%8d%b3%e6%b2%89%e6%b7%80%e4%b8%ba-harness-%e8%b5%84%e4%ba%a7" class="header-anchor"></a>第 5 步：失败即沉淀为 Harness 资产 </h3><p>当 Agent 出错，不要只修当前 bug，要顺手做一件事：</p> <ul> <li>能写规则就写进 <code>AGENTS.md</code></li> <li>能写脚本就加工具脚本</li> <li>能写检查就加到 <code>CHECKLIST.md</code></li> </ul> <p>目标是“同类错误不再发生”，这一步尤其重要是逐渐优化项目匹配harness的过程。</p> <h3 id="第-6-步长任务做会话交接"><a href="#%e7%ac%ac-6-%e6%ad%a5%e9%95%bf%e4%bb%bb%e5%8a%a1%e5%81%9a%e4%bc%9a%e8%af%9d%e4%ba%a4%e6%8e%a5" class="header-anchor"></a>第 6 步：长任务做会话交接 </h3><p>当任务超过 1 个上下文窗口时，强制生成 handoff：</p> <ul> <li>当前目标</li> <li>已完成</li> <li>未完成</li> <li>阻塞点</li> <li>下轮第一步</li> </ul> <p>并且落到 <code>PROGRESS.md</code> 或执行计划文件，而不是只留在对话里。</p> <h3 id="第-7-步合并前做一次发布级回路"><a href="#%e7%ac%ac-7-%e6%ad%a5%e5%90%88%e5%b9%b6%e5%89%8d%e5%81%9a%e4%b8%80%e6%ac%a1%e5%8f%91%e5%b8%83%e7%ba%a7%e5%9b%9e%e8%b7%af" class="header-anchor"></a>第 7 步：合并前做一次“发布级回路” </h3><p>合并前统一跑一轮：</p> <ul> <li>回归测试</li> <li>页面主路径冒烟</li> <li>性能与错误日志快速巡检</li> <li>Agent 自评 + 人工抽查</li> </ul> <p>这一步是防止“单点通过，整体失稳”。</p> <h3 id="第-8-步周维度做-harness-垃圾回收"><a href="#%e7%ac%ac-8-%e6%ad%a5%e5%91%a8%e7%bb%b4%e5%ba%a6%e5%81%9a-harness-%e5%9e%83%e5%9c%be%e5%9b%9e%e6%94%b6" class="header-anchor"></a>第 8 步：周维度做 Harness 垃圾回收 </h3><p>每周处理：</p> <ul> <li>删除过期规则</li> <li>修复失效脚本</li> <li>合并重复约束</li> <li>更新 docs 索引</li> </ul> <p>Harness 也是代码，不维护会腐化。</p> <h2 id="从零开始尝试"><a href="#%e4%bb%8e%e9%9b%b6%e5%bc%80%e5%a7%8b%e5%b0%9d%e8%af%95" class="header-anchor"></a>从零开始尝试 </h2><p>可以现在就在你的项目中，用ai工具协助你创建以下文件：</p> <ol> <li><code>AGENTS.md</code> 写 20-50 行硬规则，不要过于冗杂</li> <li>每次只让 Agent 做 1 个功能点</li> <li>每轮固定跑 <code>lint/test/build</code></li> <li>每轮写 <code>PROGRESS.md</code></li> <li>发现重复错误就补规则或脚本</li> </ol> <p>仅这 5 条，通常就能把“靠感觉用 Agent”升级为“可持续提效的工程流”。</p> <h2 id="实践理解"><a href="#%e5%ae%9e%e8%b7%b5%e7%90%86%e8%a7%a3" class="header-anchor"></a>实践理解 </h2><p>Harness Engineering 本质上是在回答一个问题：</p> <blockquote> <p>当 Agent 出错时，你是重复监督它，还是把错误转化成系统能力？</p> </blockquote> <p>前者只会消耗人；后者会复利。</p> <p>所以对普通 webcoding 用户来说，最重要的不是多高级的模型，而是：</p> <ul> <li>你有没有可执行规则</li> <li>你有没有自动化反馈</li> <li>你有没有把失败沉淀成下一次的确定性优势</li> </ul> <p>我认为，当前AI模型的结果输出说到底还是概率模型，而当前市面上的大部分模型已经具备了不俗的能力足以解决我们的开发问题，而怎样让不够好的概率模型也能生成比肩行业顶尖的模型结果就是Harness工程的实际作用。</p> <h2 id="参考文章"><a href="#%e5%8f%82%e8%80%83%e6%96%87%e7%ab%a0" class="header-anchor"></a>参考文章 </h2><ul> <li>OpenAI: <a class="link" href="https://openai.com/index/harness-engineering/" target="_blank" rel="noopener" >Harness engineering: leveraging Codex in an agent-first world</a></li> <li>Anthropic: <a class="link" href="https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents" target="_blank" rel="noopener" >Effective harnesses for long-running agents</a></li> <li>Anthropic: <a class="link" href="https://www.anthropic.com/engineering/harness-design-long-running-apps" target="_blank" rel="noopener" >Harness design for long-running application development</a></li> <li>LangChain: <a class="link" href="https://www.langchain.com/blog/the-anatomy-of-an-agent-harness" target="_blank" rel="noopener" >The Anatomy of an Agent Harness</a></li> <li>Mitchell Hashimoto: <a class="link" href="https://mitchellh.com/writing/my-ai-adoption-journey" target="_blank" rel="noopener" >My AI Adoption Journey</a></li> <li>Martin Fowler: <a class="link" href="https://martinfowler.com/articles/exploring-gen-ai/harness-engineering-memo.html" target="_blank" rel="noopener" >Harness Engineering - first thoughts</a></li> <li>Martin Fowler: <a class="link" href="https://martinfowler.com/articles/harness-engineering.html" target="_blank" rel="noopener" >Harness engineering for coding agent users</a></li> </ul>