bestpractice_agent_defect_diagnosis

Z3 全文↑ Z2 条目

道-方法 · 道层 skill 全文

本页是 <code>rules/skills/drafts/bestpractice_agent_defect_diagnosis.md</code> 的逐字投影（仅隐私清洗，零改写）。

时点提示：本页是仓内文件 rules/skills/drafts/bestpractice_agent_defect_diagnosis.md 的逐字投影（仅做隐私清洗：仓库根绝对路径→相对路径、家目录→~/；除此零改写）。若源文件后续有修订，以仓内真源为准。

Agent 缺陷判别方法论

元数据

类型: BestPractice
适用场景: E2E 测试失败时，判断是 Agent 行为问题还是 Skill 文档问题
创建日期: 2026-03-29
来源: codebase-explorer V5 多仓库验证
验证: Flask 30/30 (基准) + 4 个仓库失败分析

核心洞察

当基准系统达到 ALL_PASS 时，其他系统的所有失败项都可归因为 agent_behavior，而非 skill_doc 缺陷。

这个方法论的核心是建立一个"完美基准"——用最简单、最标准的场景验证 Skill 文档的完整性。一旦基准通过，任何其他失败都是 Agent 执行层面的问题，而非文档设计问题。

判别决策树

E2E 测试失败
    │
    ├─→ 是否有基准系统达到 ALL_PASS？
    │       │
    │       └─→ 否 → 先修复 Skill 文档，建立基准
    │       │
    │       └─→ 是 → 继续
    │
    ├─→ 失败项是否与基准使用相同的 Skill 指令？
    │       │
    │       └─→ 否 → 可能是 Skill 问题，检查文档覆盖
    │       │
    │       └─→ 是 → Agent 行为问题
    │
    └─→ Agent 行为问题分类
            │
            ├─→ 模型行为（如日文 kanji 编码）→ 换模型或加 warning
            ├─→ 未调用必要工具 → 检查 prompt 引导
            ├─→ 非功能性命名 → 加命名规范检查
            └─→ 上下文耗尽 → 加 context budget trigger

基准系统选择标准

选择基准系统时，应满足：

规模适中: 不会触发 context window 问题
结构标准: 没有极端的边缘情况
已有验证: 之前成功过的案例
可复现: 能够稳定达到 ALL_PASS

案例：codebase-explorer V5

仓库	评分	分析
Flask	30/30 ✅	基准系统
Celery	26/30	Agent 行为：日文 kanji、未调用 submit_analysis
Rich	26/30	Agent 行为：非功能性命名
Scrapy	25/30	Agent 行为：类似问题
FastAPI	18/30	Agent 行为：context window 耗尽（23 cones）

结论: 所有失败都是 agent_behavior，Skill 文档已验证完整。

缺陷分类详解

1. Agent Behavior（Agent 行为问题）

特征: Skill 文档指令清晰，但 Agent 未正确执行

常见类型:

类型	症状	解决方案
模型行为	日文 kanji、编码问题	换模型或加 warning
未调用工具	跳过必要步骤（如 submit_analysis）	加显式 prompt 引导
命名问题	使用非功能性名称	加命名规范检查
Context 耗尽	大仓库跳过 Phase 4	加 context budget trigger

处理方式: 修改 Agent 配置或加引导，不改 Skill 文档

2. Skill Doc（Skill 文档缺陷）

特征: 基准系统也无法通过，或文档有明确缺失

常见类型:

类型	症状	解决方案
覆盖不全	某些场景无指令	补充文档
歧义指令	Agent 理解不一致	澄清指令
缺少边界	不知道何时停止	加 guard 条件

处理方式: 修改 Skill 文档，重新验证基准

实施流程

Step 1: 建立基准

1. 选择简单、标准的测试案例
2. 运行 E2E 测试
3. 如果失败，修复 Skill 文档
4. 重复直到基准达到 ALL_PASS

Step 2: 多系统验证

1. 用相同 Skill 测试多个系统
2. 记录每个系统的失败项
3. 分类失败原因

Step 3: 根因分析

1. 如果所有系统都失败 → Skill Doc 问题
2. 如果只有基准通过 → Agent Behavior 问题
3. 针对性修复

与 Judge-driven E2E 的关系

本方法论基于 Judge-driven E2E 测试：

单一验收指标: LLM Judge 作为唯一评判
无代理评分: 不使用 ARI/NMI 等代理指标
端到端验证: 测试最终产出，而非中间过程

核心优势: 当基准通过时，Skill 的正确性已被验证，后续失败必然是 Agent 执行问题。

注意事项

基准选择很重要: 太简单会遗漏边缘情况，太复杂会不稳定
区分模型行为: 某些问题是特定模型的行为模式，不是 Skill 缺陷
Context window: 大系统的失败可能是资源限制，不是方法问题
记录模式: 失败分类有助于后续优化 Agent 配置

与其他 Skill 的关系

配合 bestpractice_ai_debugging_diagnosis.md 的代码调试
作为 E2E 测试分析的标准流程

变更日志

日期	变更
2026-03-29	初始版本，来自 codebase-explorer V5 多仓库验证

← 返回道层 skill 索引 · 返回方法论区