从工作流而非代码评估编程 Agent

“你的 AI 编码 Agent 生成代码的速度很快。真正的瓶颈，是你的工作流。”

这是「每天一个开源项目」系列的第 143 篇文章。今天介绍的项目是 Better Harness——QoderAI 开源的一款评估工具。它分析的是 AI 编码 Agent 周围的工作流，而不只是 Agent 产出的代码。

大多数 AI 编码 Agent 评估都聚焦于输出质量：测试通过率、缺陷密度、功能正确性。Better Harness 则持有不同的观点：Agent 失败并不一定是因为模型能力不足，更可能是因为周围的工作流存在缺口。目标模糊、缺少可复用的执行路径、变更未经验证、绕过质量检查、每次会话结束后经验随之消失——这些问题不会体现在 diff 中，只有审查工作流本身时才会暴露出来。

Better Harness 会收集项目和会话证据，从五个维度评估工作流的健康状况，并输出按优先级排序的问题。每个问题都附有范围明确、可以直接执行的修复方案。

1,500 个 Star。采用 MIT 许可证。支持 Claude Code、Codex、GitHub Copilot、Cursor 和 Qwen Code。

• Better Harness 的核心模型：前馈指引与反馈传感器
• 五个维度分别评估什么，以及哪些内容可以作为证据
• 系统架构：三个相互独立的证据 Agent 并行运行
• 报告结构：问题、修复方案与历史趋势
• 为什么它“刻意保持诚实”：绝不根据配置是否存在来推断实际使用情况
• 如何在 Claude Code 和 Codex 中安装与使用

阅读本文前，你可以具备以下背景：

• 使用过 Claude Code、Codex、Cursor 或类似的 AI 编码工具
• 熟悉 AGENTS.md、Hooks 和 Skills 会有所帮助，但不是必需条件
• 对软件质量实践有基本了解，例如 CI/CD、测试和代码审查

问题所在：Agent 飞速前进，工作流依然薄弱

AI 编码 Agent 带来了一种新的失败模式：速度。过去需要数小时完成的工作，现在 Agent 几分钟就能做完——但这种速度也会跳过那些看似缓慢、实际上很有价值的步骤：认真理解目标、沿用经过验证的路径开展工作、验证变更，以及通过人工审查。

Better Harness 识别出五种常见的工作流失败模式：

1. 任务理解不充分
2. 执行过程缺乏控制
3. 变更没有得到验证
4. 交付过程不可靠
5. 经验与教训没有沉淀

这五类问题通常无法从代码 diff 中看出来。代码顺利通过了审查，但工作流中的问题依然存在，并会在下一项任务中再次发生。

Better Harness 由 QoderAI 开发。QoderAI 还推出了一款名为 Qoder 的桌面 AI 编码 Agent。Better Harness 已原生集成到 Qoder 中，其开源版本则可以作为插件运行在其他主流 Agent 中。

⭐ GitHub Stars：1,500+

运行环境：Node.js 22.20.0–25.0.0

核心概念：前馈信号 + 反馈信号

Better Harness 的评估模型建立在一个框架之上：高效的 Agent 工作流，需要两类信号协同发挥作用。

Before work starts                After / during work
──────────────────                ──────────────────
Feedforward guides                Feedback sensors

AGENTS.md                         Linters
Spec documents                    Test suites
Skills (reusable steps)           Hooks (event-triggered)
Acceptance criteria               Evaluation agents
                                  Diagnostics

前馈指引会在 Agent 行动之前为其指明方向——AGENTS.md 负责建立规则和目标，spec 文档定义任务范围，Skills 提供经过验证的执行路径，验收标准则定义什么才算“完成”。

反馈传感器会在 Agent 行动之后观察结果——linters 检查代码规范，测试套件验证功能，Hooks 在事件触发时捕获信号，评估 Agent 则对输出质量进行评分。

健康工作流的核心指标是：前馈与反馈两端都在正常运作，并且它们的运行结果留下了可以检查的证据。

维度一：任务理解

