开源项目第176期：Better Harness — 不审查 diff，审查工作流本身，给 AI 编程 Agent 的五维评估框架

引言

"你的 AI 编程 Agent 生成代码很快，但你的工作流是瓶颈。"

这是「每日一个开源项目」系列的第 176 篇 。今天的项目是 Better Harness ------ QoderAI 出品的开源评估工具，分析 AI 编程 Agent 的工作流，而不只是看它生成的代码。

大多数对 AI 编程 Agent 的评估集中在"生成的代码质量"上：测试通过率、漏洞密度、功能正确性。But 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 等 harness 概念会有帮助
对软件工程的质量保障流程（CI/CD、测试、代码审查）有基本认知

项目背景

问题：Agent 改代码很快，但工作流是弱点

AI 编程 Agent 引入了一个新的失败模式：速度。Agent 能在几分钟内完成以前需要几小时的工作，但这个速度也容易绕过那些本来有价值的慢环节------仔细理解需求、在已有路径上工作、验证变更、通过人工审查。

Better Harness 识别出五种常见工作流漏洞：

漏洞类型	表现
目标模糊	Agent 不清楚"完成"是什么样子，反复改错方向
临时执行	每次从头摸索，没有可复用的执行路径
未经验证的变更	代码改完了，但没有证据证明改动有效
绕过检查	AI 速度使质量检查变成了可选项
经验丢失	这次任务的教训不会沉淀到下次任务

这五种问题在代码 diff 里通常不可见。代码通过了 review，但工作流层面的问题仍然存在，会在下次任务里以同样的方式出现。

QoderAI 和 Qoder

Better Harness 由 QoderAI 开发，他们自己也做一个桌面 AI 编程 Agent------Qoder，Better Harness 作为原生功能内置在 Qoder 里。开源的 Better Harness 则以插件形式支持其他主流 Agent。

项目数据

⭐ GitHub Stars: 1,500+
🍴 Forks: 123+
📄 许可证: MIT
运行环境: Node.js 22.20.0--25.0.0

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

Better Harness 的评估模型建立在一个框架上：有效的 Agent 工作流需要两类信号共同工作。

markdown 复制代码

工作开始前                    工作进行中/完成后
─────────────                ──────────────────
前馈引导（Feedforward）       反馈传感器（Feedback）

AGENTS.md                    Linters
规范文档（specs）             测试套件
Skills（可复用步骤）          Hooks（事件触发）
验收标准                      评估 Agent
                             诊断工具

前馈引导：在 Agent 动手之前就提供方向------AGENTS.md 告诉 Agent 规则和目标，specs 定义任务范围，Skills 提供经过验证的执行路径，验收标准定义"完成"是什么样。

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

一个工作流健康的核心指标：这两侧都在工作，而且工作结果有证据记录。

五个维度详解

维度一：任务理解（Task Understanding）

核心问题：Agent 知道目标是什么，知道"完成"是什么样子吗？

评估内容：

AGENTS.md 是否存在并包含有效的规则和目标定义
是否有规范文档（specs）定义任务范围
是否有明确的验收标准，让 Agent 知道何时停止
Agent 是否能识别项目起点和适合的变更粒度

常见问题：目标描述模糊（"改进登录流程"而不是"给错误状态添加具体错误信息"），Agent 不知道什么时候算"完成"，反复过度修改或反复在错误方向上迭代。

维度二：受控执行（Controlled Execution）

核心问题：Agent 工作在有支撑的、可复用的路径上吗？

评估内容：

Skills 的配置情况：是否有可复用的 SDLC 执行步骤
MCP 工具的可用性和边界设置
沙箱边界：Agent 的权限范围是否合理受限
Agent 是否在已知有效的路径上工作，而不是每次从头摸索

常见问题：每次任务都重新发明执行流程；Agent 有过多权限，做了超出任务范围的修改；没有可复用的步骤，相似任务的质量差异很大。

维度三：变更验证（Change Validation）

核心问题：有证据证明改动实际生效了吗？

评估内容：

测试是否在变更后实际运行（不只是"存在测试"）
lint 检查是否在变更后实际执行
Hooks 是否捕获了验证信号
验证失败后是否有重新验证的记录
诊断工具是否实际被使用

关键区别：Better Harness 区分"配置了测试"和"测试被执行了"。一个项目可以有完整的测试套件，但如果没有证据显示 Agent 在变更后运行了测试，这个维度就不能得分。

维度四：可靠交付（Reliable Delivery）

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

评估内容：

是否有任务验收证据（不只是"代码改完了"）
高风险操作是否有人工审批路径
是否有回滚机制
CI/CD 管道是否在 Agent 的工作流里
人工 review 是否实际发生

核心担忧：Agent 可以在没有任何人察觉的情况下完成大量修改。可靠交付评估的是：这些修改在交付前经过了哪些验证关卡。

维度五：经验沉淀（Learning Capture）

核心问题：这次任务的教训会影响到下次任务吗？

评估内容：

重复出现的问题是否沉淀为可复用的 Rules 或 Skills
Loop Discovery 是否在工作（识别模式并生成建议）
Memory 系统是否在使用
类似任务是否在复用已有经验，还是每次从零开始

