harness-review
对项目的 AI 编码工作流(Harness)做轻量体检:从任务理解、受控执行、变更验证、可靠交付、学习沉淀五个维度评估机制是否存在与真正被使用,产出带证据状态标注的报告(纯 Markdown,零运行时依赖)。触发:"体检一下工作流"、"评估 AI 工作流"、"harness review"。
SKILL.mdskills/harness-review/SKILL.md
GitHub工作流体检
概述
目的:回答"这个项目围绕 AI 的工作流是否健康"——不评审代码本身,评审的是让 AI 把任务从意图带到可靠交付的那套机制(规则、技能、验证、评审、沉淀)
功能:五维度 × 三检查项评估,每项结论强制标注证据状态(存在/已接入/被使用/有效果/缺失/未观察),产出按优先级排序的改进建议报告
使用场景:
- 用户说"体检一下这个项目的 AI 工作流"、"harness review"时
- 接手新项目,想快速了解其 AI 协作机制的成熟度时
- 本技能仓库自检:评估技能体系是否存在盲区
定位
体检请求 → harness-review(本 skill)→ 五维评估 → Markdown 体检报告
↓
发现"学习沉淀"缺口 → 建议走 loop-discovery
- 输入:目标项目路径 +(可选)近期任务上下文
- 输出:Markdown 体检报告(默认输出到对话;用户要求落盘时遵循 requirement-doc-store 规范)
- 边界:不评审代码质量(code-review 的事)、不评审设计文档(design-review 的事)、不评审单个 skill 质量(scenario-rehearsal 的事);评审对象是工作流机制整体
与官方 Better Harness 的关系:本 skill 是零依赖轻量版。若当前环境为 Qoder(内置 /better-harness),应先提示用户:官方版带 session 证据收集器和可视化报告,做深度体检更合适;用户仍要轻量版或环境不支持时,使用本 skill。
核心原则
- 配置了 ≠ 用了,用了 ≠ 有效:每条结论必须标注证据状态,禁止把"文件存在"说成"机制有效"
- 未观察就说未观察:拿不到证据的行为标
未观察,不编造分数、不脑补结论 - 发现必须可修复:每条发现要给出影响、最小修复动作和验证方式;纯粹的数量统计(如"有 40 个 skill")不构成发现
- 一次体检是基线:单次体检只能证明机制现状,"是否改善"需要下次可比体检对照
证据状态阶梯
所有维度的检查结论必须使用以下状态词标注:
| 状态 | 含义 | 能支撑的最强结论 |
|---|---|---|
存在 |
机制文件/配置存在 | "有这个机制" |
已接入 |
有明确触发路径能到达它(触发词、流程引用、hook) | "它可能被用上" |
被使用 |
有本次任务或历史痕迹证明它被真实使用过 | "它在工作" |
有效果 |
有前后可比的结果证明它改善了产出 | "它有价值" |
缺失 |
检查过,确认需要的机制不存在 | "这是缺口" |
未观察 |
现有观察手段无法判断 | 不下结论 |
不适用 |
检查过,确认该项目不需要此机制 | 排除该项 |
升级规则:状态只能靠证据升级。存在→已接入 需要找到真实触发路径;已接入→被使用 需要使用痕迹(git 历史中的产出文档、对话中的实际调用、报告文件);被使用→有效果 需要可比结果。
工作流
Step 0 环境检测 → Step 1 证据收集 → Step 2 五维评估 → Step 3 生成报告
Step 0:环境检测
- 若在 Qoder 环境:提示官方
/better-harness可做深度体检(含 session 证据 + Canvas 报告),询问用户是否改用官方版 - 其他环境或用户选择轻量版:继续
Step 1:证据收集
只收集静态可查 + 当前对话可观察的证据,不假装能读 session 日志:
| 证据域 | 收集内容 |
|---|---|
| 指导资产 | AGENTS.md / CLAUDE.md / rules/ / README、设计文档、需求目录结构 |
| 能力资产 | skills/ 目录清单及 description 质量、MCP 配置、脚本工具 |
| 验证机制 | 测试目录与运行方式、lint 配置、CI 配置、hooks |
| 交付机制 | 分支/PR 约定、发版脚本、回滚手段 |
| 沉淀机制 | .solutions/、记忆体系、知识库、经验文档 |
| 使用痕迹 | git log 中的产出文档(评审报告、推演报告等)、需求目录中的落盘产物 |
Step 2:五维评估
每个维度回答一个读者问题,含三个检查项,逐项给出证据状态 + 一句话结论:
| 维度 | 读者问题 | 三个检查项 |
|---|---|---|
| 任务理解 | AI 知道目标和"完成"的定义吗? | 意图与验收边界(有无需求文档/验收标准机制);权威上下文(有无规则/设计文档指路);范围边界(改动范围是否有约束机制) |
| 受控执行 | 工作跑在可复现的支持路径上吗? | 可复现启动(环境搭建/运行路径是否文档化);支持的操作(常用操作有无 skill/脚本/命令覆盖);权限边界(危险操作有无约束) |
| 变更验证 | 有证据证明变更真的有效吗? | 相关验证(改动能否映射到对应检查);失败诊断(失败时有无可用的诊断路径);修复后复验(有无"修完再跑一遍"的机制) |
| 可靠交付 | 速度有没有绕过质量关卡? | 交付验收(有无评审/合并关卡);高风险审批(危险动作有无事前确认);回滚恢复(出错后有无恢复路径) |
| 学习沉淀 | 下一个任务能从这次受益吗? | 机会识别(重复工作/踩坑有无被察觉的机制);沉淀路由(识别后有无合适的沉淀通道);持续有效(沉淀物有无保鲜/验证机制) |
评分规则(每维 0-100,受证据状态封顶):
| 该维最强证据状态 | 分数上限 |
|---|---|
| 缺失 / 未观察 | 59 |
| 存在 | 74 |
| 已接入 | 84 |
| 被使用 | 94 |
| 有效果 | 100 |
分数独立判断,不由发现数量推导。分数低不强制编造发现;发现必须来自被检查过的真实缺口。
Step 3:生成报告
# AI 工作流体检报告
> 项目:{路径} | 体检时间:{日期} | 模式:轻量(无 session 证据,相关行为标注"未观察")
## 五维总览
| 维度 | 分数 | 最强证据状态 | 一句话结论 |
|------|-----:|--------------|-----------|
| 任务理解 | .. | .. | .. |
| 受控执行 | .. | .. | .. |
| 变更验证 | .. | .. | .. |
| 可靠交付 | .. | .. | .. |
| 学习沉淀 | .. | .. | .. |
## 检查项明细
### {维度名}
| 检查项 | 证据状态 | 证据 | 结论 |
|--------|----------|------|------|
## 发现与建议(按优先级)
### 🔴/🟡/🟢 F-{N}:{标题}
- **证据**:{检查到的具体事实,含文件路径}
- **影响**:{这个缺口会导致什么}
- **修复**:{最小修复动作,指明归属(改哪个文件/建什么机制/走哪个 skill)}
- **验证**:{怎么确认修好了}
## 证据边界声明
以下内容本次无法观察,未纳入评分:{列出,如 session 级触发行为、跨任务效果对比}
严重度:🔴 该维度核心路径缺失或断裂 | 🟡 机制存在但未接入/未被使用 | 🟢 可选优化
与相关 skill 的关系
| skill | 分工 |
|---|---|
| code-review / design-review | 评审具体产物;本 skill 评审产生这些产物的工作流机制 |
| scenario-rehearsal(skill 模式) | 验证单个 skill 质量;本 skill 发现"某类场景无 skill 覆盖"后可建议对现有 skill 推演 |
| loop-discovery | 学习沉淀维度发现缺口后,沉淀动作走 loop-discovery 路由 |
| artifact-optimizer | 优化单个文件;本 skill 不下钻到单文件优化 |
反模式
- ❌ 把清单当健康:"有 40 个 skill" 不是发现,"设计评审技能存在但需求目录中无一份评审报告落盘(存在但未被使用)"才是
- ❌ 编造 session 结论:没有会话证据时禁止声称"AI 经常/从不触发某机制",标注
未观察 - ❌ 满分幻觉:没有前后对比证据时任何维度不得给 95 分以上
- ❌ 发现不落地:每条发现必须有可执行的最小修复动作,不输出"建议加强建设"式空话