> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Better Harness
> Qoder 内置工程专家，帮助你持续进化——由 Agent 审视项目的 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. 点击 **重新生成** 可发起新一轮扫描；点击 **查看详情** 进入完整报告页。
Better Harness 不会自动修改代码。所有修复都以 Quest 任务的形式呈现，可以审阅、可以回滚——Better Harness 只负责指出问题并准备好提示词。
## 五个维度详解
确认 Agent 是否理解你的目标、相关上下文和改动范围，确保任务方向明确、边界清楚。
确认 Agent 是否能按项目说明启动和操作项目，并在明确的权限和操作边界内完成任务。
确认 Agent 是否会针对本次改动运行相关检查；如果检查失败，是否能修复后再次验证。
确认任务结果是否有可核验的证据支持验收；遇到高风险操作时，是否有审批、回滚或恢复办法。
确认反复出现的问题是否被沉淀为可查找、可复用、可维护的规则、流程或工具，并在后续类似任务中验证效果。
## 创建修复方案
点击优化点卡片上的 **创建修复方案** 后，会弹出 **问题详情** 对话框，包含以下信息:
* **优先级** 标记（高/中/低）
* **问题标题** 与所属维度（如「修复计划 · 任务理解」）
* **原因**——说明为什么当前配置存在该短板
* **预期输出**——修复完成后的预期结果
* **修复说明**——一段可编辑的提示词，默认以 `/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`，看看下一步最值得补齐什么。