customaize-agent:agent-evaluation

Claude Code Agent 的评估方法

评估 Agent 系统所需的方法不同于传统软件或标准大模型应用。Agent 会动态做出决策，在不同运行之间具有非确定性，而且往往没有唯一正确答案。有效的评估必须考虑这些特性，同时提供可操作的反馈。稳健的评估框架可以推动持续改进、发现回归问题，并验证上下文工程的选择是否达成预期效果。

核心概念

Agent 评估需要以结果为导向，并考虑非确定性和多种有效路径。多维评分标准可以捕捉不同的质量方面：事实准确性、完整性、引用准确性、来源质量和工具效率。LLM-as-judge 可实现大规模评估，而人工评估则能发现边缘情况。

关键在于，Agent 可能会通过不同路径达成目标，因此评估应判断它们是否取得了正确结果，同时遵循合理的过程。

性能驱动因素：95% 的发现 对 BrowseComp 评估（用于测试浏览 Agent 查找难以找到的信息的能力）的研究发现，三个因素可以解释 95% 的性能差异：

因素	解释的差异	启示
Token 用量	80%	Token 越多＝性能越好
工具调用次数	~10%	更多探索会有所帮助
模型选择	~5%	更好的模型能提升效率

对 Claude Code 开发的启示：

• Token 预算很重要：使用现实的 Token 限制进行评估
• 升级模型优于增加 Token：升级模型带来的提升大于增加 Token 预算
• 多 Agent 验证：验证通过独立上下文窗口中的子 Agent 分配工作的架构

评估挑战

非确定性和多种有效路径

Agent 可能会采取完全不同但有效的路径来达成目标。一个 Agent 可能搜索三个来源，另一个则搜索十个。它们可能使用不同的工具找到相同的答案。在这种情况下，检查特定步骤的传统评估方式会失效。

解决方案：关注结果，而不是精确的执行路径。判断 Agent 是否通过合理的过程取得了正确结果。

依赖上下文的失败

Agent 的失败往往会以微妙的方式依赖上下文。Agent 可能能处理复杂查询，却无法处理简单查询。它可能适用于一组工具，却不适用于另一组。只有在上下文累积、经过较长时间的交互后，才可能出现失败。

解决方案：评估必须涵盖不同复杂度级别，并测试长时间交互，而不只是孤立的查询。

复合质量维度

Agent 质量并非单一维度，而是包括事实准确性、完整性、连贯性、工具效率和过程质量。Agent 可能准确性得分很高，但效率得分很低，反之亦然。

Agent 可能准确性得分很高，但效率得分很低。

解决方案：评估评分标准必须涵盖多个维度，并根据使用场景进行适当加权。

评估评分标准设计

多维度评分标准

有效的评分标准会涵盖关键维度，并为各级别提供描述：

指令遵循（权重：0.30）

• 优秀（1.0）：精准遵循所有指令
• 良好（0.8）：存在轻微偏差，但不影响结果
• 可接受（0.6）：遵循了主要指令，遗漏了少数次要指令
• 较差（0.3）：忽略了重要指令
• 失败（0.0）：从根本上误解了任务

输出完整性（权重：0.25）

• 优秀：全面涵盖所有要求的方面
• 良好：涵盖了大部分方面，仅有少量遗漏
• 可接受：涵盖了关键方面，但存在一些遗漏
• 较差：遗漏了重要内容
• 失败：未涉及关键方面

工具效率（权重：0.20）

• 优秀：工具选择最优，调用次数最少
• 良好：工具选择合理，仅有轻微低效
• 可接受：工具使用恰当，但有些冗余
• 较差：工具选择错误或调用过多
• 失败：严重误用工具或调用次数极多

推理质量（权重：0.15）

• 优秀：整个过程中的推理清晰、合乎逻辑
• 良好：总体推理合理，仅有少量不足
• 可接受：具备基本的推理过程
• 较差：推理不清晰或存在缺陷
• 失败：没有明显的推理过程

回复连贯性（权重：0.10）

• 优秀：结构清晰，易于理解
• 良好：总体连贯，仅有轻微问题
• 可接受：可以理解，但有待改进
• 较差：难以理解
• 失败：内容混乱

评分方法

将各维度评估转换为 0.0 到 1.0 之间的数值，并应用相应权重计算加权总分。根据使用场景要求设定及格线（通用场景通常为 0.7，关键操作通常为 0.85）。

评估方法

LLM-as-Judge

使用大模型评估 Agent 输出，易于扩展且能提供一致的判断。设计能涵盖关注维度的评估提示词。基于 LLM 的评估可扩展至大型测试集，并提供一致的判断。关键在于设计有效的评估提示词，涵盖关注的维度。

请提供清晰的任务描述、Agent 输出、真实答案（如有）、附带级别描述的评估量表，并要求以结构化方式作出判断。

评估提示词模板：

You are evaluating the output of a Claude Code agent.

## Original Task
{task_description}

## Agent Output
{agent_output}

## Ground Truth (if available)
{expected_output}

## Evaluation Criteria
For each criterion, assess the output and provide:
1. Score (1-5)
2. Specific evidence supporting your score
3. One improvement suggestion

### Criteria
1. Instruction Following: Did the agent follow all instructions?
2. Completeness: Are all requested aspects covered?
3. Tool Efficiency: Were appropriate tools used efficiently?
4. Reasoning Quality: Is the reasoning clear and sound?
5. Response Coherence: Is the output well-structured?

Provide your evaluation as a structured assessment with scores and justifications.

思维链要求：始终要求先给出评分依据，再给出分数。研究表明，与先给分再解释的方式相比，这能将可靠性提升 15-25%。

人工评估

人工评估可以发现自动化评估遗漏的问题：

• 在不常见的查询中产生幻觉式回答
• 对上下文的细微误解
• 自动化评估忽略的边缘情况
• 语气或处理方式方面的定性问题

对于 Claude Code 开发，请让用户：

• 手动检查 Agent 输出中的边缘情况
• 按复杂度级别进行系统抽样
• 跟踪失败模式，以指导提示词改进

终态评估

对于会生成产物（文件、配置、代码）的命令，应评估最终输出，而不是过程：

• 生成的代码能否正常工作？
• 配置是否有效？
• 输出是否符合要求？

测试集设计