核心问题：Agent 是否知道目标是什么，以及做到什么程度才算“完成”？

• 是否存在 AGENTS.md，以及其中是否包含有效的规则和目标定义
• spec 文档是否定义了任务范围
• 是否有明确的验收标准告诉 Agent 何时应该停止
• Agent 是否能够识别项目的切入点，并采用合适的变更粒度

常见失败：模糊的目标描述，例如“改进登录流程”，而不是“针对每一种错误状态添加对应的错误提示”，会让 Agent 找不到明确的停止点，进而导致过度设计或反复调整方向。

维度二：受控执行

核心问题：Agent 是否沿着受支持、可重复的路径开展工作？

• Skills 配置：是否存在可复用的软件开发生命周期执行步骤
• MCP 工具是否可用，以及边界设置是否合理
• Sandbox 边界：Agent 的权限范围是否得到恰当限制
• Agent 是否使用经过验证的路径，而不是每次都临场发挥

常见失败：每项任务都重新设计一套执行过程；权限过大的 Agent 做出超出任务范围的变更；缺少可复用的步骤，导致相似任务的交付质量不一致。

维度三：变更验证

核心问题：是否有证据能够证明变更确实有效？

• 变更后是否实际运行了测试，而不只是“项目中存在测试”
• 变更后是否实际运行了 lint 检查
• Hooks 是否捕获了验证信号
• 验证失败后是否重新进行了验证
• 是否实际使用了诊断工具

关键区别：Better Harness 会区分“已经配置测试”和“实际执行了测试”。一个项目可以拥有完整的测试套件，但如果没有证据表明 Agent 在变更后运行过测试，这个维度就不会因此获得分数。

维度四：可靠交付

核心问题：AI 带来的速度是否绕过了质量关卡？

• 任务验收是否具有可验证的证据，而不只是声称“代码已经完成”
• 高风险操作是否设置了人工审批路径
• 是否存在回滚机制
• CI/CD pipeline 是否属于 Agent 工作流的一部分
• 是否实际进行了人工审查

核心关注点：Agent 可以在无人察觉的情况下做出大范围修改。可靠交付评估的是，这些修改在交付之前通过了哪些验证关卡。

维度五：经验沉淀

核心问题：这项任务中的经验教训，是否能够改善下一项任务？

• 是否将反复出现的问题提炼为可复用的 Rules 或 Skills
• Loop Discovery 是否正常工作，即通过模式识别生成建议
• 是否正在使用 Memory 系统
• 相似任务是否会复用已有经验，而不是每次都从零开始

其中一个信号是：Better Harness 会标记持续时间超过 45 分钟的“长会话”，交由人工审查。这类会话通常意味着 Agent 在探索上投入了大量精力，而这些探索结果应该被沉淀下来，避免以后重复劳动。

分析架构：三个相互独立的证据 Agent

Better Harness 不会使用单一 Agent 完成全部分析。三个相互独立、只有读取权限的子 Agent 会并行收集不同类别的证据。只有在独立收集全部完成后，主 Agent 才会汇总分析结果。

Three independent sub-agents (parallel)
├── Agent 1: Customization asset analysis
│       → Completeness of Rules, Skills, Hooks, and configs
│
├── Agent 2: Real task session analysis
│       → What the agent actually did and how it performed
│
└── Agent 3: Project engineering foundation analysis
        → Whether project structure supports the agent workflow

        ↓ (after independent collection)

Lead Agent: Unified analysis + report generation

为什么要让它们保持独立：分别运行三个子 Agent，可以防止某一类证据的结论影响另一类证据的解读。如果 Agent 1 发现项目拥有完整的 Skills 配置，这不应该影响 Agent 2 解读真实会话记录的方式——Agent 2 只关注执行证据。

缺失证据的处理方式：Better Harness 绝不会推断未观察到的行为。没有测试执行记录，就意味着变更验证情况未知，而不会仅仅因为项目中存在测试文件，就假设 Agent 运行过测试。

运行分析后会生成三个文件：