一个信号：Better Harness 会标记"长时间会话"（超过 45 分钟）供人工审查------这通常意味着 Agent 在做大量摸索，而这些经验应该被沉淀下来以避免重复。

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

Better Harness 不用一个 Agent 做所有分析，而是用三个独立的只读子 Agent 并行收集不同类型的证据，最后由主 Agent 做统一分析。

yaml 复制代码

三个独立子 Agent（并行）
├── Agent 1: 定制化资产分析
│       → Rules、Skills、Hooks、配置的完整性
│
├── Agent 2: 真实任务会话分析
│       → Agent 实际做了什么，如何执行
│
└── Agent 3: 项目工程基础分析
        → 项目结构是否支撑 Agent 工作流

        ↓（独立收集完成后）

主 Lead Agent：统一分析 + 生成报告

为什么要保持独立：让三个子 Agent 独立工作，防止一类证据的结论影响另一类的解读。如果 Agent 1 发现 Skills 配置完整，这不应该影响 Agent 2 对实际会话记录的分析------后者只看执行证据，不看配置。

缺失证据的处理：未观察到的行为不会被推断。如果没有测试执行记录，变更验证这一维度就是未知状态，不会因为"项目里有测试文件"而假设"测试被运行了"。

报告结构

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

report.html：自包含的可视化报告（独立浏览器打开）
report.md：Markdown 格式，方便版本控制和团队分享
findings.json：结构化数据，方便程序处理

报告内容

五维概览：每个维度的评分条形图 + 相关发现数量

范围快照：当前配置的资产清点------Rules 数量、Skills 数量、自定义 Agents、MCP 工具、Memories、Hooks

优先级发现：每条发现包含：

优先级（High / Medium / Low）
所属维度
原因（具体的配置缺口）
预期输出（修复后达到的效果）
修复说明（可编辑的预填充提示词，以 /harness 开头）

会话观察：从分析的会话中提取的典型模式，超过 45 分钟的长会话单独标出

历史趋势：多次运行的结果对比，显示各维度随时间的变化

刻意保守的评分

Better Harness 在评分上有一个明确限制：

"配置了某个资产，只能证明机制存在；只有与任务链接的证据，才能证明它被实际使用了。"

这意味着：一个项目配置了完整的 Skills，但如果没有实际使用记录，受控执行这个维度不会因此得满分。通过当前检查，只能证明干预被执行了；只有比较后续结果，才能证明工作流改善了。 历史视图展示的是记录的趋势，不是因果改善的证明。

安装与使用

在 Claude Code 里安装

bash 复制代码

/plugin marketplace add QoderAI/better-harness

其他平台

平台	安装方式
Codex Desktop	Settings > Plugins > Add from Marketplace
Codex CLI	`codex plugin marketplace add [repo URL]`
GitHub Copilot	`copilot plugin marketplace add QoderAI/better-harness`
Qwen Code	`qwen extensions install QoderAI/better-harness`
Cursor	clone 仓库到本地，source-local 安装
Qoder	原生内置，无需安装

运行分析

安装完成后，在任意支持的 Agent 里：

kotlin 复制代码

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

输出自包含的 report.html + report.md + findings.json。

修复工作流

Better Harness 不直接修改任何东西，只识别问题并提供修复起点：

bash 复制代码

发现一个高优先级问题 → 点击 "Plan a fix"
    ↓
打开修复详情：
  - 原因：当前配置的具体缺口
  - 预期输出：修复后达到的效果
  - 修复指令：预填充的提示词（可编辑）
    ↓
点击 "Start Fix" → 启动 Quest 任务
    ↓
Agent 在可检查、可回滚的 Quest 任务里执行修复
    ↓
重新运行 /better-harness → 确认工作流实际改善

修复结果可以进一步沉淀为 Rules、Skills 和 Memories，让后续任务直接受益。

项目地址与资源

🌟 GitHub : QoderAI/better-harness
📖 文档 : docs.qoder.com/user-guide/...

总结

Better Harness 解决的是一个元层面的问题：AI 编程 Agent 的输出质量取决于围绕它的工作流，而不只取决于模型能力。一个 Claude Sonnet 在有完整 AGENTS.md、明确验收标准、运行后自动测试、经验沉淀为 Skills 的工作流里，比同一个 Claude Sonnet 在没有这些的随意工作流里，输出质量差异很大。

五维框架的价值在于把"工作流健康度"变成了可测量的东西：不是"感觉工作流不太好"，而是"变更验证这个维度评分低，因为没有找到测试执行的证据记录"。优先级排序让你知道先修什么，修复方案让你知道怎么修，历史趋势让你确认修复实际有效。

"刻意保守"的评分策略是这个工具最值得信任的地方。它不从"项目里有测试文件"推断"测试被运行了"，也不从"历史视图显示改善"推断"是这次修复导致的改善"。这种诚实让工具的输出可以被信任，而不是被质疑。

探索 PrimeSkills ------ 精选 AI Agent 与技能的市场，每一个都经过真实企业工作流验证，去掉浮夸，留下真正有用的。

欢迎访问我的个人主页，发现更多有价值的见解和有趣的产品。