样本选择 开发期间从小规模样本开始。在 Agent 开发早期，由于有大量容易解决的问题，改动会产生显著影响。小型测试集可以揭示显著效果。

从真实使用模式中抽取样本。加入已知边缘情况。确保覆盖不同复杂度级别。

复杂度分层 测试集应涵盖不同复杂度级别：简单（单次工具调用）、中等（多次工具调用）、复杂（多次工具调用、存在明显歧义）和非常复杂（长时间交互、深度推理）。

上下文工程评估

测试提示词变体

迭代优化 Claude Code 提示词时，应进行系统评估：

1. 基线：在测试用例上运行当前提示词
2. 变体：在相同用例上运行修改后的提示词
3. 比较：衡量质量评分、令牌用量和效率
4. 分析：确定哪些更改改善了哪些维度

测试上下文策略

应通过系统评估验证上下文工程的选择。在同一测试集上使用不同的上下文策略运行 Agent。比较质量评分、令牌用量和效率指标。

性能退化测试

通过在不同上下文大小下运行 Agent，测试上下文退化对性能的影响。找出上下文开始造成问题时的性能断崖，并设定安全的运行限值。

高级评估：LLM-as-Judge

关键见解：LLM-as-a-Judge 并非单一技术，而是一系列方法，每种方法都适用于不同的评估场景。选择恰当的方法并缓解已知偏差，是这项技能要培养的核心能力。

评估分类体系

评估方法分为两大类，其可靠性特征各不相同：

直接评分：单个 LLM 按照既定量表对一个回答评分。

• 最适用：客观标准（事实准确性、遵循指令、毒性）
• 可靠性：对于定义明确的标准，中到高
• 失效模式：评分校准漂移、对量表的解读不一致

成对比较：LLM 比较两个回答并选出较好的一个。

• 最适用：主观偏好（语气、风格、说服力）
• 可靠性：评估偏好时高于直接评分
• 失效模式：位置偏差、长度偏差

MT-Bench 论文（Zheng 等人，2023 年）的研究表明，在基于偏好的评估中，成对比较与人类评审的结果一致性高于直接评分；对于有明确真实答案的客观标准，直接评分仍然适用。

偏差情况

LLM 评审会表现出系统性偏差，必须主动加以缓解：

位置偏差：在成对比较中，排在第一位的回答更容易获得优待。缓解方法：交换位置后评估两次，采用多数投票或一致性检查。

长度偏差：无论质量如何，较长的回答评分都更高。缓解方法：通过明确提示忽略长度，并使用长度归一化评分。

自我增强偏差：模型对自己的输出评分更高。缓解方法：使用不同模型进行生成和评估，或承认这一局限。

冗长偏差：即使没有必要，详细解释也会获得更高评分。缓解方法：使用针对具体标准的评分细则，对无关细节扣分。

权威偏差：无论准确性如何，自信且权威的语气都会获得更高评分。缓解方法：要求引用证据，并加入事实核查环节。

指标选择框架

根据评估任务的结构选择指标：

任务类型	主要指标	次要指标
二元分类（通过/失败）	召回率、精确率、F1	Cohen's κ
有序量表（1-5 评分）	Spearman's ρ、Kendall's τ	Cohen's κ（加权）
成对偏好	一致率、位置一致性	置信度校准
多标签	Macro-F1、Micro-F1	各标签精确率/召回率

关键见解：绝对一致性高低不如系统性分歧模式重要。如果评审在特定标准上总是与人类评审意见不一致，那么相比存在随机噪声的评审，这种评审的问题更大。

评估指标参考

分类指标（通过/不通过任务）

精确率：所有被标记为通过的响应中，实际通过的比例是多少？

• 适用于误报代价高的场景

召回率：所有实际通过的响应中，我们识别出的比例是多少？

• 适用于漏报代价高的场景

F1 分数：精确率和召回率的调和平均数

• 适用于提供平衡的单一数值摘要

一致性指标（与人工判断进行比较）

Cohen's Kappa：校正了偶然一致性的判断一致性

• 0.8：几乎完全一致

• 0.6-0.8：高度一致
• 0.4-0.6：中度一致
• < 0.4：一般到较差的一致性

相关性指标（顺序评分）

Spearman's Rank Correlation：排名之间的相关性

• 0.9：极强相关性

• 0.7-0.9：强相关性
• 0.5-0.7：中度相关性
• < 0.5：弱相关性

良好评估系统的指标

指标	良好	可接受	值得关注
Spearman's rho	> 0.8	0.6-0.8	< 0.6
Cohen's Kappa	> 0.7	0.5-0.7	< 0.5
位置一致性	> 0.9	0.8-0.9	< 0.8
长度-分数相关性	< 0.2	0.2-0.4	> 0.4

评估方法

直接评分实现

直接评分需要三个要素：清晰的标准、经过校准的量表和结构化的输出格式。

标准定义模式：

Criterion: [Name]
Description: [What this criterion measures]
Weight: [Relative importance, 0-1]

量表校准：

• 1-3 级量表：带中立选项的二元量表，认知负担最低
• 1-5 级量表：标准 Likert 量表，在细致程度和可靠性之间取得良好平衡
• 1-10 级量表：细致程度高，但更难校准，仅在有详细评分细则时使用

直接评分的提示词结构：

You are an expert evaluator assessing response quality.

## Task
Evaluate the following response against each criterion.

## Original Prompt
{prompt}

## Response to Evaluate
{response}

## Criteria
{for each criterion: name, description, weight}

## Instructions
For each criterion:
1. Find specific evidence in the response
2. Score according to the rubric (1-{max} scale)
3. Justify your score with evidence
4. Suggest one specific improvement

## Output Format
Respond with structured JSON containing scores, justifications, and summary.

思维链要求：所有评分提示词都必须要求先给出理由，再给出分数。研究表明，与先给分数的方法相比，这能将可靠性提高 15-25%。

成对比较实现

对于基于偏好的评估，成对比较本身更可靠，但需要缓解偏差。

位置偏差缓解流程：

1. 第一轮：响应 A 放在第一个位置，响应 B 放在第二个位置
2. 第二轮：响应 B 放在第一个位置，响应 A 放在第二个位置
3. 一致性检查：如果两轮结果不一致，则返回 TIE，并降低置信度
4. 最终判定：选择结果一致的胜者，并对置信度取平均值

成对比较的提示词结构：

You are an expert evaluator comparing two AI responses.