• report.html：自包含的可视化报告，可以直接在浏览器中打开
• report.md：Markdown 格式的报告，便于纳入版本控制并在团队中共享
• findings.json：用于程序化处理的结构化数据

报告包含哪些内容

• 五维概览：每个维度对应一个评分条形图，并显示相关问题的数量
• 范围快照：当前已配置的资产清单，包括 Rules 数量、Skills 数量、自定义 Agents、MCP 工具、Memories 和 Hooks
• 按优先级排序的问题：每个问题都包括：
  • 优先级：High / Medium / Low
  • 原因：当前配置中存在的具体缺口
  • 预期输出：成功修复后应该达到的效果
  • 修复说明：一个可以编辑、以 /harness 开头的预填充 prompt
• 会话观察：从已分析会话中提取的代表性模式；持续时间超过 45 分钟的会话会被单独标记
• 历史趋势：比较多次运行的结果，展示各个维度随时间发生的变化

刻意保守的评分方式

Better Harness 有一条明确的评分约束：

“已配置的资产只能证明某种机制存在；只有与具体任务关联的证据，才能证明它确实被使用过。”

即使项目拥有完整的 Skills 配置，如果没有实际使用的证据，受控执行维度也不会获得满分。当前检查通过，只能证明干预措施得到过执行；只有后续可比较的结果，才能证明整个闭环确实有所改善。历史视图展示的是已记录的趋势，而不是能够证明改进存在因果关系的证据。

安装与使用

/plugin marketplace add QoderAI/better-harness

安装完成后，可以在任何受支持的 Agent 中运行：

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

该命令会输出自包含的 report.html、report.md 和 findings.json。

Better Harness 绝不会直接修改任何内容——它负责识别缺口，并提供修复工作的起点：

High-priority finding → click "Plan a fix"
    ↓
Fix detail opens:
  - Cause: the specific config gap
  - Expected Output: what a fix achieves
  - Fix instructions: editable pre-filled prompt
    ↓
Click "Start Fix" → launches as a Quest task
    ↓
Agent executes fix in an inspectable, reversible Quest task
    ↓
Re-run /better-harness → confirm the loop actually improved

修复结果还可以进一步提炼为 Rules、Skills 和 Memories，让后续任务直接从中受益。

🌟 GitHub：QoderAI/better-harness

📖 文档：docs.qoder.com/user-guide/knowledge-engine/better-harness

Better Harness 解决的是一个元层面的问题：AI 编码 Agent 的输出质量，取决于周围的工作流，而不只是模型自身的能力。同一个 Claude Sonnet，如果运行在一个拥有完整 AGENTS.md、清晰验收标准、变更后测试流程，并能把经验提炼为 Skills 的工作流中，其产出会显著优于缺少这些机制的工作流。

这套五维框架让“工作流健康度”变得可衡量——不再只是“感觉工作流有点问题”，而是可以明确指出：“由于没有发现测试执行记录，变更验证维度的得分较低。”优先级排序告诉你应该先修复什么，修复方案告诉你应该怎么做，历史趋势则用于确认修复是否真的有效。

刻意保守的评分方式，正是这款工具值得信任的原因。它不会根据“存在测试文件”推断“已经运行测试”，也不会因为历史分数有所提高，就声称“修复措施导致了改进”。正是这种诚实，让用户可以直接根据输出采取行动，而不用反复质疑结论是否可靠。

如果你正在使用 Claude Code、Codex 或 Cursor，并且偶尔觉得会话效率低下——例如目标花了太长时间才澄清、变更意外破坏了功能、同样的问题反复出现——那么 /better-harness 可以帮你找出工作闭环中真正出问题的环节。

探索 PrimeSkills——一个精选 AI Agents 和 Skills 的 marketplace。每一项都经过真实企业工作流验证，剔除炒作，只保留真正有效的能力。

欢迎访问我的主页，获取更多实用洞察和有趣产品。

如果需要采取进一步行动，你可以考虑屏蔽此人和／或举报滥用行为。