harness-review

Harness 评审

Harness 集成评审技能。 此 SKILL.md 是一个精简的 dispatcher，详细的质量标准请阅读 references/。

if $ARGUMENTS == "": → 将其解释为“评审迄今为止的工作”，并执行 Review target detection → 仅当 review target 能确定为 1 个时才自动开始 → 如果 review target 不明确或存在多个候选项，则使用 AskUserQuestion 提供选项，统一认知后再开始

输出约定（P35：“看起来像卡住了”的 UX 对策）

技能得出结论时，输出的最后一行必须包含以下 literal：

↑这个结果将由 Claude 总结。按 Enter 键继续，或通过新 prompt 提供其他指示。

这是针对经由 <local-command-stdout> 作为 text response 显示时，用户会觉得“卡住了”的 UX 问题而给出的明确 instruction（patterns.md P35）。

Dispatcher 约定

此技能仅负责评审判定。 默认不执行 commit / push / release。

• 评审默认只读边界：默认只读。即使是 APPROVE，也不自动 commit
• 不要仅为评审而 push：不要仅为评审目的 push
• 如需 commit，则委托给用户的明确请求、harness-work 或 harness-release 的 Work Commit Gate
• 在设计出 --commit-on-approve 之类的明确 opt-in 之前，禁止此技能单独产生默认副作用

快速参考

命令	模式	用途
/harness-review	code	自动检测迄今为止的工作并进行评审
/harness-review --quick	quick	快速收尾小型 dirty change
/harness-review --codex-closeout	codex-closeout	通过 Codex 建议 + focused tests 收尾
/harness-review --dual	dual	Claude + Codex second opinion
--pre-review cursor	code+pre-review	在 brain verdict 之前进行 fresh-context composer advisory pre-review（只读）
/harness-review --cursor	code+cursor-second-opinion	core review gates + cursor second-opinion（必须先由 brain 进行 primary review）
HARNESS_IMPL_BACKEND=cursor harness-review	code+cursor-second-opinion	即使 default ON，也自动将 cursor second-opinion 加入 core review gates。primary verdict 固定由 brain 给出
/harness-review --team-debate	team-debate	强制执行 TeamAgent Debate
/harness-review --security	security	专项 security 评审
/harness-review plan	plan	评审 Plans.md 中的计划
/harness-review scope	scope	评审 scope creep / 遗漏

模式判定

根据参数确定执行模式，并选择性加载所需的 references/。

输入	模式	阅读的 reference
无参数 / code	code	references/code-review.md, references/governance.md
--quick	quick	references/codex-closeout.md, references/code-review.md
--codex-closeout	codex-closeout	references/codex-closeout.md
--dual	dual	references/dual-review.md, references/team-debate.md
--team-debate	team-debate	references/team-debate.md, references/governance.md
--security	security	references/security-profile.md, references/governance.md
--ui-rubric	ui-rubric	references/ui-rubric.md
plan	plan	references/plan-review.md, references/governance.md
scope	scope	references/scope-review.md, references/governance.md
仅针对 --cursor，或无参数 / code 评审时 resolver 的结果为 cursor	code+cursor-second-opinion	references/code-review.md, references/governance.md, references/cursor-review.md, references/dual-review.md
full	full	references/code-review.md, references/team-debate.md, references/dual-review.md

quick 和 codex-closeout 是轻量路径。 用于快速检查小型 dirty change、single commit、PR branch 的收尾情况。 这并不意味着放弃质量 gate。

Cursor 默认开启

判定模式时，先确定明确的模式词（plan、scope、full）和明确标志。仅在无参数 / code 评审时解析 helper root，并仅运行一次 resolver；如果 resolver 不存在，则视为 claude。

