00 · STAR 总览：Better Harness 是什么

5 分钟读懂 QoderAI/better-harness——一个给"AI 编码代理的工作方式"做体检的开源系统，不评审代码，评审产生代码的那个工作循环。

一图速览

S — Situation：AI 写代码越来越快，工作流成了短板

AI 编码代理改代码的速度，已经远超团队工作流的承载能力。项目 README 列出了五个典型症状：

• 目标模糊——代理自信地解决了错误的问题
• 路径即兴——工作过程不可复现
• "能跑"但没证据——验证不完整或缺失
• 速度压过安全——评审和交付检查被绕过
• 经验丢失——同样的坑下个任务再踩一遍

关键洞察：只 review 最终 diff 看不到这些系统级问题。diff 只回答"改了什么"，回答不了代理是怎么理解任务、怎么执行、怎么验证、怎么交付的。

T — Task：给"产生 diff 的那个循环"做体检

不评估代码质量，评估围绕代码的工作循环是否健康；并且每条结论必须有证据支撑——没观察到的行为就明说"没观察到"，不编分数。

项目的自我定位写在 roadmap 里：“证据与控制面（evidence and control plane），不是又一个编码代理运行时”。宿主负责跑模型，Better Harness 负责回答"这个项目的 harness 够不够好、哪里该修、修了之后真的变好了吗"。

A — Action：三层开源资产

第一层 · 评估模型——五个维度回答五个问题：

配套两个防作弊机制：证据上限制（静态配置最多撑到 74 分，演练过最多 94 分，只有可比的后续改善结果能到 100）和修复/有效性分离（修完只更新 Repair Progress，维度分数要等下一个可比任务才允许变动）。

第二层 · 工程实践——六个判据域：会话证据、项目 harness、代理资产定制、bootstrap 规格、循环工程、运行时契约。每条评分判据都有出处和发射条件，连"根 AGENTS.md 超过 200 行算 finding"这种细节都有明确规则。

第三层 · 可运行实现——/better-harness 一条命令跑通五步流水线：冻结证据包 → 三个互相隔离的只读证据代理 → 主代理单点裁决 → 八道质量闸门 → 校验渲染成自包含 HTML 或原生 Canvas 报告。

R — Result：可复核的体检报告，和一套行业稀缺的诚实标准

• 一份有边界的报告：五维概览 + 按严重度（High/Medium/Low）排序的 findings——每条带证据引用、影响、aiFixPrompt 修复入口、预期产物与验收检查——外加证据简报和显式的未判定清单。
• 每条 finding 可直接行动：aiFixPrompt 是机器可读的修复回调契约（带 revision 控制与拓扑绑定），修完由独立的只读代理复核为 verified / partial / blocked。
• 纵向诚实：多次运行的趋势视图只声明"记录"，README 明确注明"不是因果证明"。
• 十宿主覆盖：同一套判据，Qoder/Cursor 出原生 Canvas，其余八家出自包含 HTML + Markdown + JSON 报告。

谁该读这个系列

面试表述

• Q：Better Harness 到底评的是什么？ 不评代码质量，评的是"产生代码的那个工作循环"——代理怎么理解任务、怎么执行、怎么验证、怎么交付。只看最终 diff 看不到这些系统级问题，所以需要一套独立的证据驱动评审。
• Q：它和普通的 lint/CI 有什么区别？ lint 评审代码本身，Better Harness 评审工作流程。关键差异在证据上限制：装了一堆 hooks 在 lint 里是加分项，在这里静态配置最多撑到 74 分——因为"配置存在"和"机制被使用"是两件事。
• Q：三层资产各自解决什么？ 评估模型定义"怎么判分"，工程实践定义"怎么检查"，可运行实现把前两层变成一条命令跑通的流水线。判据与判定分离，是防止"自己查自己打分"的结构保障。

记忆点：Better Harness 的本质是——不看你改了什么代码，看你产生代码的过程有没有证据；没证据的地方，诚实地写着"没观察到"。