Better Harness

​

什么是 Agent Harness

现在的 Coding Agent 已经能读需求、改代码、跑测试，甚至提交 Pull Request。但”能做很多事”，不代表”能把事情做好”。Agent 通常会在”理解任务—执行操作—查看结果—继续调整”之间不断循环，这就是 Agent Loop。 真正可靠的 Loop，不只是让 Agent 一直行动，而是让它知道目标是什么、哪些地方不能动、怎么判断结果对不对，以及失败后该怎么办。否则，它可能改了很多代码、跑了很多测试，最后却无法证明任务真的完成了。 这就是 Loop Engineering 和 Harness Engineering 要解决的问题：为 Agent 准备好项目上下文、相关的开发工具、验证方式方法，以及明确的安全范围，让每一次 Loop 都更接近可靠交付。 在 Qoder 中，Loop 工程涵盖以下资产类型：Rules、Skills、Hooks、MCP 配置、Custom Agents、Plugins、Session Insights。

​

为什么需要 Better Harness

把 Loop 工程做到位并不轻松。本该写下来的规则只留在某个人的脑子里、复盘发现的问题没有沉淀成规则、团队约定散落在群聊里、AGENTS.md 里空空如也。大部分团队既没有充分的时间、也缺少清晰的标准，来把这件事系统地做好。 基于 Qoder 内部实践，以及社区在 Coding Agent、Loop 工程和软件研发等领域积累的最佳实践，我们推出了 Better Harness。 在新版 Qoder 中，你可以进入 Better Harness，通过可视化界面启动分析并修复问题；也可以直接运行 /better-harness。它会分析当前 Agent 执行任务的过程中，识别其中缺失或薄弱的关键要素，并帮助你明确下一步需要补齐和优化的内容。

​

Better Harness 如何工作

Better Harness 检查的不是某一次回答写得好不好，而是支撑 Coding Agent 完成任务的整套 Harness：目标和上下文是否清晰、项目是否容易运行、权限是否可控、验证是否有效、交付是否安全，以及团队和 Agent 能否从任务中持续学习。 其主要的分析过程：

1. 画出当前 Harness——识别目标、上下文、执行入口、反馈、交付和学习机制。
2. 找到断点——说明哪一环缺少机制、接入、实际执行或结果证据。
3. 选择最小改进载体——把问题交给最合适的 Rule、Skill、Hook、脚本、自动化或人工门禁。
4. 修复并复验——限定修复范围，执行相关验证，再次运行 /better-harness 检查 Loop 是否真的改善。

分析时，Better Harness 会先由主分析流程收集原始数据，再交给三个相互独立的只读子 Agent 分别解读三类证据：Agent 自定义资产（Rules、Skills、Hooks 等配置是否完整可用）、真实的任务会话记录（Agent 在实际任务中做了什么、结果如何），以及项目的软件工程基础。三类证据独立收集、再统一汇总，避免结论互相污染。

​

Better Harness 评估什么

Better Harness 会扫描你选定的项目，并从五个维度输出一份分析报告：

• 任务理解——Agent 是否能识别项目是什么、任务应当从哪里开始、改动范围应控制在多大。
• 可控执行——Agent 能否按项目说明启动项目、在明确的权限内完成任务，并守住操作边界。
• 改动验证——每次改动是否经过 lint、测试等相关检查；如果检查失败，是否能修复后再次验证。
• 可靠交付——任务结果是否有可核验的证据支撑验收；高风险操作是否有审批、回滚或恢复方案。
• 经验沉淀——反复出现的问题是否已经沉淀为可查找、可复用的规则或 Skill，并在后续同类任务中被真正用上。

每个维度都会以条形图展示分数，并标注相关优化点数量。报告同时展示项目当前的 Scope 概览（Rules、Skills、Custom Agents、MCPs、Memories、Hooks）。对任意一条优化建议，都可以通过 创建修复方案 一键交给 Agent 处理——修复任务会走 Quest 流水线，由 Agent 先出方案，你像审阅普通 Quest 任务一样确认变更即可。