## Critical Instructions
- Do NOT prefer responses because they are longer
- Do NOT prefer responses based on position (first vs second)
- Focus ONLY on quality according to the specified criteria
- Ties are acceptable when responses are genuinely equivalent

## Original Prompt
{prompt}

## Response A
{response_a}

## Response B
{response_b}

## Comparison Criteria
{criteria list}

## Instructions
1. Analyze each response independently first
2. Compare them on each criterion
3. Determine overall winner with confidence level

## Output Format
JSON with per-criterion comparison, overall winner, confidence (0-1), and reasoning.

置信度校准：置信度分数应反映位置一致性：

• 两轮结果一致：置信度 = 各轮置信度的平均值
• 两轮结果不一致：置信度 = 0.5，判定 = TIE

评分细则生成

与开放式评分相比，定义良好的评分细则可将评估差异减少 40-60%。

评分细则组成部分

1. 等级描述：明确界定每个分数等级
2. 特征：定义每个等级的可观察特征
3. 示例：每个等级的代表性输出（如有可能）
4. 边缘案例：为模棱两可的情况提供指导
5. 评分指南：确保应用一致性的一般原则

严格程度校准

• 宽松：通过分数的门槛较低，适合鼓励迭代
• 平衡：公平、符合生产环境常见预期
• 严格：标准较高，适合安全关键或高风险评估

领域适配

评分细则应使用领域专属术语：

• “代码可读性”评分细则会提及变量、函数和注释。
• 文档评分细则会涉及清晰度、准确性和完整性
• 分析评分细则侧重深度、准确性和可操作性

实践指南

评估流水线设计

生产环境评估系统需要多个层次：

┌─────────────────────────────────────────────────┐
│                 Evaluation Pipeline              │
├─────────────────────────────────────────────────┤
│                                                   │
│  Input: Response + Prompt + Context               │
│           │                                       │
│           ▼                                       │
│  ┌─────────────────────┐                         │
│  │   Criteria Loader   │ ◄── Rubrics, weights    │
│  └──────────┬──────────┘                         │
│             │                                     │
│             ▼                                     │
│  ┌─────────────────────┐                         │
│  │   Primary Scorer    │ ◄── Direct or Pairwise  │
│  └──────────┬──────────┘                         │
│             │                                     │
│             ▼                                     │
│  ┌─────────────────────┐                         │
│  │   Bias Mitigation   │ ◄── Position swap, etc. │
│  └──────────┬──────────┘                         │
│             │                                     │
│             ▼                                     │
│  ┌─────────────────────┐                         │
│  │ Confidence Scoring  │ ◄── Calibration         │
│  └──────────┬──────────┘                         │
│             │                                     │
│             ▼                                     │
│  Output: Scores + Justifications + Confidence     │
│                                                   │
└─────────────────────────────────────────────────┘

避免评估陷阱

反模式：评分缺乏依据

• 问题：分数缺乏依据，难以调试或改进
• 解决方案：评分前始终要求提供基于证据的理由

反模式：单轮成对比较

• 问题：位置偏差会扭曲结果
• 解决方案：始终交换位置并检查结果是否一致

反模式：标准过于繁杂

• 问题：衡量多个方面的标准不可靠
• 解决方案：一个标准 = 一个可衡量的方面

反模式：缺少边缘情况指导

• 问题：评估者对模糊情况的处理不一致
• 解决方案：在评分标准中加入边缘情况，并提供明确指导

反模式：忽视置信度校准

• 问题：高置信度的错误判断比低置信度的判断更糟
• 解决方案：根据位置一致性和证据强度校准置信度

决策框架：直接评分还是成对比较

使用此决策树：

Is there an objective ground truth?
├── Yes → Direct Scoring
│   └── Examples: factual accuracy, instruction following, format compliance
│
└── No → Is it a preference or quality judgment?
    ├── Yes → Pairwise Comparison
    │   └── Examples: tone, style, persuasiveness, creativity
    │
    └── No → Consider reference-based evaluation
        └── Examples: summarization (compare to source), translation (compare to reference)

扩大评估规模

对于大批量评估：

1. LLM 评审团（PoLL）：使用多个模型作为评审者，并汇总投票

   • 减少单个模型的偏差
   • 成本更高，但在高风险决策中更可靠

2. 分层评估：先用快速、廉价的模型筛查，再用昂贵的模型处理边缘情况

   • 适用于大批量评估，成本效益高
   • 需要校准筛查阈值

3. 人在回路中：对明确的情况进行自动评估，对低置信度的情况进行人工审核

   • 对关键应用而言，可靠性最佳
   • 设计反馈循环以改进自动评估

示例

示例 1：准确性直接评分

输入：

Prompt: "What causes seasons on Earth?"
Response: "Seasons are caused by Earth's tilted axis. As Earth orbits the Sun, 
different hemispheres receive more direct sunlight at different times of year."
Criterion: Factual Accuracy (weight: 1.0)
Scale: 1-5

输出：

{
  "criterion": "Factual Accuracy",
  "score": 5,
  "evidence": [
    "Correctly identifies axial tilt as primary cause",
    "Correctly explains differential sunlight by hemisphere",
    "No factual errors present"
  ],
  "justification": "Response accurately explains the cause of seasons with correct 
scientific reasoning. Both the axial tilt and its effect on sunlight distribution 
are correctly described.",
  "improvement": "Could add the specific tilt angle (23.5°) for completeness."
}

示例 2：交换位置的成对比较

输入：

Prompt: "Explain machine learning to a beginner"
Response A: [Technical explanation with jargon]
Response B: [Simple analogy-based explanation]
Criteria: ["clarity", "accessibility"]

第一轮（A 在前）：

{ "winner": "B", "confidence": 0.8 }

第二轮（B 在前）：

{ "winner": "A", "confidence": 0.6 }

（注意：胜者是 A，因为 B 位于第一个位置）

映射后的第二轮结果：

{ "winner": "B", "confidence": 0.6 }

最终结果：

{
  "winner": "B",
  "confidence": 0.7,
  "positionConsistency": {
    "consistent": true,
    "firstPassWinner": "B",
    "secondPassWinner": "B"
  }
}

示例 3：生成评分标准

输入：

criterionName: "Code Readability"
criterionDescription: "How easy the code is to understand and maintain"
domain: "software engineering"
scale: "1-5"
strictness: "balanced"

