Harness Review

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

# 工作流体检

## 概述

**目的**：回答"这个项目围绕 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：生成报告

```markdown
# 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 分以上
- ❌ **发现不落地**：每条发现必须有可执行的最小修复动作，不输出"建议加强建设"式空话