​

如何使用

1. 在左侧栏底部点击 Better Harness（与「知识中心」「插件市场」并列）。
2. 顶部以 tab 形式展示你的项目（如 air、maERP、condo、twenty、flow 等），点击切换；需要新增项目时点击 + 添加项目。
3. 首次对某个项目发起扫描时，你会看到「正在理解项目结构…」等状态提示——Agent 会读取模块结构、历史会话、已有 Skills 等信息。扫描期间可在 Quest 列表查看进度。
4. 报告生成后，概览页展示五个维度的条形图分数、优化点数量，以及 Scope 统计（Rules、Skills、Custom Agents、MCPs、Memories、Hooks）。
5. 概览页下方列出全部优化点卡片，可通过 全部优化点 / 已处理 / 待处理 tab 筛选。每张卡片标注优先级（高/中/低）、标题与所属维度。
6. 在卡片上点击 创建修复方案 可启动修复流程；对不需要处理的建议点击 忽略。
7. 点击 重新生成 可发起新一轮扫描；点击 查看详情 进入完整报告页。

​

五个维度详解

​

创建修复方案

点击优化点卡片上的 创建修复方案 后，会弹出 问题详情 对话框，包含以下信息:

• 优先级 标记（高/中/低）
• 问题标题 与所属维度（如「修复计划 · 任务理解」）
• 原因——说明为什么当前配置存在该短板
• 预期输出——修复完成后的预期结果
• 修复说明——一段可编辑的提示词，默认以 /harness 开头并预填修复方案。你可以直接使用，也可以修改后再确认。

对话框底部有模型选择器和 开始修复 按钮。点击后会用修复说明创建一个新的 Quest，可在 Quest 列表继续跟进。 由于所有修复都走 Quest 流水线，Agent 的每一步动作都可审可回——不会有任何看不见的改动落入仓库。 对于识别出的改进机会，用户只需点击 创建修复方案，即可由 AI 生成并执行相应的修复方案。更重要的是，这些修复不仅服务于当前任务，还可以进一步沉淀为 Rules、Skills、Memories 等可复用的用户资产，持续增强用户自己的 Agent Harness。

​

查看详情

点击概览页右上角的 查看详情 进入完整报告页。报告包含以下模块：

• Agent 工作流——以流水线可视化形式呈现五个维度的分数节点。
• 项目用量——每日活动热力图、已分析会话数、估算活跃分钟数、Skill 使用次数、最常使用的 Skills。
• 优先优化项——所有优化点卡片，可点击 规划 AI 修复 或 查看详情 展开单条建议的详细信息。
• Agent 自定义——已发现的 Loop 工程资产（Hooks、MCP、Plugins）及覆盖范围（Rules、Skills、Session Insights、Custom Agents 是否已配置）。
• 证据与方法——触样可信度、来源缺口和交付结果概况，说明报告结论所依据的数据量。
• 长会话待复核——标记出超过 45 分钟的会话供人工检查。
• 会话观察——从已分析会话中提炼的代表性观察条目，用于指引后续调查与优先排列。

​

重新生成报告

报告卡片上会显示更新时间（24 小时制、当地时区）。随着项目演进，旧报告的参考价值会下降。点击 重新生成 即可发起新一轮扫描，新报告会替换原有报告。 推荐在下面情况下重新生成：

• 你按报告修复了一批 Loop 工程问题，想看看分数变化。
• 项目结构发生较大变化（新增模块、大范围重构）。
• 距离上次报告超过两三周。

​

让每一次 Harness 都沉淀为下一次的能力

一次 /better-harness 分析不是终点。它会帮助你发现断点、生成修复方案，并在修复后验证新的 Rule、Skill、Hook 或脚本是否真正进入 Agent 的工作循环。 更重要的是，值得复用的经验会被沉淀为个人或团队的 Agent 资产，让后续 Loop 更稳定、更高效、更可控。现在，你可以在 Qoder 中进入 Better Harness，或运行 /better-harness，看看下一步最值得补齐什么。