输出（节选）：

{
  "levels": [
    {
      "score": 1,
      "label": "Poor",
      "description": "Code is difficult to understand without significant effort",
      "characteristics": [
        "No meaningful variable or function names",
        "No comments or documentation",
        "Deeply nested or convoluted logic"
      ]
    },
    {
      "score": 3,
      "label": "Adequate",
      "description": "Code is understandable with some effort",
      "characteristics": [
        "Most variables have meaningful names",
        "Basic comments present for complex sections",
        "Logic is followable but could be cleaner"
      ]
    },
    {
      "score": 5,
      "label": "Excellent",
      "description": "Code is immediately clear and maintainable",
      "characteristics": [
        "All names are descriptive and consistent",
        "Comprehensive documentation",
        "Clean, modular structure"
      ]
    }
  ],
  "edgeCases": [
    {
      "situation": "Code is well-structured but uses domain-specific abbreviations",
      "guidance": "Score based on readability for domain experts, not general audience"
    }
  ]
}

迭代改进工作流

1. 找出弱点：通过评估找出 Agent 遇到困难的地方
2. 推测原因：问题出在提示词、上下文还是示例？
3. 修改提示词：根据假设进行有针对性的修改
4. 重新评估：使用修改后的提示词运行相同的测试用例
5. 比较结果：修改是否改善了目标维度？
6. 检查回归：其他维度是否受到影响？
7. 迭代：重复以上步骤，直至质量达到阈值

指南

1. 评分前始终要求提供理由 - 思维链提示可将可靠性提高 15-25%

2. 成对比较时始终交换位置 - 单轮比较会受到位置偏差的影响

3. 让评分尺度的细化程度与评分标准的具体程度相匹配 - 没有详细的等级描述时，不要使用 1-10 分

4. 区分客观标准和主观标准 - 客观标准使用直接评分，主观标准使用成对比较

5. 加入置信度评分 - 根据位置一致性和证据强度进行校准

6. 明确定义边缘情况 - 模糊情况最容易造成评估结果差异

7. 使用领域专用评分标准 - 通用评分标准会产生通用（实用性较低）的评估结果

8. 根据人工判断进行验证 - 只有与人工评估相关联时，自动评估才有价值

9. 监控系统性偏差 - 按标准和回答类型跟踪意见分歧模式

10. 为迭代而设计 - 评估系统会随着反馈循环而不断改进

示例：评估 Claude Code 命令

假设你创建了一个 /refactor 命令，并希望评估它的质量：

测试用例：

1. 简单：在单个文件中重命名变量
2. 中等：从现有代码中提取函数
3. 复杂：重构类以采用新的设计模式
4. 非常复杂：重组模块依赖关系

评估标准：

• 正确性：重构后的代码能否正常运行？
• 完整性：是否更新了所有实例？
• 风格：是否遵循项目规范？
• 效率：是否避免了不必要的更改？

评估提示词：

Evaluate this refactoring output:

Original Code:
{original}

Refactored Code:
{refactored}

Request:
{user_request}

Score 1-5 on each dimension with evidence:
1. Correctness: Does the code still work correctly?
2. Completeness: Were all relevant instances updated?
3. Style: Does it follow the project's coding patterns?
4. Efficiency: Were only necessary changes made?

Provide scores with specific evidence from the code.

迭代： 如果评估发现该命令经常遗漏实例：

1. 添加明确指令：“搜索整个代码库中的所有匹配项”
2. 使用相同的测试用例重新评估
3. 比较完整性得分
4. 检查正确性是否有所下降

缓解大模型评估偏差的技巧

本参考详细介绍了缓解 LLM-as-a-Judge 系统中已知偏差的具体技巧。

位置偏差

问题

在成对比较中，大模型会系统性地偏好特定位置上的回答。研究表明：

• GPT 存在轻微的首位偏差（平局时约有 55% 的概率偏好首位）
• Claude 也表现出类似模式
• 较小的模型通常偏差更明显

缓解方法：位置交换协议

async def position_swap_comparison(response_a, response_b, prompt, criteria):
    # Pass 1: Original order
    result_ab = await compare(response_a, response_b, prompt, criteria)
    
    # Pass 2: Swapped order
    result_ba = await compare(response_b, response_a, prompt, criteria)
    
    # Map second result (A in second position → B in first)
    result_ba_mapped = {
        'winner': {'A': 'B', 'B': 'A', 'TIE': 'TIE'}[result_ba['winner']],
        'confidence': result_ba['confidence']
    }
    
    # Consistency check
    if result_ab['winner'] == result_ba_mapped['winner']:
        return {
            'winner': result_ab['winner'],
            'confidence': (result_ab['confidence'] + result_ba_mapped['confidence']) / 2,
            'position_consistent': True
        }
    else:
        # Disagreement indicates position bias was a factor
        return {
            'winner': 'TIE',
            'confidence': 0.5,
            'position_consistent': False,
            'bias_detected': True
        }

替代方案：多次打乱顺序

若要提高可靠性，请使用多种位置顺序：

async def multi_shuffle_comparison(response_a, response_b, prompt, criteria, n_shuffles=3):
    results = []
    for i in range(n_shuffles):
        if i % 2 == 0:
            r = await compare(response_a, response_b, prompt, criteria)
        else:
            r = await compare(response_b, response_a, prompt, criteria)
            r['winner'] = {'A': 'B', 'B': 'A', 'TIE': 'TIE'}[r['winner']]
        results.append(r)
    
    # Majority vote
    winners = [r['winner'] for r in results]
    final_winner = max(set(winners), key=winners.count)
    agreement = winners.count(final_winner) / len(winners)
    
    return {
        'winner': final_winner,
        'confidence': agreement,
        'n_shuffles': n_shuffles
    }

长度偏差

问题

无论质量如何，大模型往往会给较长的回答更高评分。具体表现为：

• 冗长的回答获得虚高的分数
• 简洁但完整的回答受到惩罚
• 填充内容和重复内容反而得到奖励

缓解方法：明确提示

在提示词中加入防止长度偏差的指令：

CRITICAL EVALUATION GUIDELINES:
- Do NOT prefer responses because they are longer
- Concise, complete answers are as valuable as detailed ones
- Penalize unnecessary verbosity or repetition
- Focus on information density, not word count

缓解方法：长度归一化评分