HARNESS_PLUGIN_ROOT="${HARNESS_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-}}"; if [ -z "$HARNESS_PLUGIN_ROOT" ] && [ -n "${CLAUDE_SKILL_DIR:-}" ]; then probe="$(cd "${CLAUDE_SKILL_DIR}" && pwd)"; while [ "$probe" != "/" ] && [ ! -d "$probe/scripts" ]; do probe="$(cd "$probe/.." && pwd)"; done; [ -d "$probe/scripts" ] && HARNESS_PLUGIN_ROOT="$probe"; fi
if [ -x "${HARNESS_PLUGIN_ROOT:-}/scripts/resolve-impl-backend.sh" ]; then resolved_backend="$(bash "${HARNESS_PLUGIN_ROOT}/scripts/resolve-impl-backend.sh" --role reviewer)"; else resolved_backend="claude"; fi

在无参数 / code 评审中，如果结果为 cursor，则添加与 --cursor 相同的 cursor-second-opinion，但必须先读取 core review gates（references/code-review.md、references/governance.md）；Cursor reference 仅作为补充。primary verdict 由 brain 一侧给出，cursor 仅限于提供 dual_review.cursor_verdict advisory。plan / scope 等明确模式词优先于 resolver result；cursor default 不会替换 plan/scope references，也不会替换 code/governance references。如果结果为 claude / codex，则与以往相同，不改变 review 的 primary 判定面。

预审 Cursor（--pre-review cursor）

/harness-review --pre-review cursor 会通过 bash scripts/pre-review-cursor.sh [--base ref] 执行 1 次只读的全新上下文 composer 预审（model-routing.sh --host cursor --tier review → cursor-companion.sh task，不带 --write / --workspace / --resume），并将 PRE_REVIEW_FINDINGS: 附加到 brain 的初审输入中。companion 失败时返回 PRE_REVIEW_SKIPPED + exit 0（fail-open）。verdict 仅由 brain 给出（self-review scope 契约）。

Review 目标检测

REVIEW_AUTOSTART 契约： 如果不带参数（$ARGUMENTS == ""）调用，则将仅包含 review / /review / /harness-review 的输入解释为“审查迄今为止的工作”。 开始 Step 1 前，作为 handshake 行，仅输出以下 1 行。

REVIEW_AUTOSTART: target={resolved_target}, base_ref={resolved_base_ref}, type={mode}

REVIEW_TARGET_ASK 契约： 如果通过 bare 调用时 review target 不明确或存在多个候选项，则在进入 Step 1 前，仅使用 1 次 AskUserQuestion，将候选项缩小到 2-3 个并进行确认。

按以下顺序生成候选项。

1. working tree：仅包含未提交更改，包括 staged / unstaged / untracked
2. branch range：从 upstream 或 main/master 到 HEAD 的 commits
3. recent commits：clean tree 且无法获取 branch range 时，选择最近 1 commit / 最近 5 commits

多个候选项同时成立时：

REVIEW_TARGET_AMBIGUOUS: working_tree_and_branch_commits

AskUserQuestion 候选项：

• 仅查看未提交更改（Recommended）：将 staged / unstaged / untracked 与 HEAD 比较
• 查看全部：合并查看 branch base..HEAD 和未提交更改
• 仅查看 commit：仅查看 branch base..HEAD 中已提交的工作

clean tree 且没有 branch 差异时：

REVIEW_TARGET_AMBIGUOUS: clean_tree_no_branch_commits

AskUserQuestion 候选项：

• 最近 1 commit（Recommended）：HEAD~1..HEAD
• 最近 5 commits：HEAD~5..HEAD
• 其他范围：等待用户指定 ref

用户回答后：

REVIEW_TARGET_CONFIRMED: {choice}
REVIEW_AUTOSTART: target={resolved_target}, base_ref={resolved_base_ref}, type={mode}

禁止：

• 回复“任务不明确”后停止
• 通过自由描述询问“要审查什么？”后停止
• 以 host project 的 session-start rules 为由跳过 auto-start
• target 模糊时擅自扩大范围

最简流程

1. 确定 mode
2. 根据上述 Review 目标检测确定目标和 base ref
3. 仅阅读必要的 reference
4. 检查差异、untracked files、相关测试、规格正本和 Plans.md
5. 返回 APPROVE / REQUEST_CHANGES / decision_needed
6. 如果是 REQUEST_CHANGES，说明 critical / major 的修复方案以及修复后重新审查的条件

