Harness review

Harness Review (v3)

Harness v3 的统一评审技能。 整合了以下旧技能：

• harness-review — 对代码、计划、范围做多角度评审
• codex-review — 使用 Codex CLI 提供第二意见
• verify — 构建验证、错误恢复、应用评审修复
• troubleshoot — 诊断并修复错误与故障

Quick Reference

用户输入	子命令	动作
“评审一下” / review	code（自动）	代码评审（最近的变更）
在执行 harness-plan 后	plan（自动）	计划评审
“确认范围”	scope（自动）	范围分析
harness-review code	code	强制代码评审
harness-review plan	plan	强制计划评审
harness-review scope	scope	强制范围分析
harness-review --dual	code（自动） + Codex 并行	Claude + Codex 双评审
harness-review --security	Security Review	专用 OWASP Top 10 安全评审（只读）

选项

选项	默认值	说明
--dual	无	并行运行 Claude Reviewer 和 Codex Reviewer，并合并 verdict。若 Codex 不可用则自动回退。详见 ${CLAUDE_SKILL_DIR}/references/dual-review.md
--security	无	执行基于 OWASP Top 10 的专用安全评审。只读模式（不可执行 Write/Edit/写入型 Bash）。详见 ${CLAUDE_SKILL_DIR}/references/security-profile.md
--no-commit	无	禁用 APPROVE 后的自动提交

自动判定评审类型

最近活动	评审类型	视角
在 harness-work 之后	Code Review	Security、Performance、Quality、Accessibility、AI Residuals
在 harness-plan 之后	Plan Review	Clarity、Feasibility、Dependencies、Acceptance
新增任务之后	Scope Review	Scope-creep、Priority、Feasibility、Impact

Code Review 流程

Step 1: 收集变更差异

# 如果 harness-work 传入了 BASE_REF 就使用它，否则回退到 HEAD~1
CHANGED_FILES="$(git diff --name-only --diff-filter=ACMR "${BASE_REF:-HEAD~1}")"
git diff ${BASE_REF:-HEAD~1} --stat
git diff ${BASE_REF:-HEAD~1} -- ${CHANGED_FILES}

Step 1.5: 对 AI Residuals 做静态扫描

不要只凭 LLM 的主观印象判断，而要以可复现的方式收集残留候选。scripts/review-ai-residuals.sh 会返回稳定的 JSON，因此应把结果作为评审依据使用。

# 基于 diff
AI_RESIDUALS_JSON="$(bash scripts/review-ai-residuals.sh --base-ref "${BASE_REF:-HEAD~1}")"

# 如果想显式指定目标文件
bash scripts/review-ai-residuals.sh path/to/file.ts path/to/config.sh

Step 2: 从 5 个视角评审

视角	检查内容
Security	SQL 注入、XSS、敏感信息暴露、输入校验
Performance	N+1 查询、不必要的重新渲染、内存泄漏
Quality	命名、单一职责、测试覆盖率、错误处理
Accessibility	ARIA 属性、键盘导航、颜色对比度
AI Residuals	mockData、dummy、fake、localhost、TODO、FIXME、it.skip、describe.skip、test.skip、硬编码的敏感信息/环境相关 URL、明显的临时实现注释

Step 2.2: AI Residuals 的严重级别判定表

对于 AI Residuals，应先查看 scripts/review-ai-residuals.sh 返回的 JSON，再结合 diff 上下文判断“它是否真的构成发布风险”。

重要度	代表例	判定思路
major	指向 localhost / 127.0.0.1 / 0.0.0.0 的连接目标，it.skip / describe.skip / test.skip，看起来像硬编码密钥的值，固定 dev/staging URL	很容易直接导致生产事故、误配置或验证缺失。只要 1 条就应 REQUEST_CHANGES
minor	mockData、dummy、fakeData、TODO、FIXME	很可能是残留，但不一定立刻造成事故。建议修复，但不改变 verdict
recommendation	如 temporary implementation、replace later、placeholder implementation 之类的临时实现注释	仅凭注释还不足以判定为 bug，但值得追踪和澄清

Step 2.5: 基于阈值标准判定 verdict

把所有问题按下表分类，并且只使用这些标准来决定 verdict。

重要度	定义	对 verdict 的影响
critical	安全漏洞、数据丢失风险、可能引发生产故障	只要 1 条 → REQUEST_CHANGES
major	破坏现有功能、与规格明显矛盾、测试不通过	只要 1 条 → REQUEST_CHANGES
minor	命名改进、注释不足、风格不统一	不影响 verdict
recommendation	最佳实践建议、未来改进方向	不影响 verdict

重要：如果只有 minor / recommendation，必须返回 APPROVE。 “有会更好”的改进点，不能成为 REQUEST_CHANGES 的理由。 AI Residuals 也是同样原则。只有那些容易直接造成发布事故或误配置的问题才应归为 major；普通残留候选应保留在 minor 或 recommendation。

Step 3: 输出评审结果