def length_normalized_score(score, response_length, target_length=500):
    """Adjust score based on response length."""
    length_ratio = response_length / target_length
    
    if length_ratio > 2.0:
        # Penalize excessively long responses
        penalty = (length_ratio - 2.0) * 0.1
        return max(score - penalty, 1)
    elif length_ratio < 0.3:
        # Penalize excessively short responses
        penalty = (0.3 - length_ratio) * 0.5
        return max(score - penalty, 1)
    else:
        return score

缓解方法：单独设置长度标准

将长度作为单独的明确标准，避免对其隐性奖励：

criteria = [
    {"name": "Accuracy", "description": "Factual correctness", "weight": 0.4},
    {"name": "Completeness", "description": "Covers key points", "weight": 0.3},
    {"name": "Conciseness", "description": "No unnecessary content", "weight": 0.3}  # Explicit
]

自我增强偏差

问题

与不同模型生成的输出相比，模型会给自己（或类似模型）生成的输出更高评分。

缓解方法：跨模型评估

使用不同于生成模型的模型系列进行评估：

def get_evaluator_model(generator_model):
    """Select evaluator to avoid self-enhancement bias."""
    if 'gpt' in generator_model.lower():
        return 'claude-4-5-sonnet'
    elif 'claude' in generator_model.lower():
        return 'gpt-5.2'
    else:
        return 'gpt-5.2'  # Default

缓解方法：盲评

在评估前移除回答中的模型归属信息：

def anonymize_response(response, model_name):
    """Remove model-identifying patterns."""
    patterns = [
        f"As {model_name}",
        "I am an AI",
        "I don't have personal opinions",
        # Model-specific patterns
    ]
    anonymized = response
    for pattern in patterns:
        anonymized = anonymized.replace(pattern, "[REDACTED]")
    return anonymized

冗长偏差

问题

即使额外细节无关或不正确，详细的解释也会获得更高分数。

缓解方法：按相关性加权评分

async def relevance_weighted_evaluation(response, prompt, criteria):
    # First, assess relevance of each segment
    relevance_scores = await assess_relevance(response, prompt)
    
    # Weight evaluation by relevance
    segments = split_into_segments(response)
    weighted_scores = []
    for segment, relevance in zip(segments, relevance_scores):
        if relevance > 0.5:  # Only count relevant segments
            score = await evaluate_segment(segment, prompt, criteria)
            weighted_scores.append(score * relevance)
    
    return sum(weighted_scores) / len(weighted_scores)

缓解方法：加入冗长惩罚的评分标准

在评分标准中明确加入冗长惩罚：

rubric_levels = [
    {
        "score": 5,
        "description": "Complete and concise. All necessary information, nothing extraneous.",
        "characteristics": ["Every sentence adds value", "No repetition", "Appropriately scoped"]
    },
    {
        "score": 3,
        "description": "Complete but verbose. Contains unnecessary detail or repetition.",
        "characteristics": ["Main points covered", "Some tangents", "Could be more concise"]
    },
    # ... etc
]

权威性偏差

问题

无论准确性如何，语气自信、权威的回答都会获得更高评分。

缓解方法：要求提供证据

要求回答为其主张明确提供证据：

For each claim in the response:
1. Identify whether it's a factual claim
2. Note if evidence or sources are provided
3. Score based on verifiability, not confidence

IMPORTANT: Confident claims without evidence should NOT receive higher scores than 
hedged claims with evidence.

缓解方法：事实核查环节

在评分前添加事实核查步骤：

async def fact_checked_evaluation(response, prompt, criteria):
    # Extract claims
    claims = await extract_claims(response)
    
    # Fact-check each claim
    fact_check_results = await asyncio.gather(*[
        verify_claim(claim) for claim in claims
    ])
    
    # Adjust score based on fact-check results
    accuracy_factor = sum(r['verified'] for r in fact_check_results) / len(fact_check_results)
    
    base_score = await evaluate(response, prompt, criteria)
    return base_score * (0.7 + 0.3 * accuracy_factor)  # At least 70% of score

综合偏差检测

监控生产环境中的系统性偏差：

class BiasMonitor:
    def __init__(self):
        self.evaluations = []
    
    def record(self, evaluation):
        self.evaluations.append(evaluation)
    
    def detect_position_bias(self):
        """Detect if first position wins more often than expected."""
        first_wins = sum(1 for e in self.evaluations if e['first_position_winner'])
        expected = len(self.evaluations) * 0.5
        z_score = (first_wins - expected) / (expected * 0.5) ** 0.5
        return {'bias_detected': abs(z_score) > 2, 'z_score': z_score}
    
    def detect_length_bias(self):
        """Detect if longer responses score higher."""
        from scipy.stats import spearmanr
        lengths = [e['response_length'] for e in self.evaluations]
        scores = [e['score'] for e in self.evaluations]
        corr, p_value = spearmanr(lengths, scores)
        return {'bias_detected': corr > 0.3 and p_value < 0.05, 'correlation': corr}

汇总表

偏差	主要缓解方法	次要缓解方法	检测方法
位置	交换位置	多次打乱顺序	一致性检查
长度	明确提示	长度归一化	长度与分数的相关性
自我增强	跨模型评估	匿名化	模型比较研究
冗长	按相关性加权	评分标准惩罚	相关性评分
权威性	要求提供证据	事实核查环节	置信度与准确性的相关性

Claude Code 的 LLM-as-Judge 实现模式

本参考提供了实用的提示词模式和工作流，用于在开发过程中评估 Claude Code 命令、技能和 Agent。

模式 1：结构化评估工作流

最可靠的评估采用结构化工作流，将各项工作分开处理：

Define Criteria → Gather Test Cases → Run Evaluation → Mitigate Bias → Interpret Results

步骤 1：定义评估标准

评估前，先制定明确的标准。以可重复使用的格式记录：

## Evaluation Criteria for [Command/Skill Name]

### Criterion 1: Instruction Following (weight: 0.30)
- **Description**: Does the output follow all explicit instructions?
- **1 (Poor)**: Ignores or misunderstands core instructions
- **3 (Adequate)**: Follows main instructions, misses some details
- **5 (Excellent)**: Follows all instructions precisely

### Criterion 2: Output Completeness (weight: 0.25)
- **Description**: Are all requested aspects covered?
- **1 (Poor)**: Major aspects missing
- **3 (Adequate)**: Core aspects covered with gaps
- **5 (Excellent)**: All aspects thoroughly addressed

