引言
“你的 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 工作流需要两类信号共同工作。
工作开始前 工作进行中/完成后 ───────────── ────────────────── 前馈引导（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 做统一分析。
三个独立子 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 里安装
/plugin marketplaceaddQoderAI/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 里：
/better-harness analyze this project's AI coding workflow and generate an evidence-backed report输出自包含的report.html+report.md+findings.json。
修复工作流
Better Harness 不直接修改任何东西，只识别问题并提供修复起点：
发现一个高优先级问题 → 点击 "Plan a fix" ↓ 打开修复详情： - 原因：当前配置的具体缺口 - 预期输出：修复后达到的效果 - 修复指令：预填充的提示词（可编辑） ↓ 点击 "Start Fix" → 启动 Quest 任务 ↓ Agent 在可检查、可回滚的 Quest 任务里执行修复 ↓ 重新运行 /better-harness → 确认工作流实际改善修复结果可以进一步沉淀为 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 Sonnet 在没有这些的随意工作流里，输出质量差异很大。
五维框架的价值在于把"工作流健康度"变成了可测量的东西：不是"感觉工作流不太好"，而是"变更验证这个维度评分低，因为没有找到测试执行的证据记录"。优先级排序让你知道先修什么，修复方案让你知道怎么修，历史趋势让你确认修复实际有效。
“刻意保守"的评分策略是这个工具最值得信任的地方。它不从"项目里有测试文件"推断"测试被运行了”，也不从"历史视图显示改善"推断"是这次修复导致的改善"。这种诚实让工具的输出可以被信任，而不是被质疑。
探索 PrimeSkills —— 精选 AI Agent 与技能的市场，每一个都经过真实企业工作流验证，去掉浮夸，留下真正有用的。
欢迎访问我的个人主页，发现更多有价值的见解和有趣的产品。
