silent-degradation-audit

静默降级审计技能

概述

可用于生产环境的技能，用于检测代码库中的静默降级。采用多轮审计系统，包含 6 个专门的类别 Agent、多 Agent 验证小组和收敛检测。已在 CyberGym 代码库上经过实战检验（发现约 250 个 bug）。

何时使用此技能

适用于以下情况：

• 代码存在可靠性问题，但不清楚问题出在哪里
• 系统发生故障时没有任何提示，运维人员无法察觉
• 虽然存在错误处理，但其有效性尚不明确
• 需要全面审计多种故障模式
• 准备部署到生产环境
• 静默故障发生后的事后分析

不适用于以下情况：

• 代码风格或格式问题（使用代码检查工具）
• 性能优化（使用性能分析器）
• 安全漏洞（使用安全扫描工具）
• 简单的一次性代码审查（使用 /analyze）

主要功能

多轮渐进式审计

• 第 1 轮：广泛扫描，发现明显问题（占总数的 40–50%）
• 第 2–3 轮：深入分析，发现隐藏问题（30–40%）
• 第 4–6 轮：检查边界情况和细微问题（10–20%）
• 收敛条件：新增发现少于 10 个或少于第 1 轮的 5% 时停止

6 个类别 Agent

1. 依赖项故障（类别 A）：“当 X 停机时会发生什么？”
2. 配置错误（类别 B）：“配置错误时会发生什么？”
3. 后台任务（类别 C）：“后台任务失败时会发生什么？”
4. 测试有效性（类别 D）：“测试是否真的能检测到故障？”
5. 运维可见性（类别 E）：“运维人员能否看到错误？”
6. 功能占位实现（类别 F）：“这段代码是否真的实现了其名称所描述的功能？”

多 Agent 验证小组

• 由 3 个 Agent 审查发现：安全、架构师、构建者
• 至少需要 2/3 达成共识，才能验证一项发现
• 避免误报和不必要的修改
• 跟踪强共识与弱共识

语言无关

支持 9 种语言，并提供针对各语言的模式：

• Python、JavaScript、TypeScript
• Rust、Go、Java、C#
• Ruby、PHP

集成模式

独立调用

直接调用技能，执行定向审计：

/silent-degradation-audit path/to/codebase

质量审计工作流中的子循环

作为质量审计工作流的第 2 阶段集成：

quality-audit-workflow calls silent-degradation-audit
→ Returns findings to quality workflow
→ Quality workflow applies fixes
→ Continues to next phase

用法

基本用法

# Audit entire codebase
/silent-degradation-audit .

# Audit specific directory
/silent-degradation-audit ./src

# With custom exclusions
/silent-degradation-audit . --exclusions .my-exclusions.json

配置

在代码库根目录中创建 .silent-degradation-config.json：

{
  "convergence": {
    "absolute_threshold": 10,
    "relative_threshold": 0.05
  },
  "max_waves": 6,
  "exclusions": {
    "patterns": ["*.test.js", "test_*.py", "**/__tests__/**"]
  },
  "categories": {
    "enabled": [
      "dependency-failures",
      "config-errors",
      "background-work",
      "test-effectiveness",
      "operator-visibility",
      "functional-stubs"
    ]
  }
}

排除列表

全局排除项

编辑 ~/.amplihack/.claude/skills/silent-degradation-audit/exclusions-global.json：

[
  {
    "pattern": "*.test.*",
    "reason": "Test files excluded from production audits",
    "category": "*"
  },
  {
    "pattern": "**/vendor/**",
    "reason": "Third-party code",
    "category": "*"
  }
]

仓库专属排除项

在仓库根目录中创建 .silent-degradation-exclusions.json：

[
  {
    "pattern": "src/legacy/*.py",
    "reason": "Legacy code being replaced",
    "category": "*",
    "wave": 1
  },
  {
    "pattern": "api/endpoints.py:42",
    "reason": "Empty dict is valid API response",
    "category": "functional-stubs",
    "type": "exact"
  }
]

输出

报告格式

生成 .silent-degradation-report.md：

# Silent Degradation Audit Report

## Summary

- **Total Waves**: 4
- **Total Findings**: 137
- **Converged**: Yes
- **Convergence Ratio**: 4.2%

## Convergence Progress

Wave 1: ██████████████████████████████████████████████████ 120
Wave 2: ███████████████████████████ 65 (54.2% of Wave 1)
Wave 3: ████████ 18 (15.0% of Wave 1)
Wave 4: ██ 5 (4.2% of Wave 1)

Status: ✓ CONVERGED
Reason: Relative threshold met: 4.2% < 5.0%

## Findings by Category

### dependency-failures (42 findings)

- High: 15
- Medium: 20
- Low: 7

