harness-review

对项目的 AI 编码工作流(Harness)做轻量体检:从任务理解、受控执行、变更验证、可靠交付、学习沉淀五个维度评估机制是否存在与真正被使用,产出带证据状态标注的报告(纯 Markdown,零运行时依赖)。触发:"体检一下工作流"、"评估 AI 工作流"、"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。

核心原则

  1. 配置了 ≠ 用了,用了 ≠ 有效:每条结论必须标注证据状态,禁止把"文件存在"说成"机制有效"
  2. 未观察就说未观察:拿不到证据的行为标 未观察,不编造分数、不脑补结论
  3. 发现必须可修复:每条发现要给出影响、最小修复动作和验证方式;纯粹的数量统计(如"有 40 个 skill")不构成发现
  4. 一次体检是基线:单次体检只能证明机制现状,"是否改善"需要下次可比体检对照

证据状态阶梯

所有维度的检查结论必须使用以下状态词标注:

状态 含义 能支撑的最强结论
存在 机制文件/配置存在 "有这个机制"
已接入 有明确触发路径能到达它(触发词、流程引用、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 分以上
  • ❌ 发现不落地:每条发现必须有可执行的最小修复动作,不输出"建议加强建设"式空话