mcpField
Q
quality-audit

quality-audit

github.com/rysweet测试与质量7688 次安装22 周前更新
代码仓库

关于 quality-audit

用于代码库质量审计的工作流 Skill，借助并行 Agent 检查并自动推进修复。它会验证发现、创建问题与 PR，并汇总优先级建议。

主要功能

  1. 01并行代码库质量审计
  2. 02多 Agent 验证审计发现
  3. 03生成 GitHub Issue 和 PR
  4. 04检查近期 PR 以减少误报
  5. 05迭代审计并验证修复

适用场景

  1. 01查找安全与可靠性问题
  2. 02审查技术债务和代码结构
  3. 03为确认的问题生成优先级修复

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/rysweet/amplihack --skill quality-audit

安装后在 Claude Code 中输入/quality-audit确认已加载。

附带文件examples.mdreference.md

详细介绍

质量审计工作流

用途

对任意代码库进行系统化的并行质量审计，通过生成 PR 自动修复问题，并提供由 PM 排定优先级的建议。

何时激活

提到以下内容时，我会自动加载：

  • “质量审计”或“代码审计”
  • “代码库审查”或“全面代码审查”
  • “重构机会”或“技术债务审计”
  • “模块质量检查”或“架构审查”
  • 涉及多个 Agent 的“并行分析”

我会做什么

执行一个包含 7 个阶段的工作流：

  1. 熟悉项目（调查阶段）
  2. 使用并行 Agent 审计代码库中的各个部分
  3. 为发现的每个问题创建 GitHub issue 3.5. 根据近期 PR 进行验证（防止误报）
  4. 针对剩余问题在并行工作树中生成 PR
  5. 由 PM 架构师审查 PR 并确定优先级
  6. 在主 issue 中汇总报告建议

快速开始

User: "Run a quality audit on this codebase"
Skill: *activates automatically*
       "Beginning quality audit workflow..."

7 个阶段

阶段 1：项目熟悉
  • 对项目结构运行调查工作流
  • 梳理模块、依赖项和入口点
  • 了解现有模式和架构
阶段 2：并行质量审计
  • 将代码库划分为逻辑部分
  • 为每个部分部署多种类型的 Agent（分析器、审查员、安全专家、优化器）
  • 严格执行 PHILOSOPHY.md 标准
  • 检查模块大小、复杂度和单一职责
阶段 3：整理 issue
  • 为每项发现创建 GitHub issue
  • 标注严重程度、位置和建议
  • 添加适当的标签
  • 添加唯一 ID、关键词和文件元数据
阶段 3.5：审计后验证 [NEW]
  • 扫描过去 30 天内合并的 PR（可配置）
  • 计算 PR 与 issue 匹配的置信度分数
  • 自动关闭高置信度匹配项（≥90%）
  • 标记中等置信度匹配项（70-89%）以供验证
  • 在 issue 和 PR 之间添加双向交叉引用
  • 目标：误报率低于 5%
阶段 4：并行生成 PR
  • 为每个仍未关闭的 issue 创建工作树（worktrees/fix-issue-XXX）
  • 在每个工作树中运行 DEFAULT_WORKFLOW.md
  • 为每个已确认的未关闭 issue 生成修复 PR
阶段 5：PM 审查
  • 调用 pm-architect 技能
  • 按类别和优先级对 PR 分组
  • 识别修复之间的依赖关系
阶段 6：主报告
  • 创建主 GitHub issue
  • 链接所有相关 issue 和 PR
  • 提供包含建议的优先级行动计划

理念贯彻

此工作流会严格贯彻以下原则：

  • 极致简洁：标记过度设计的模块
  • 模块大小限制：目标是每个模块少于 300 LOC
  • 单一职责：每块代码只承担一个用途
  • 零废话：不留存根、TODO 或死代码
  • 反回退（#2805、#2810）：检测静默降级和吞咽错误的模式
  • 结构分析（#2809）：标记过大的文件、深层嵌套代码和纠缠的依赖关系

检测类别

标准类别
类别检测内容
安全性硬编码密钥、缺少输入验证、查询中的字符串插值
可靠性缺少超时设置、裸露的 except 子句、未处理的异步操作
死代码未使用的导入、不可达分支、过时的 TODO
测试缺口没有测试的文件、没有断言的测试
文档缺口没有文档字符串的公共函数、过时的文档
扩展类别

