| name | harness-review |
| description | 双 Agent 对抗 Review + GAN 启发式评分。基于 Anthropic Labs 的 Generator/Evaluator 分离原则：Generator（内部视角，有完整上下文）负责 spec compliance；Evaluator（对抗视角，只有 diff+需求）负责独立评价。两者都输出结构化评分，不只是 MUST FIX/PASS。参考：harness-design-long-running-apps (Anthropic, 2026-03-24)。 |
harness-review：双 Agent 对抗 Review + 评分
参考：Anthropic Labs — "Harness design for long-running application development"
核心原则：Generator（实现者）和 Evaluator（评判者）必须分离。
自我评价 = 过度宽容。独立 Evaluator 的批评远比让 Generator 自我批判容易。
触发方式
流程内调用：harness-dev 在 code-review 步骤自动调用。
独立调用：用户执行 /harness-review，需提供：
- 需求描述（必填）
- branch 名或 commit range（必填）
- constraints.md（当前目录有
.harness/ 则自动读取）
GAN-Inspired Feedback Loop
Generator produces code
↓
Evaluator grades independently (with specific scores)
↓
Generator iterates based on scores (if MUST FIX exists)
↓
Evaluator re-grades
↓
Loop until pass or user intervenes
This is NOT a one-shot review. It is an iterative improvement loop.
Step 1：准备 Review 材料
生成 diff：
git diff {base_branch}...HEAD
git diff {commit_range}
diff 处理规则（按文件分批，不做粗暴截断）：
Step A：统计
git diff {base}...HEAD --stat
Step B：分批策略（目标每批 ~400 行）
- 500 行以内：完整使用
- 超过 500 行：按文件分组，每批不超过 400 行
- 大文件（单文件超 400 行）：按 hunk 截取关键变更区域
- 告知用户分了几批
分批输出格式：
[Review Batch 1/3 — {文件列表}，共 ~{N} 行]
[DIFF_BATCH_1]
---
[Review Batch 2/3 — {文件列表}，共 ~{N} 行]
[DIFF_BATCH_2]
读取约束： .harness/context/constraints.md（不存在则为空）
Step 2：派发两个 Reviewer（真正并发）
关键原则：Generator 和 Evaluator 必须同时启动，不能串行。
两者各自独立 subagent，有独立上下文，同时运行，互不等待。
最后才汇总评分。
并发派发（不要等一个完成再启动另一个）
同时使用 Agent tool 派发两个 subagent：
Agent "Generator" — 内部 Reviewer（Spec Compliance）
Agent "Evaluator" — 对抗 Reviewer（Evaluator）
等待两个 agent 都返回后，进入 Step 3 汇总。
提示：两个 Agent 是独立调用，不要在 prompt 中等待对方的输出。
Generator 和 Evaluator 必须同时运行，不能串行。
内部 Reviewer — Generator 视角（Spec Compliance）
携带完整信息：需求描述 + 影响面分析 + 设计方案 + 实施计划 + diff + constraints.md
Spec Compliance Review Dimensions:
- Does the implementation match the design intent?
- Are any steps from the implementation plan missing?
- Is boundary case coverage complete?
- Does it conflict with any constraints in constraints.md?
- Is the code readable and maintainable?
Output format (strictly follow):
## Spec Compliance Report
### Scores (1-10)
### spec_fit: {N}/10
Does implementation match design? Deduct for: {description}
### completeness: {N}/10
Is functionality complete? Missing parts: {description}
### boundary_cases: {N}/10
Boundary case coverage: {description}
### constraints_aligned: {N}/10
Alignment with constraints: {description}
### Overall: {avg}/10
### Issues
MUST FIX: [serious spec violations — must fix before proceeding]
SUGGEST: [improvements, non-blocking]
QUESTION: [clarifications needed]
[If all dimensions ≥ 8 with no MUST FIX:]
PASS — Spec Compliance passed
对抗 Reviewer — Evaluator 视角（隔离评分）
故意只给：diff + 需求 + constraints。不给设计方案。
这是 Anthropic 说的"分离 Generator 和 Evaluator"的核心：
Evaluator 不知道实现者打算怎么做的，只看最终结果。
Evaluation Dimensions:
| Dimension | Weight | Question |
|---|
| correctness | highest | Does the code correctly implement the requirement? Any logic bugs? |
| readability | highest | Can you understand it on first read? Are names self-explanatory? |
| maintainability | medium | Is structure clear? Any obvious duplication? |
| change_safety | medium | Will this break existing functionality? Is the interface backward compatible? |
| no_slop | reference | Any AI slop patterns? (Template code, unchanged defaults, hardcoded magic numbers) |
Output format (strictly follow):
## Evaluator Report
### Scores (1-10)
### correctness: {N}/10
Evidence: {specific issue with file:line}
### readability: {N}/10
Evidence: {how it reads on first pass}
### maintainability: {N}/10
Evidence: {structure analysis}
### change_safety: {N}/10
Evidence: {potential breakage assessment}
### no_slop: {N}/10
Evidence: {template/default/AI smell check}
### Overall: {avg}/10
### Issues
MUST FIX: [description]
SUGGEST: [description]
QUESTION: [description]
### Scoring Rationale
For each dimension, cite specific code location and reason for deduction.
评分理由（详细说明为什么扣分）
{给出每项扣分的具体代码位置和原因}
[如果 Overall ≥ 7 且无 MUST FIX：]
PASS — Evaluator 通过
**降级处理**：若 codex-plugin-cc 不可用，降级为 Claude subagent，标注 `⚠️ Codex 不可用，已降级为 Claude Evaluator`。
---
## Step 2.5：Anti-Leniency Scoring Discipline
> **Scoring rule from Anthropic eval-criteria.md:**
> "If you cannot point to specific observable evidence of quality, do not score above 3."
> "3 is the baseline, not a consolation prize."
**Scoring discipline**:
When scoring, you MUST be able to cite specific, observable evidence.
❌ Wrong: "Code looks okay" → score 6
✅ Right: "Function names are self-explanatory, logic flow is clear, no magic numbers"
→ Has evidence → can score 7+
❌ Wrong: "Implementation is fairly complete" → score 5
✅ Right: "All ACs have corresponding implementation, boundary cases have test coverage"
→ Has evidence → can score 7+
For each deduction, you MUST:
- Cite specific code line or behavior ("at {file}:{line}, {specific issue}")
- Explain why it caused the deduction
- Never say "just doesn't feel right"
### Spec Compliance Report（Generator 视角）
| 维度 | 分数 | 证据 |
|------|------|------|
| spec_fit | {N}/10 | {具体证据} |
| completeness | {N}/10 | {具体证据} |
| boundary_cases | {N}/10 | {具体证据} |
| constraints_aligned | {N}/10 | {具体证据} |
| **Overall** | **{avg}/10** | — |
**验收标准检查结果**：
| AC ID | 状态 | 验证方法和结果 |
|-------|------|---------------|
| AC-1 | ✅ PASS / ❌ FAIL | {验证方法}: {结果} |
| AC-2 | ✅ PASS / ❌ FAIL | {验证方法}: {结果} |
**Issues**：
- **MUST FIX**: [严重问题]
- **SUGGEST**: [建议改进]
- **QUESTION**: [需要澄清]
---
### Evaluator Report（对抗视角）
| 维度 | 分数 | 证据 |
|------|------|------|
| correctness | {N}/10 | {file}:{line} — {具体问题} |
| readability | {N}/10 | {file}:{line} — {具体问题} |
| maintainability | {N}/10 | {file}:{line} — {具体问题} |
| change_safety | {N}/10 | {file}:{line} — {具体问题} |
| no_slop | {N}/10 | {是否有模板/默认/AI 生成气味} |
| **Overall** | **{avg}/10** | — |
**反宽容检查**：每个维度 ≤ 3 时，必须有具体可观测证据。{维度}={N} 的证据：{...}
**Issues**：
- **MUST FIX**: [严重问题]
- **SUGGEST**: [建议改进]
- **QUESTION**: [需要澄清]
---
## Step 4：3-Way Verdict 判定
> **关键设计**：不是只有 PASS/ITERATE，还有第三种可能——PIVOT。
> PIVOT = 方向错了，不是实现质量问题。从原始 spec 重新开始。
### 三种判定结果
| 判定 | 条件 | 行为 |
|------|------|------|
| **PASS** | Spec ≥ 8 且 Evaluator ≥ 7 且无 MUST FIX | 进入下一步 |
| **ITERATE** | 存在 MUST FIX 或 Spec < 8 或 Evaluator < 7 | Generator 修复后重评（最多3次） |
| **PIVOT** | 3次 ITERATE 后仍失败，或 spec_fit < 5 | 回到原始需求，从头重新分析 + 设计 |
### PIVOT 触发条件
满足以下任一条件 → 触发 PIVOT：
- 连续 3 次 ITERATE 后 Spec 或 Evaluator 仍未达标
- spec_fit < 5（设计与实现完全对不上，可能是需求理解错了）
- 架构层面出现严重违规（security/correctness 核心问题）
- Generator 和 Evaluator 给出矛盾结论（说明 spec 本身有问题）
PIVOT 不丢人 —— 说明需求分析和设计阶段还有优化空间。
### PIVOT 执行流程
🔄 PIVOT — 方向性调整
不是简单重做上一轮的实现，而是：
- 回到原始需求（从 harness-onboard 的 impact_analysis 开始）
- 重新分析影响面（可能有新的相关文件/模块）
- 重新设计方案（Planner 重新出 plan，可以复用之前的失败原因）
- 新增一条记忆到 harness-swarm：
{
"type": "pivot-record",
"reason": "之前方案在 {具体点} 上有根本性错误",
"what-went-wrong": "...",
"confidence": 0.3,
"lesson": "应该先确认 {某个假设} 再开始实现"
}
- 重新进入 Builder → Review 循环
### 通过/未通过判定
| Spec Compliance | Evaluator | 行为 |
|----------------|-----------|------|
| Overall ≥ 8 | Overall ≥ 7 | ✅ 两者都通过 → **PASS** |
| Overall < 8 | — | ❌ Spec 未通过 → **ITERATE** |
| — | Overall < 7 | ❌ Evaluator 未通过 → **ITERATE** |
| MUST FIX 存在 | MUST FIX 存在 | ❌ 两者都有 MUST FIX → **ITERATE** |
| 3次 ITERATE 后仍失败 | — | 🔄 **PIVOT** |
| spec_fit < 5 | — | 🔄 **PIVOT** |
**评分处于 6-7 分区**（例如 Evaluator 6.5/10）：展示警告但不阻断，询问用户是否继续。
⚠️ Evaluator Overall = 6.5/10（勉强通过）
主要扣分项：
- readability: 5/10（变量命名不清晰，函数过长）
- no_slop: 5/10（使用了模板生成的默认样式）
选项：
A. 修复这些问题
B. 忽略，继续下一步
C. 要求重新评分
---
## Step 5：GAN 迭代改进 + PIVOT 决策
当判定为 **ITERATE** 时，驱动迭代改进：
⏸ Review not passed. Beginning iteration {N}/3.
Generator: fix the following issues based on the scores:
MUST FIX #1: [description]
MUST FIX #2: [description]
Score deductions:
- correctness: {N}/10 ([file:line] — null pointer risk)
- readability: {N}/10 ([file:line] — unclear variable names)
After fixing, resubmit to Evaluator for re-grading.
If Overall returns to 7+ with no MUST FIX, it passes.
当判定为 **PIVOT** 时，执行方向性调整（见 Step 4 PIVOT 部分）。
**Max 3 iterations. Stop and report to user after 3 failures.**
评分扣分项：
- correctness: 5/10（[具体代码位置] 有空指针风险）
- readability: 5/10（[具体代码位置] 变量命名不清晰）
修复后，重新提交给 Evaluator 评分。
Evaluator 重新评分，如果 Overall 回到 7+ 且无 MUST FIX，则通过。
如果 3 次迭代后仍未通过，停止并汇报给用户裁决。
迭代上限：3 次。超过后停止并报告。
Context Anxiety Handling
Watch for context anxiety signs during review:
- Model starts wrapping up at ~70% context
- Output "looks complete" but actually omits key parts
If context anxiety is suspected:
- Batch the diff processing (reduce per-session input)
- Add to prompt: "Do not wrap up early. Continue until the task is truly complete."
与 harness-dev 的衔接
- Review 通过 → 返回 harness-dev 继续下一个角色
- Review 未通过 → 进入迭代改进循环
- 3 次迭代后仍失败 → 汇报给用户：需要人工介入哪些问题