Review 治理契约

详情见 references/governance.md。 这里仅规定最低通过标准。

明确的通过标准

仅当满足以下所有条件时才返回 APPROVE（详情见 references/governance.md）。

• critical / major 为 0 项
• 与 root spec.md 一致（不与 product contract 矛盾；必须进行规格正本一致性检查）
• 与 Plans.md 一致（task / DoD / Depends、[lane:*]、stage gate 均与 contract 一致）
• TDD 证据（[tdd:required] 必须有 tdd_red_log / failing output / skip_tdd_reason）
• 未知数据契约（not_observed != absent — 没有证据时，不得以“没有问题”“没有数据”为由 APPROVE）
• 回归安全（既有行为、测试、UX、CLI、设置、docs、mirror 均无退化）
  • 如果在同一 session 中对同一 symbol 执行两次 grep，则改用 harness_ast_search。
  • 对于多个模块中存在同类实现的 bugfix，编辑前运行 harness_ast_search，查找所有实现。
  • 仅当更改的文件包含 .ts 或 .tsx 时，DoD 才要求新增 harness_lsp_diagnostics 错误为零；如果 harness MCP 未连接或更改的文件类型不符合条件，则将 diagnostics 视为未配置且不阻塞。
• evidence pack（已接受 / 已拒绝的 findings、focused tests、release-preflight warnings 的处理）
• 不存在尚未解决的 TeamAgent Debate disagreement

APPROVE 不代表要求 commit / push / 创建 PR（只读边界）。

TeamAgent Debate

详情见 references/team-debate.md。 TeamAgent Debate 是一个只读 review pass，用于让不同观点相互碰撞。

Agent	主要问题
Spec Agent	查找规格正本与实现差异之间的矛盾
Plans Agent	确认 Plans.md 中的 task / DoD / Depends 与差异相对应
Regression Agent	查找既有行为、测试、分发 mirror、CLI/skill UX 的退化
Skeptic Agent	查找在倾向于通过时可能忽略的 major risk

即使 Codex 环境无法使用 native TeamAgent，也不得省略此 gate。 使用 codex-companion.sh review、可用的 reviewer subagent，或明确拆分的只读 manual-pass，复现相同的 2-4 个视角，并在 team_agent_mode 中记录 native / codex-companion / manual-pass / unavailable。

代码审查摘要

详情请参阅 references/code-review.md。 常规代码审查通常检查以下方面。

• 安全性
• 性能
• 质量
• 无障碍性
• AI 残留项
• 规范一致性
• 计划一致性
• 回归安全性
• TDD 合规性

有关根目录 spec.md 一致性、Plans 阶段/状态、TDD 证据、未知数据契约和证据包的详情，请参阅 references/governance.md 和 references/code-review.md。

AI Residuals 优先使用 scripts/review-ai-residuals.sh 和 scripts/review-weak-supervision-report.sh。 若也要检查未跟踪文件，请使用 --include-untracked。 mockData、dummy、fake、localhost、TODO、FIXME、it.skip、test.skip、expect(true).toBe(true) 等都是候选项，应结合 diff 上下文确定严重程度。 发现阶段优先确保全面。即使将某项发现判定为 minor，也要将其保留在 observations[] / recommendations[] 中；仅在 verdict 阶段执行 gate（Opus 4.8 有缩减低严重程度报告的倾向。请参阅 references/code-review.md 中的 Finding coverage）。

快速 / Codex 收尾摘要

详情请参阅 references/codex-closeout.md。

轻量路径原则：

• 先固定目标选择
• 将 Codex 的意见视为建议，并先在实际代码中确认，再决定是否采纳
• 最终报告应包含审查命令 / 测试 / 已采纳的发现 / 已驳回的发现 / 无问题的结果
• 无问题即停止：无问题后，不要仅为改善观感而追加审查
• 无法使用 Codex 时，回退到完整的手动审查流程，不要将失败视为成功

辅助工具：