| 类别 | 检测内容 | | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --- | -------------------------- | | 静默回退 | except: pass、返回默认值的宽泛异常捕获、掩盖故障的回退链、隐藏缺失配置的 ?? defaultValue、对必需值使用 dict.get(key, default)、Shell 脚本中的 | | fallback | | 吞掉错误 | 不重新引发异常的 catch 块、将错误转换为 None/null、丢弃异常的全捕获处理、仅记录日志的 catch 块、空 catch 块、catch (Exception) 返回 false/默认值/空集合 | | 丢弃结果 | 即发即弃的异步操作（_ = Task()、未进行错误处理的 asyncio.create_task()）、未检查的 HTTP 响应状态、被丢弃的返回值、未逐项检查失败的 Task.WhenAll/Promise.all/asyncio.gather、未检查的 subprocess.run() | | Shell 反模式 | \|\| true、>/dev/null 2>&1、2>/dev/null、set +e、\|\| fallback_command、缺少 set -euo pipefail | | 静默截断 | 未记录日志的 Take(N)/[:N]/.slice(0,N)、会静默丢弃本应处理的项目的 .Where()/列表推导式、未记录边界日志的字符串子串截取 | | 异步反模式 | async void（C#）、.Result/.Wait() 异步转同步、未等待的协程/Promise、未同步的共享可变状态、未传播 CancellationToken、未释放的 Timer/CancellationTokenSource | | 配置偏差 | 部署配置中定义的环境变量在代码中通过静默回退读取、可能泄漏到预发布/生产环境的 IsDevelopment() 守卫、基础设施未提供配置但服务却依赖该配置 | | 验证缺口 | 缺少输入验证的 API 端点、SQL/GraphQL/Cypher 中的字符串插值、缺少分页上限、缺少请求大小限制、未验证用户输入就解析枚举、信任未经空值检查的外部反序列化数据 | | 健康状态与可观测性 | 应报告为 Unhealthy 却报告为 Degraded、未在 /health 中呈现后台工作器故障、仅记录日志而不报告指标的错误处理、将永久性错误视为暂时性错误（重试而非移入死信队列）、将部分成功标记为完全成功 | | 重试反模式 | 重试耗尽后静默退出的循环、打开但不发出告警的熔断器、最终放弃却不引发最后一次错误的重试逻辑 | | 结构问题 | 超过 500 行的文件、超过 50 行的函数、超过 4 层的嵌套、超过 5 个参数、循环导入 | | 文档 | 时效性内容、不专业的语气（海盗腔、聊天机器人痕迹）、质量/正确性缺陷 | | 硬编码限制 | 不可配置的数字上限（[:N]、max_X = N）、未记录日志的静默截断、处理限制导致的数据丢失 |

多 Agent 验证（v3.0）

每项发现都由 3 个独立 Agent（分析员、审查员、架构师）验证。只有在 ≥2 个 Agent 达成一致时，才确认该发现。这样可在尝试任何修复之前消除误报。

逐步深入的迭代循环（v3.0）

Cycle 1: SEEK → VALIDATE (3 agents) → FIX → decision
Cycle 2: SEEK (deeper) → VALIDATE → FIX → decision
Cycle 3: SEEK (deepest) → VALIDATE → FIX → decision
...continues if thresholds not met

循环规则：

  • 始终至少运行 3 轮
  • 如果出现任何高危／严重级别的新增发现，或新增的中危发现超过 3 个，则继续
  • 最多 6 轮（安全上限）
  • 每轮都要以全新视角深入调查，并质疑此前的发现
  • 修复采用完整的 DEFAULT_WORKFLOW 方法（理解 → 测试 → 实施 → 验证）
  • 每轮修复所有问题规则（#2842）： 每轮中确认的所有发现都必须在该轮结束前修复。不得只完成部分轮次。不得将发现推迟到“后续问题”或“下一轮”。如果 SEEK 发现问题，FIX 必须解决全部问题。
  • 根据新增发现决定是否继续循环（#2842）： 是否继续取决于当前轮是否发现了新问题，而不是旧问题是否仍未修复（根据修复所有问题规则，旧问题不应仍未修复）。
  • 修复验证步骤： 修复后，将已确认的发现与修复结果进行比较，确保没有遗漏。

通过 recipe 运行：

amplihack recipe execute quality-audit-cycle.yaml --context '{"target_path": "src/amplihack", "min_cycles": "3", "max_cycles": "6"}'

配置

通过 recipe 上下文或环境变量覆盖默认值：

结构化输入（recipe 上下文，依据 #2843）：

输入默认值说明
target_pathsrc/amplihack要审计的目录
min_cycles3最少审计轮数
max_cycles6最多轮数（安全上限）
validation_threshold2必须达成一致的最少验证者数量（共 3 个）
severity_thresholdmedium要报告的最低严重程度
module_loc_limit300标记超过此 LOC 的模块
fix_all_per_cycletrue下一轮开始前必须修复所有发现的问题（#2842）
categories(全部)要检查的类别，以逗号分隔

可用类别：security、reliability、dead_code、silent_fallbacks、 error_swallowing、result_dropping、shell_anti_patterns、silent_truncation、 async_anti_patterns、config_divergence、validation_gaps、health_observability、 retry_anti_patterns、structural、hardcoded_limits、test_gaps、doc_gaps、documentation

调用示例：

amplihack recipe execute quality-audit-cycle.yaml --context '{
  "target_path": "src/amplihack/fleet",
  "min_cycles": "3",
  "max_cycles": "6",
  "severity_threshold": "medium",
  "module_loc_limit": "300",
  "fix_all_per_cycle": "true",
  "categories": "security,reliability,dead_code,silent_fallbacks,error_swallowing"
}'

核心设置（环境变量）：

  • AUDIT_PARALLEL_LIMIT：最大并发工作树数量（默认值：8）

阶段 3.5 验证设置：

  • AUDIT_PR_SCAN_DAYS：扫描近期 PR 的天数（默认值：30）
  • AUDIT_AUTO_CLOSE_THRESHOLD：自动关闭所需的置信度百分比（默认值：90）
  • AUDIT_TAG_THRESHOLD：添加标签所需的置信度百分比（默认值：70）
  • AUDIT_ENABLE_VALIDATION：启用阶段 3.5（默认值：true）

评论

支持 Markdown