QoderAI/better-harness

Better Harness – AI 编码代理的教练

功能说明

• 当您使用 AI 驱动的编码助手（Claude Code、Codex、Cursor、GitHub Copilot、Qoder 等）时，Better Harness 会监控整个 工作循环：任务描述、代理执行的指令、变更的文件、运行的测试或 linter，以及最终的审查步骤。
• 它会收集主机所能提供的任何证据（项目文件、会话记录、CI 日志等），并针对五个维度评估工作流程：
  1. 任务理解 (Task Understanding) – 代理是否了解目标与“完成”的定义？
  2. 受控执行 (Controlled Execution) – 步骤是否可重复且受限于定义的工具？
  3. 变更验证 (Change Validation) – 是否有具体证据（测试、lint、诊断）证明变更有效？
  4. 可靠交付 (Reliable Delivery) – 是否仍应用了审查或 CI 等质量门控检查？
  5. 学习捕获 (Learning Capture) – 下一个任务是否能从中获益？
• 缺失的证据会被明确显示，而非猜测。若存在缺口，Better Harness 会建立 优先级发现，包含：
  • 缺口的影响，
  • 预期结果，
  • 范围明确的修复计划（简称“AI 修复”），以及
  • 团队可执行的验收检查。
• 输出为一个独立的 HTML 报告（附带 Markdown 与 JSON），可视化呈现发现、证据来源，以及提示词、工具调用与提交的时间轴。

如何使用

• 为您现有的编码代理安装插件（Claude Code、Codex Desktop/CLI、Qoder Desktop/CLI、Cursor、GitHub Copilot CLI 等）。README 提供了各主机特定的安装指令；没有单一的通用入口点。
• 在您想要分析的仓库中开启新会话，执行斜线指令：

  /better-harness analyze this project's AI coding workflow and generate an evidence‑backed report
  

• 主机将在特定文件夹中建立 report.html（以及 report.md 与 findings.json）。您可以开启 HTML 探索发现，或查看 Markdown 获取快速摘要。
• 独立的 CLI（better-harness plugin status …、better-harness doctor …）让您无需触碰主机 UI 即可检查所有支持主机上的插件安装状态。

重要性

• AI 编码代理能快速产生代码，但团队往往会忽略代码产生的 过程。目标可能模糊、步骤即兴、验证不完整且经验被遗忘。Better Harness 让这些隐藏部分可见，将模糊的摩擦转化为具体、可执行的改进项目。
• 通过保持证据明确，该工具避免了过于乐观的评分，并为团队提供了一条明确的路径，在利用 AI 速度的同时收紧开发流程。

适用对象

• 已经使用 AI 编码助手并希望审核与改进周边工作流程的团队。
• 寻求系统化方式来捕捉 AI 生成变更之质量与可重复性的工程经理。
• 希望获得 AI 代理在任务期间实际执行内容之可视化、证据支持报告的开发者。

项目健康度

• 以 npm 包 (@qoder-ai/better-harness) 发布，并采用 MIT 授权。
• 支持不断增加的主机列表（Claude Code、Codex、Qoder、Cursor、GitHub Copilot，以及 Qwen Code、Pi、Kimi Code、WorkBuddy、Grok）。
• 开发需 Node 22+，包含测试、打包脚本与预览服务器。
• 贡献指南鼓励新增主机适配器、评估模型或工作流程指引。

总结 Better Harness 是一个开源“教练”，它监控 AI 编码代理、记录其实际行为，并将证据缺口转化为具体、优先级排序的改进步骤。它帮助团队在保持 AI 速度的同时，重新获得对每个任务的控制力、可重复性与学习成果。