### Criterion 3: Tool Efficiency (weight: 0.20)
- **Description**: Were appropriate tools used efficiently?
- **1 (Poor)**: Wrong tools or excessive redundant calls
- **3 (Adequate)**: Appropriate tools with some redundancy
- **5 (Excellent)**: Optimal tool selection, minimal calls

### Criterion 4: Reasoning Quality (weight: 0.15)
- **Description**: Is the reasoning clear and sound?
- **1 (Poor)**: No apparent reasoning or flawed logic
- **3 (Adequate)**: Basic reasoning present
- **5 (Excellent)**: Clear, logical reasoning throughout

### Criterion 5: Response Coherence (weight: 0.10)
- **Description**: Is the output well-structured and clear?
- **1 (Poor)**: Difficult to follow or incoherent
- **3 (Adequate)**: Understandable but could be clearer
- **5 (Excellent)**: Well-structured, easy to follow

步骤 2：创建测试用例

按复杂度级别组织测试用例：

## Test Cases for /refactor Command

### Simple (Single Operation)
- **Input**: Rename variable `x` to `count` in a single file
- **Expected**: All instances renamed, code still runs
- **Complexity**: Low

### Medium (Multiple Operations)
- **Input**: Extract function from 20-line code block
- **Expected**: New function created, original call site updated, behavior preserved
- **Complexity**: Medium

### Complex (Cross-File Changes)
- **Input**: Refactor class to use Strategy pattern
- **Expected**: Interface created, implementations separated, all usages updated
- **Complexity**: High

### Edge Case
- **Input**: Refactor code with conflicting variable names in nested scopes
- **Expected**: Correct scoping preserved, no accidental shadowing
- **Complexity**: Edge case

步骤 3：运行直接评分评估

使用此提示词模板评估单个输出：

You are evaluating the output of a Claude Code command.