[... continues for all 6 categories ...]

发现项格式

生成 .silent-degradation-findings.json：

[
  {
    "id": "dep-001",
    "category": "dependency-failures",
    "severity": "high",
    "file": "src/payments.py",
    "line": 89,
    "description": "Payment API failure silently falls back to mock",
    "impact": "Production system using mock payments, no real charges",
    "visibility": "None - no logs or metrics",
    "recommendation": "Add explicit failure logging and metric, or fail fast",
    "wave": 1,
    "validation": {
      "result": "VALIDATED",
      "consensus": "strong",
      "votes": {
        "security": "APPROVE",
        "architect": "APPROVE",
        "builder": "APPROVE"
      }
    }
  },
  ...
]

工作流详情

第 1 阶段：初始化

1. 创建带阈值的收敛跟踪器
2. 初始化排除项管理器
3. 设置审计状态

第 2 阶段：语言检测

1. 扫描代码库中的文件扩展名
2. 识别语言（文件数 > 5 或占比超过 5%）
3. 加载针对各语言的模式

第 3 阶段：加载排除项

1. 从技能目录加载全局排除项
2. 加载仓库专属排除项
3. 合并为单一排除列表

阶段 4：波次循环

对每个波次（直到收敛）：

1. 类别分析（6 个 Agent 并行）

   • 每个 Agent 扫描特定类别的问题
   • 使用特定于语言的模式
   • 排除之前的发现

2. 验证小组（3 个 Agent 并行）

   • 安全 Agent 审查安全影响
   • 架构师 Agent 审查设计影响
   • 构建者 Agent 审查实现可行性

3. 统计投票

   • 要求 2/3 达成共识（APPROVE）
   • 跟踪强共识与弱共识
   • 将无法得出结论的项目标记为需要人工审查

4. 排除项过滤

   • 应用全局和仓库特定的排除项
   • 过滤重复项

5. 状态更新

   • 将新发现添加到总数中
   • 记录波次指标

6. 收敛检查

   • 绝对标准：少于 10 个新发现
   • 相对标准：少于波次 1 发现数的 5%
   • 如果已收敛，则退出

阶段 5：生成报告

1. 生成收敛图
2. 计算指标摘要
3. 按类型和严重程度对发现进行分类
4. 编写 Markdown 报告
5. 编写 JSON 发现结果

架构

目录结构

.claude/skills/silent-degradation-audit/
├── SKILL.md                    # This file
├── reference.md                # Detailed patterns and examples
├── examples.md                 # Usage examples
├── patterns.md                 # Language-specific patterns
├── README.md                   # Quick start
├── category_agents/            # 6 category agent definitions
│   ├── dependency-failures.md
│   ├── config-errors.md
│   ├── background-work.md
│   ├── test-effectiveness.md
│   ├── operator-visibility.md
│   └── functional-stubs.md
├── validation_panel/           # Validation panel specs
│   ├── panel-spec.md
│   └── voting-rules.md
├── recipe/                     # Recipe-based workflow
│   └── audit-workflow.yaml
└── tools/                      # Python utilities
    ├── exclusion_manager.py
    ├── language_detector.py
    ├── convergence_tracker.py
    └── __init__.py

组件职责

类别 Agent：

• 扫描代码库，查找特定类别的问题
• 使用特定于语言的模式
• 生成包含严重程度、影响和建议的发现结果

验证小组：

• 从多个角度审查发现结果
• 投票 APPROVE/REJECT/ABSTAIN
• 要求 2/3 达成共识

收敛跟踪器：

• 跟踪每个波次的发现结果
• 计算收敛指标
• 确定何时停止

排除项管理器：

• 加载并合并排除列表
• 根据模式过滤发现结果
• 添加新的排除项

语言检测器：

• 识别代码库中的语言
• 加载特定于语言的模式
• 支持 9 种语言

最佳实践

运行首次审计

1. 从小范围开始：先审计单个服务/模块
2. 仔细审查波次 1：以此建立基准
3. 调整排除项：将误报添加到排除列表
4. 验证修复：广泛应用修复前先进行测试

排除项管理

适合添加排除项的情况：

• 误报（发现的问题实际上并不存在）
• 有意的设计（当前行为正确）
• 遗留代码（目前不值得修复）
• 第三方代码（无法修改）

不适合添加排除项的情况：

• 确实存在但你不想修复的问题
• 现在没时间修复的问题
• 看起来很难解决的问题

更好的做法：修复实际问题，并按严重程度确定优先级。

调整验证

如果误报过多：

• 检查验证小组的提示词
• 提高共识门槛（要求全体一致）
• 添加特定类别的验证规则

如果漏掉实际问题：