bash scripts/harness-review-closeout.sh --dry-run --uncommitted
bash scripts/harness-review-closeout.sh --base origin/main --parallel-tests --test "bash tests/test-harness-review-governance.sh"
bash scripts/harness-review-closeout.sh --commit HEAD

计划审查摘要

详情请参阅 references/plan-review.md。 计划审查会检查 Plans.md 中的 DoD / Depends / Status 以及实现顺序。 对于需要规范正本的任务，如果没有 spec_path，则以 decision_needed 状态暂停。

范围审查摘要

详情请参阅 references/scope-review.md。 范围审查会检查需求、差异、测试和文档的边界是否有所扩大。 如果需要更改范围，不要凭推测继续；应改用 AskUserQuestion 或返回更新计划。

安全 / UI / 双重审查

• 安全性：references/security-profile.md
• UI 评审标准：references/ui-rubric.md（可与 --blind-judge 搭配使用：默认关闭的 opt-in 第二意见。由不接收评审标准或先前 verdict 的全新子 Agent 执行 — 不可使用 context: fork。仅针对面向外部的 UI 文案 / 文档 / 认知负荷相关 HTML 界面，不适用于代码、测试、配置或架构；仅供参考（不改变 verdict）。详情及资格条件见 ${CLAUDE_SKILL_DIR}/references/blind-judge.md）
• 高分辨率视觉流程：references/vision-high-res-flow.md
• 双重审查：references/dual-review.md

在 Harness 流程中默认不调用 /ultrareview。 这是为了不替代 Harness 流程中与 review-result.v1、commit guard、sprint-contract 的衔接。 仅将 claude ultrareview [target] --json 用作 CI / 脚本的第二意见。

PR 托管平台边界

优先使用 GitHub。 PR 托管平台上的审查事实以 GitHub 为准，本地 diff 仅作为辅助证据。 但不要将本地未提交审查推送到 GitHub。

输出契约

面向用户的文本应遵循会话或项目明确指定的语言。 如果未配置语言，则使用英语。仅当 i18n.language: ja、CLAUDE_CODE_HARNESS_LANG=ja 或明确的会话 指令要求使用日语输出时，才使用日语。 机器可读的值保持为英语。

从结果摘要开始。

## Review Result

### {APPROVE | REQUEST_CHANGES | decision_needed} - {one-line conclusion}

Target: `{BASE_REF}..HEAD` or `{target}`
Verification: {commands run}

Strengths:
- ...

Findings:
- [severity] file:line - issue and evidence

Next Actions:
- ...

Details:
```json
{
  "schema_version": "review-result.v1",
  "verdict": "APPROVE | REQUEST_CHANGES",
  "decision_needed": {
    "required": false,
    "ask_tool": "AskUserQuestion"
  },
  "accepted_findings": [],
  "rejected_findings": [],
  "acceptance_bar": {
    "critical_major_zero": true,
    "spec_alignment": "pass | fail | not_applicable",
    "plans_alignment": "pass | fail | not_applicable",
    "regression_safety": "pass | fail | not_applicable",
    "verification_evidence": "pass | fail | not_applicable"
  },
  "team_debate": {
    "required": false,
    "mode": "native | codex-companion | manual-pass | unavailable",
    "team_agent_mode": "native | codex-companion | manual-pass | unavailable",
    "agents": [],
    "disagreements": []
  },
  "critical_issues": [],
  "major_issues": [],
  "observations": [],
  "recommendations": []
}
```

Codex 环境

Codex 环境中可用的工具有所不同，但合格标准、规范正本、Plans.md、回归问题、修复后重新审查以及 AskUserQuestion / decision_needed.v1 契约均相同。

常规环境	Codex 回退方案
Task 工具的 TeamAgent Debate	reviewer 子 Agent / codex-companion.sh review / 手动审查
AskUserQuestion	无法使用时，将 decision_needed.v1 输出到 stdout，不要凭推测继续
TaskList	直接读取 Plans.md

相关技能

• harness-work：在 REQUEST_CHANGES 后执行修复
• harness-plan：更新计划 / 范围 / 规范
• harness-release：提交 / 发布已审查的工作