## Original Task
{paste the user's original request}

## Command Output
{paste the full command output including tool calls}

## Evaluation Criteria
{paste your criteria definitions from Step 1}

## Instructions
For each criterion:
1. Find specific evidence in the output that supports your assessment
2. Assign a score (1-5) based on the rubric levels
3. Write a 1-2 sentence justification citing the evidence
4. Suggest one specific improvement

IMPORTANT: Provide your justification BEFORE stating the score. This improves evaluation reliability.

## Output Format
For each criterion, respond with:

### [Criterion Name]
**Evidence**: [Quote or describe specific parts of the output]
**Justification**: [Explain how the evidence maps to the rubric level]
**Score**: [1-5]
**Improvement**: [One actionable suggestion]

### Overall Assessment
**Weighted Score**: [Calculate: sum of (score × weight)]
**Pass/Fail**: [Pass if weighted score ≥ 3.5]
**Summary**: [2-3 sentences summarizing strengths and weaknesses]

步骤 4：降低比较中的位置偏差

比较两个提示词变体（A 与 B）时，使用以下两轮工作流：

第 1 轮（A 在前）：

You are comparing two outputs from different prompt variants.

## Original Task
{task description}

## Output A (First Variant)
{output from prompt variant A}

## Output B (Second Variant)
{output from prompt variant B}

## Comparison Criteria
- Instruction Following
- Output Completeness
- Reasoning Quality

## Critical Instructions
- Do NOT prefer outputs because they are longer
- Do NOT prefer outputs based on their position (first vs second)
- Focus ONLY on quality differences
- TIE is acceptable when outputs are equivalent

## Analysis Process
1. Analyze Output A independently: [strengths, weaknesses]
2. Analyze Output B independently: [strengths, weaknesses]
3. Compare on each criterion
4. Determine winner with confidence (0-1)

## Output
Reasoning: [Explain why]
Winner: [A/B/TIE]
Confidence: [0.0-1.0]

第 2 轮（B 在前）： 重复使用相同的提示词，但调换顺序——将输出 B 放在前面，输出 A 放在后面。

解读结果：

• 如果两轮结果一致 → 确认胜出者，并计算置信度平均值
• 如果两轮结果不一致 → 结果为平局，置信度为 0.5（检测到位置偏差）

模式 2：分层评估工作流

对于复杂评估，采用分层方法：

Quick Screen (cheap model) → Detailed Evaluation (expensive model) → Human Review (edge cases)

第 1 层：快速筛查（使用 Haiku）

Rate this command output 0-10 for basic adequacy.

Task: {brief task description}
Output: {command output}

Quick assessment: Does this output reasonably address the task?
Score (0-10):
One-line reasoning:

判定规则：分数 < 5 → 未通过，分数 ≥ 7 → 通过，分数为 5-7 → 升级至详细评估

第 2 层：详细评估（使用 Opus）

对于处于临界范围的案例，使用模式 1 中完整的直接评分提示词。

第 3 层：人工审核

对于置信度较低的自动评估（置信度 < 0.6），将其加入人工审核队列：

## Human Review Request

**Automated Score**: 3.2/5 (Confidence: 0.45)
**Reason for Escalation**: Low confidence, evaluator disagreed across passes

### What to Review
1. Does the output actually complete the task?
2. Are the automated criterion scores reasonable?
3. What did the automation miss?

### Original Task
{task}

### Output
{output}

### Automated Assessment
{paste automated evaluation}

### Human Override
[ ] Agree with automation
[ ] Override to PASS - Reason: ___
[ ] Override to FAIL - Reason: ___

模式 3：大模型评审团（PoLL）

对于高风险评估，使用多个模型：

工作流

1. 运行 3 次独立评估，使用不同的提示词表述方式：

   • 评估 1：标准标准提示词
   • 评估 2：对抗性表述（“找出此输出的问题”）
   • 评估 3：用户视角（“开发者会满意吗？”）

2. 汇总结果：

   • 计算每项标准的中位数分数（对异常值更稳健）
   • 标记方差较大的标准（std > 1.0）以供审核
   • 总体是否通过取决于多数意见

多评审提示词变体

标准表述：

Evaluate this output against the specified criteria. Be fair and balanced.

对抗性表述：

Your role is to find problems with this output. Be critical and thorough.
Look for: factual errors, missing requirements, inefficiencies, unclear explanations.

用户视角：

Imagine you're a developer who requested this task.
Would you be satisfied with this result? Would you need to redo any work?

一致性分析

运行所有评审后，检查一致性：

标准	评审 1	评审 2	评审 3	中位数	标准差
遵循指令	4	4	5	4	0.58
完整性	3	4	3	3	0.58
工具效率	2	3	4	3	1.00 ⚠️

⚠️ 工具效率的方差较大，这表明该标准需要更明确的定义，或者输出在效率特征上存在歧义。

模式 4：置信度校准

置信度分数应与实际可靠性相匹配：

置信度因素

因素	高置信度	低置信度
位置一致性	两轮结果一致	两轮结果不一致
证据数量	3 条以上具体引证	引证含糊或没有引证
标准一致性	所有标准的评分一致	各标准的评分差异很大
边缘案例匹配度	与已知案例相似	情况新颖

在提示词中添加校准说明

将以下内容添加到评估提示词中：

## Confidence Assessment

After scoring, assess your confidence:

1. **Evidence Strength**: How specific was the evidence you cited?
   - Strong: Quoted exact passages, precise observations
   - Moderate: General observations, reasonable inferences
   - Weak: Vague impressions, assumptions

2. **Criterion Clarity**: How clear were the criterion boundaries?
   - Clear: Easy to map output to rubric levels
   - Ambiguous: Output fell between levels
   - Unclear: Rubric didn't fit this case

3. **Overall Confidence**: [0.0-1.0]
   - 0.9+: Very confident, clear evidence, obvious rubric fit
   - 0.7-0.9: Confident, good evidence, minor ambiguity
   - 0.5-0.7: Moderate confidence, some ambiguity
   - <0.5: Low confidence, significant uncertainty

Confidence: [score]
Confidence Reasoning: [explain what factors affected confidence]

模式 5：结构化输出格式

要求采用一致的输出结构，以便于分析：

评估输出模板

## Evaluation Results

### Metadata
- **Evaluated**: [command/skill name]
- **Test Case**: [test case ID or description]
- **Evaluator**: [model used]
- **Timestamp**: [when evaluated]

### Criterion Scores

| Criterion | Score | Weight | Weighted | Confidence |
|-----------|-------|--------|----------|------------|
| Instruction Following | 4/5 | 0.30 | 1.20 | 0.85 |
| Output Completeness | 3/5 | 0.25 | 0.75 | 0.70 |
| Tool Efficiency | 5/5 | 0.20 | 1.00 | 0.90 |
| Reasoning Quality | 4/5 | 0.15 | 0.60 | 0.75 |
| Response Coherence | 4/5 | 0.10 | 0.40 | 0.80 |

### Summary
- **Overall Score**: 3.95/5.0
- **Pass Threshold**: 3.5/5.0
- **Result**: ✅ PASS

### Evidence Summary
- **Strengths**: [bullet points]
- **Weaknesses**: [bullet points]
- **Improvements**: [prioritized suggestions]

### Confidence Assessment
- **Overall Confidence**: 0.78
- **Flags**: [any concerns or caveats]

Claude Code 开发的评估工作流

工作流：测试新命令

1. 编写 5-10 个测试用例，涵盖不同复杂度级别
2. 运行命令处理每个测试用例，并捕获完整输出
3. 使用第 1 层评估对所有输出进行快速筛查
4. 对未通过和处于临界范围的案例进行详细评估
5. 识别失败中的模式，以指导提示词改进
6. 根据发现的具体弱点迭代优化提示词
7. 重新评估相同的测试用例，以衡量改进效果

工作流：比较提示词变体

1. 创建提示词变体（例如，使用不同的指令表述方式）
2. 使用相同的测试用例运行两个变体
3. 通过调换位置进行成对比较
4. 计算每个变体的胜率
5. 分析每个变体在哪些案例上表现更好
6. 做出决定：选出胜者或创建混合版本

工作流：回归测试

1. 维护测试套件，包含具有代表性的案例
2. 变更前：运行评估，记录基线分数
3. 变更后：重新运行评估
4. 比较：标记回归（分数下降 > 0.5）
5. 调查：具体哪些案例出现了回归？原因是什么？
6. 接受或回滚：根据整体影响决定

工作流：持续质量监控

1. 抽样生产环境用量（如果可用）
2. 对样本运行轻量级评估
3. 跟踪指标随时间的变化：
   • 各项标准的平均分
   • 失败率
   • 低置信度比例
4. 性能下降时发出提醒：分数较基线下降 > 10%
5. 定期深入分析：每月对随机样本进行详细评估

应避免的反模式

❌ 缺乏依据的评分

问题：评分缺乏依据，难以调试 解决方案：始终要求先提供证据，再给出评分

❌ 单轮成对比较

问题：位置偏差会导致结果失真 解决方案：始终交换位置并检查一致性

❌ 标准过载

问题：同时衡量多项内容的标准不可靠 解决方案：一项标准 = 一个可衡量的方面

❌ 缺少边缘案例指南

问题：评估者对模糊案例的处理不一致 解决方案：在评分细则中纳入边缘案例，并提供明确指导

❌ 忽略低置信度

问题：依据不确定的评估采取行动会导致错误结论 解决方案：将低置信度案例上报，以供人工审核

❌ 通用评分细则

问题：通用标准会导致评估内容模糊且缺乏帮助 解决方案：创建特定领域的评分细则（代码命令、文档命令和分析命令分别制定）

处理评估失败

评估失败或结果不可靠时，请使用以下恢复策略：

忽略格式错误的输出

评估者生成无法解析或不完整的输出时：

1. 标记为无效，并在分析中忽略——输出不正确通常意味着思考过程中出现了幻觉

2. 不做更改，重试初始提示词——多次重试通常比单次提示词更一致

3. 如果仍然生成不正确的输出，则标记以供人工审核：标记为“评估失败，需要手动检查”，并加入队列以便稍后处理

验证清单

在采信评估结果前，请确认：

• 所有标准的分数都在有效范围内（1-5）
• 每项评分都有引用具体证据的理由
• 已提供置信度分数，且数值合理
• 理由与给定分数之间没有矛盾
• 加权总分计算正确

验证评估提示词（元评估）

将评估提示词用于生产环境前，请使用已知案例进行测试：

校准测试案例

创建一组小型输出样本，并确定其质量等级：

测试类型	描述	预期分数
已知优秀	明显出色的输出	4.5+ / 5.0
已知糟糕	明显较差的输出	< 2.5 / 5.0
边界案例	处于临界值的案例	3.0-3.5，并附有细致说明

验证工作流

1. 已知优秀测试：评估明显出色的输出

   • 如果分数 < 4.0 → 评分细则过于严格，或证据要求不明确

2. 已知糟糕测试：评估明显较差的输出

   • 如果分数 > 3.0 → 评分细则过于宽松，或标准不够具体

3. 边界测试：评估处于临界值的案例

   • 应给出中等分数（3.0-3.5），并附有详细说明
   • 如果给出置信度很高的高分或低分 → 标准缺乏细致区分

4. 一致性测试：对同一评估运行 3 次

   • 分数差异应 < 0.5
   • 如果差异更大 → 需要更严格地定义标准

位置偏差验证

使用成对比较前，请测试是否存在位置偏差：

## Position Bias Test

Run this test with IDENTICAL outputs in both positions:

Test Case: [Same output text]
Position A: [Paste output]
Position B: [Paste identical output]

Expected Result: TIE with high confidence (>0.9)

If Result Shows Winner:
- Position bias detected
- Add stronger anti-bias instructions to prompt
- Re-test until TIE achieved consistently

评估提示词迭代

校准测试失败时：

1. 识别失败模式：过于严格？过于宽松？不一致？
2. 调整具体评分标准等级：添加示例，明确界限
3. 重新运行校准测试：4 项测试必须全部通过
4. 记录变更：跟踪哪些调整提高了可靠性

大模型评估的指标选择指南

本参考指南介绍如何为不同的评估场景选择合适的指标。

指标类别

分类指标

用于二元或多类别评估任务（通过/失败、正确/错误）。

精确率

Precision = True Positives / (True Positives + False Positives)

解读：评判者判定为良好的所有回复中，实际良好的回复占多少比例？

适用场景：误报代价高时（例如，批准不安全内容）

召回率

Recall = True Positives / (True Positives + False Negatives)

解读：实际良好的所有回复中，评判者识别出的回复占多少比例？

适用场景：漏报代价高时（例如，筛选时漏掉优质内容）

F1 分数

F1 = 2 * (Precision * Recall) / (Precision + Recall)

解读：精确率和召回率的调和平均数

适用场景：需要一个平衡两方面考量的单一数值时

一致性指标

用于比较自动评估与人工判断。

Cohen's Kappa（κ）

κ = (Observed Agreement - Expected Agreement) / (1 - Expected Agreement)

解读：校正偶然因素后的判断一致性

• κ > 0.8：几乎完全一致
• κ 0.6-0.8：高度一致
• κ 0.4-0.6：中度一致
• κ < 0.4：一致性一般或较差

适用于：二元或类别判断

加权 Kappa

适用于意见分歧的严重程度很重要的顺序量表：

解读：对较大的分歧比对较小的分歧施加更大的惩罚

相关性指标

用于顺序或连续分数。

Spearman 等级相关系数（ρ）

解读：排名之间的相关性，而非绝对值之间的相关性

• ρ > 0.9：极强相关
• ρ 0.7-0.9：强相关
• ρ 0.5-0.7：中度相关
• ρ < 0.5：弱相关

适用场景：顺序比精确数值更重要时

Kendall's Tau（τ）

解读：与 Spearman 相似，但基于成对一致性

适用场景：存在许多并列值时

Pearson 相关系数（r）

解读：分数之间的线性相关性

适用场景：精确分数值很重要，而不仅仅是顺序时

成对比较指标

一致率

Agreement = (Matching Decisions) / (Total Comparisons)

解读：简单的百分比一致率

位置一致性

Consistency = (Consistent across position swaps) / (Total comparisons)

解读：交换位置会改变判断结果的频率

指标选择决策树

What type of evaluation task?
│
├── Binary classification (pass/fail)
│   └── Use: Precision, Recall, F1, Cohen's κ
│
├── Ordinal scale (1-5 rating)
│   ├── Comparing to human judgments?
│   │   └── Use: Spearman's ρ, Weighted κ
│   └── Comparing two automated judges?
│       └── Use: Kendall's τ, Spearman's ρ
│
├── Pairwise preference
│   └── Use: Agreement rate, Position consistency
│
└── Multi-label classification
    └── Use: Macro-F1, Micro-F1, Per-label metrics

按使用场景选择指标

使用场景 1：验证自动评估

目标：确保自动评估与人工判断相关

推荐指标：

1. 主要指标：Spearman's ρ（用于顺序量表）或 Cohen's κ（用于类别数据）
2. 次要指标：各评估标准的一致性
3. 诊断指标：用于发现系统性错误的混淆矩阵

使用场景 2：比较两个模型

目标：确定哪个模型生成的输出更好

推荐指标：

1. 主要指标：胜率（基于成对比较）
2. 次要指标：位置一致性（偏差检查）
3. 诊断指标：各评估标准的细分结果

使用场景 3：质量监控

目标：跟踪评估质量随时间的变化

推荐指标：

1. 主要指标：与人工抽查结果的滚动一致性
2. 次要指标：分数分布稳定性
3. 诊断指标：偏差指标（位置、长度）

解读指标结果

良好评估系统的指标

指标	良好	可接受	值得关注
Spearman's ρ	> 0.8	0.6-0.8	< 0.6
Cohen's κ	> 0.7	0.5-0.7	< 0.5
位置一致性	> 0.9	0.8-0.9	< 0.8
长度相关性	< 0.2	0.2-0.4	> 0.4

警示信号

1. 一致性高但相关性低：可能表明校准存在问题
2. 位置一致性低：位置偏差正在影响结果
3. 长度相关性高：长度偏差导致分数虚高
4. 各项标准的方差：某些标准可能定义不明确

报告模板

## Evaluation System Metrics Report

### Human Agreement
- Spearman's ρ: 0.82 (p < 0.001)
- Cohen's κ: 0.74
- Sample size: 500 evaluations

### Bias Indicators
- Position consistency: 91%
- Length-score correlation: 0.12

### Per-Criterion Performance
| Criterion | Spearman's ρ | κ |
|-----------|--------------|---|
| Accuracy | 0.88 | 0.79 |
| Clarity | 0.76 | 0.68 |
| Completeness | 0.81 | 0.72 |

### Recommendations
- All metrics within acceptable ranges
- Monitor "Clarity" criterion - lower agreement may indicate need for rubric refinement