• 检查类别 Agent 的模式
• 添加特定于语言的模式
• 降低共识门槛（1/3 赞成即可）

波次管理

典型的波次特征：

• 波次 1：40-50% 的发现结果（明显问题）
• 波次 2：25-30%（更深层的问题）
• 波次 3：15-20%（较隐蔽的问题）
• 波次 4+：每个波次少于 10%（边缘情况）

如果波次未能收敛：

• 检查是否存在重复发现（排除功能未生效）
• 检查类别 Agent 之间的重叠（Agent 找到相同问题）
• 考虑降低收敛门槛

指标与监控

成功指标

长期跟踪以下指标：

Audit Success:
- Convergence reached: Yes/No
- Waves to convergence: 4 (target: 3-5)
- Total findings: 137 (varies by codebase)
- Validation rate: 75% (target: 60-80%)

Finding Distribution:
- High severity: 15% (target: < 20%)
- Medium severity: 45% (target: 40-60%)
- Low severity: 40% (target: 30-50%)

Panel Effectiveness:
- Strong consensus: 60% (target: > 50%)
- Weak consensus: 30% (target: 20-40%)
- Inconclusive: 10% (target: < 10%)
- Abstention rate: 5% (target: < 10%)

质量指标

健康的审计：

• 在 3-5 个波次内收敛
• 验证率为 60-80%
• 强共识率 > 50%
• 弃权率 < 10%

警示信号：

• 6 个波次后仍未收敛（Agent 反复发现相同问题）
• 验证率 > 95%（不加判断地照单全收）
• 验证率 < 40%（过于严格）
• 无法得出结论的比例 > 20%（上下文不足）

故障排除

“审计未收敛”

症状：达到最大波次数，但仍未收敛

原因：

• 类别 Agent 找到重复问题
• 排除项过滤未生效
• 收敛门槛过严

解决方案：

1. 检查发现结果中是否有重复项
2. 检查排除模式是否匹配
3. 将相对阈值提高到 10%
4. 将最大波次数减少到 5

“误报过多”

症状：验证率 > 95%，存在大量非问题

原因：

• 类别 Agent 过于激进
• 验证面板过于宽松
• 模式未针对代码库进行调整

解决方案：

1. 检查类别 Agent 模式
2. 为误报模式添加排除项
3. 要求一致通过验证（3/3）
4. 调整特定语言的模式

“漏掉真实问题”

症状：已知问题未出现在发现结果中

原因：

• 类别 Agent 存在缺漏
• 排除范围过广
• 验证面板过于严格

解决方案：

1. 检查问题是否符合任何类别
2. 检查排除列表中是否存在范围过广的模式
3. 将共识阈值降低至 1/3
4. 为漏掉的问题添加具体模式

“验证面板弃权”

症状：弃权率较高（> 20%）

原因：

• 发现结果中的上下文不足
• Agent 提示词不清晰
• 发现的问题超出 Agent 的专业范围

解决方案：

1. 在发现结果中加入更多代码上下文
2. 检查并改进 Agent 提示词
3. 添加第四个“通才”Agent
4. 改进问题描述

高级配置

自定义类别 Agent

在 category_agents/custom.md 中创建自定义类别 Agent：

# Category Custom: My Special Cases

## Core Question

"What happens when [specific scenario]?"

## Detection Focus

[Patterns to detect...]

## Language-Specific Patterns

[Language examples...]

然后在配置中启用：

{
  "categories": {
    "enabled": [
      "dependency-failures",
      "config-errors",
      "background-work",
      "test-effectiveness",
      "operator-visibility",
      "functional-stubs",
      "custom"
    ]
  }
}

自定义验证面板

使用不同的 Agent 覆盖验证面板：

# In recipe/audit-workflow.yaml
validation_panel:
  agents:
    - security
    - architect
    - builder
    - domain-expert # Add domain-specific agent

  consensus:
    required: 0.75 # Require 3/4 approval

分阶段推广

逐步审计代码库：

# Phase 1: Critical services only
/silent-degradation-audit ./services/payments ./services/auth

# Phase 2: All services
/silent-degradation-audit ./services

# Phase 3: Full codebase
/silent-degradation-audit .

另请参阅

• reference.md - 详细的技术参考
• examples.md - 实际使用示例
• patterns.md - 特定语言的退化模式
• README.md - 快速入门指南
• category_agents/ - 各类别 Agent 文档
• validation_panel/ - 验证面板规范

更新日志

Version 1.0.0（2025-02-24）

• 首次发布
• 6 个类别 Agent（A-F）
• 多 Agent 验证面板（2/3 共识）
• 收敛检测（双阈值）
• 语言无关（9 种语言）
• 已在 CyberGym 上经过实战检验（约 250 个漏洞）
• 集成模式：独立运行 + 子循环