code-quality-guardian

代码质量守护者 (Code Quality Guardian)

1. 概述

代码质量不是可选项——它是软件可维护性的基石。本技能在代码进入主分支之前，执行六轴质量门禁，系统性拦截低质量代码。每个轴都有明确的通过/失败标准，不给 "以后优化" 留借口。

与 Hermes Agent 深度集成：利用 patch 工具自动修复低悬果实，利用 delegate_task 并行审查多个文件，利用 /curator 追踪项目质量趋势。

2. 核心流程

2.1 六轴质量门禁

┌──────────────────────────────────────────────────┐
│         代码质量六轴门禁 (Six-Axis Gate)           │
├──────────┬──────────┬──────────┬─────────────────┤
│ 🔒 安全   │ 📐 复杂度 │ 🎨 风格  │ ✅ 测试覆盖     │
│ Security │Complexity│  Style   │Test Coverage   │
├──────────┼──────────┼──────────┼─────────────────┤
│ 📝 文档   │ 📦 依赖   │          │                 │
│   Docs   │   Deps   │          │                 │
└──────────┴──────────┴──────────┴─────────────────┘

2.2 各轴检查标准

🔒 安全 (Security)

• 无硬编码密钥/密码/Token
• 无 SQL 注入风险（使用参数化查询）
• 无 XSS 风险（输出编码）
• 敏感操作有授权检查
• 文件上传有类型/大小限制

# Hermes 工具集成
search_files(pattern="(api_key|password|secret|token)\s*=\s*['"]", target="content")
# 利用 Hermes 的 search_files 进行安全模式扫描

📐 复杂度 (Complexity)

• 单函数 ≤ 30 行（超过拆分为子函数）
• 圈复杂度 ≤ 10
• 嵌套深度 ≤ 3 层
• 单文件 ≤ 500 行
• 函数参数 ≤ 5 个（超过用配置对象）

🎨 风格 (Style)

• 一致的命名规范（snake_case / camelCase）
• 无注释掉的代码（用 Git 历史）
• 无 console.log / print 调试残留
• import 顺序规范（标准库 → 第三方 → 本地）

✅ 测试覆盖 (Test Coverage)

• 新增代码行覆盖率 ≥ 80%
• 关键路径有集成测试
• 无 skip/xfail 的 "临时跳过"

📝 文档 (Documentation)

• 公开 API 有 docstring/JSDoc
• 复杂逻辑有行内注释解释 "为什么" 而非 "做什么"
• README/CHANGELOG 已更新

📦 依赖 (Dependencies)

• 无已知漏洞的依赖版本
• 无未使用的依赖
• 依赖版本锁定（lockfile 已更新）

2.3 Hermes 工具链集成

# 加载技能
/skill code-quality-guardian

# 自动审查流程
# 1. 搜索安全漏洞
search_files(pattern="password\s*=", target="content", path="src/")

# 2. 运行 linter
terminal(command="ruff check src/", timeout=30)

# 3. 运行测试并检查覆盖率
terminal(command="pytest --cov=src/ --cov-report=term-missing", timeout=120)

# 4. 依赖审计
terminal(command="pip-audit", timeout=60)

# 5. 用 patch 工具自动修复低悬果实
patch(path="src/bad.py", old_string="print(f'debug: {x}')", new_string="")

2.4 自进化机制

1. 质量趋势面板：追踪每次审查的六轴得分，可视化质量变化
2. 高频违规模式库：自动识别项目中最频繁的质量违规，生成团队培训建议
3. 门禁阈值自适应：根据项目成熟度动态调整阈值（新项目宽松，核心模块严格）
4. 自动修复规则积累：将已验证的自动修复模式（如删除 debug print）沉淀为规则