{
  "schema_version": "review-result.v1",
  "verdict": "APPROVE | REQUEST_CHANGES",
  "reviewer_profile": "static | runtime | browser",
  "calibration": {
    "label": "false_positive | false_negative | missed_bug | overstrict_rule",
    "source": "manual | post-review | retrospective",
    "notes": "观察备注",
    "prompt_hint": "供 few-shot 使用的要点",
    "few_shot_ready": true
  },
  "critical_issues": [],
  "major_issues": [],
  "observations": [
    {
      "severity": "critical | major | minor | recommendation",
      "category": "Security | Performance | Quality | Accessibility | AI Residuals",
      "location": "文件名:行号",
      "issue": "问题说明",
      "suggestion": "修复建议"
    }
  ],
  "recommendations": ["非必需的改进建议"]
}

在 browser review 场景下，scripts/generate-browser-review-artifact.sh 会决定 browser_mode、route 和 required artifacts，之后再由 scripts/write-review-result.sh 规范化并保存到 .claude/state/review-result.json。 这个文件会作为 commit guard 和后续流程的共用输入。 带有 calibration 的评审结果会由 scripts/record-review-calibration.sh 追加到 .claude/state/review-calibration.jsonl， 再由 scripts/build-review-few-shot-bank.sh 更新 few-shot bank。

Step 3.5: 使用 --dual 时执行 Codex 并行评审

指定 --dual 标志时，会在 Step 3 的 Claude 评审之外并行执行 Codex 评审，并合并结果。

1. 检查 Codex 是否可用（scripts/codex-companion.sh setup --json）
2. 若可用，则启动 scripts/codex-companion.sh review --base "${BASE_REF:-HEAD~1}"
3. 按 Verdict 合并规则整合双方 verdict
4. 在最终评审结果中附加 dual_review 字段

详细步骤、输出 schema 和回退规格见 ${CLAUDE_SKILL_DIR}/references/dual-review.md。

Step 3.6: 使用 --security 时执行专用安全评审

指定 --security 标志时，会跳过常规 5 视角评审，改走安全专用流程。

只读约束：在这个流程中，完全禁止执行 Write / Edit / 写入型 Bash。

1. 读取安全 profile：

   Read: ${CLAUDE_SKILL_DIR}/references/security-profile.md
   

2. 针对变更 diff 和相关文件检查 OWASP Top 10 全部类别
3. 检查认证 / 授权流程、敏感信息处理方式和依赖包漏洞
4. 设置 reviewer_profile: "security" 并输出结果（遵循 Step 3 的 JSON schema）
5. 使用 Security 模式专属的 verdict 判定标准（见 security-profile.md 末尾）

普通 Code Review 与 --security 的区别：

	普通 Code Review	--security
视角	Security、Performance、Quality、Accessibility、AI Residuals	仅 Security（OWASP Top 10 全项）
深度	安全性只做概览检查	覆盖认证、授权、加密、依赖关系
工具限制	无	仅 Read / Grep / Glob / 只读 Bash
用途	PR 合并前的综合确认	专项安全审计、发布前额外检查

Step 4: 提交判定

• APPROVE：自动执行提交（除非启用了 --no-commit）
• REQUEST_CHANGES：给出 critical / major 问题位置和修复方向。由 harness-work 修复循环自动修复后再评审（最多 3 次）

Plan Review 流程

1. 读取 Plans.md
2. 从以下 5 个视角 进行评审：
   • Clarity：任务描述是否清晰
   • Feasibility：技术上是否可实现
   • Dependencies：任务间依赖是否正确（Depends 列与真实依赖是否一致）
   • Acceptance：完成条件（DoD 列）是否已定义且可验证
   • Value：这个任务是否真能解决用户问题？
     • 是否明确写出了“谁的、什么问题”
     • 是否考虑过替代方案（包括“不做”）
     • 是否存在 Elephant（大家都知道但一直被放着的问题）
3. 检查 DoD / Depends 列质量：
   • DoD 为空的任务 → 警告（“完成条件未定义”）
   • DoD 不可验证（如“感觉没问题”“能正常工作”）→ 警告 + 具体化建议
   • Depends 引用了不存在的任务号 → 错误
   • 循环依赖 → 错误
4. 给出改进建议

Scope Review 流程

1. 列出新增任务 / 功能
2. 从以下视角分析：
   • Scope-creep：是否偏离原始范围
   • Priority：优先级是否合理
   • Feasibility：在当前资源下是否可行
   • Impact：对现有功能的影响
3. 给出风险和建议动作

异常检测

情况	动作
安全漏洞	立即 REQUEST_CHANGES
怀疑篡改测试	警告 + 要求修复
尝试 force push	拒绝 + 给出替代方案

Codex Environment

在 Codex CLI 环境（CODEX_CLI=1）下，由于部分工具不可用，因此使用以下回退方式。

常规环境	Codex 回退方式
用 TaskList 获取任务列表	读取 Plans.md 并检查 WIP / TODO 任务
用 TaskUpdate 更新状态	直接用 Edit 改 Plans.md 标记（如 cc:WIP → cc:完了）
将评审结果写入 Task	改为输出到 stdout

检测方式

if [ "${CODEX_CLI:-}" = "1" ]; then
  # Codex 环境：基于 Plans.md 的回退方式
fi

Codex 环境中的评审输出

由于不支持 Task 工具，评审结果会以 Markdown 形式输出到标准输出。 由 Lead agent 或用户读取结果，并判断下一步动作。

相关技能

• harness-work — 在评审后实现修复
• harness-plan — 创建 / 修改计划
• harness-release — 评审通过后执行发布