AIMisc/code-quality-system

代码质量保障系统

一套完整的 Agent + Hook + Skill 组合，让 AI 能够写出更完善的代码。

🎯 核心功能

1. 自动完成检查 (Auto-Complete Hook)

• 拦截 Agent 任务结束，自动检查代码质量
• 检测未完成的功能、TODO、空函数、占位符
• 最多允许 3 次迭代修复
• 未通过时阻止任务完成，生成修复要求

2. 深度质量检查 (Code-Quality Skill)

• 手动触发命令：/code-quality
• 全面检查：功能、代码、测试、文档、规范、安全
• 生成详细的质量报告
• 提供修复建议和自动修复选项

3. 智能通知系统

• Windows 桌面通知
• 声音提醒（成功/警告/注意）
• 异步发送，不阻塞工作流程

📁 文件结构

code-quality-system/
├── hooks/                           # Hook 脚本
│   ├── auto-complete-check.py      # 主检查逻辑
│   ├── requirements-tracker.py     # 需求追踪器
│   ├── code-analyzer.py            # 代码分析器
│   ├── notification-sender.py      # 通知发送器
│   └── requirements.txt            # Python 依赖
├── custom-skills/                   # 自定义技能
│   └── code-quality/
│       ├── skill.json              # 技能定义
│       └── instructions.md         # 技能指令
├── config/                          # 配置文件
│   └── code-quality-config.json    # 系统配置
├── sounds/                          # 声音资源
│   ├── README.md                   # 声音文件说明
│   ├── success.wav                 # 成功提示音
│   ├── warning.wav                 # 警告提示音
│   └── attention.wav               # 注意提示音
├── deploy.bat                       # 一键部署脚本
└── README.md                        # 本文件

🚀 快速开始

方法 1: 使用一键部署脚本（推荐）

1. 双击运行 deploy.bat
2. 选择部署模式：
   • 全局部署：所有项目自动启用
   • 项目部署：仅当前项目启用
3. 重启 Claude Code
4. 完成！

方法 2: 手动部署

全局部署

# 1. 复制文件到 Claude Code 配置目录
cp -r hooks/* ~/.claude/hooks/
cp -r custom-skills/* ~/.claude/custom-skills/
cp config/code-quality-config.json ~/.claude/

# 2. 安装 Python 依赖
pip install plyer pygame

# 3. 配置 settings.json
# 添加以下内容到 ~/.claude/settings.json:
{
  "hooks": {
    "TaskEnd": [
      {
        "type": "command",
        "command": "python ~/.claude/hooks/auto-complete-check.py"
      }
    ]
  }
}

项目部署

# 1. 复制文件到项目目录
cp -r hooks/* .claude/hooks/
cp -r custom-skills/* .claude/custom-skills/
cp config/code-quality-config.json .claude/

# 2. 安装 Python 依赖
pip install plyer pygame

🔧 配置说明

编辑 code-quality-config.json 自定义系统行为：

{
  "enabled": true,                    // 是否启用
  "checkLevel": "standard",          // 检查级别: standard/deep
  "maxIterations": 3,                // 最大迭代次数
  "notification": {
    "enabled": true,                 // 启用通知
    "sound": true,                   // 启用声音
    "desktop": true,                 // 启用桌面通知
    "soundVolume": 0.7               // 音量 (0.0-1.0)
  },
  "thresholds": {
    "passingScore": 80,              // 通过分数
    "warningScore": 60,              // 警告分数
    "maxTodos": 5,                   // 最大 TODO 数量
    "maxEmptyFunctions": 0,          // 最大空函数数量
    "maxPlaceholders": 0             // 最大占位符数量
  }
}

📖 使用方法

自动检查（默认启用）

系统会在以下情况自动触发检查：

• 主 Agent 完成任务时
• 任何子 Agent 完成任务时
• 不需要手动干预

手动检查

使用 /code-quality 命令：

# 标准检查
/code-quality

# 深度检查
/code-quality --deep

# 聚焦特定方面
/code-quality --focus security
/code-quality --focus documentation
/code-quality --focus code-style

工作流程

┌─────────────────┐
│  AI 开始编码    │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  AI 声明完成    │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Hook 拦截      │◄───────────────┐
└────────┬────────┘                │
         │                         │
         ▼                         │
┌─────────────────┐                │
│  执行快速检查   │                │
└────────┬────────┘                │
         │                         │
    ┌────┴────┐                    │
    │         │                    │
   通过❌    通过✅                 │
    │         │                    │
    ▼         ▼                    │
┌─────────┐ ┌──────────┐          │
│迭代+1   │ │允许结束  │          │
└────┬────┘ └──────────┘          │
     │                              │
     ▼                              │
┌─────────┐                         │
│生成修复 │                         │
│要求     │                         │
└────┬────┘                         │
     │                              │
     ▼                              │
┌─────────────────┐                │
│  AI 继续修复    │────────────────┘
└─────────────────┘

🔍 检查维度

1. 功能完整性

• 对比需求清单
• 验证所有功能已实现
• 检查缺失的功能

2. 代码完整性

• 检测 TODO、FIXME
• 检测空函数、占位符
• 检测被注释的代码
• 检测调试语句

3. 代码规范

• 命名规范
• 格式一致性
• 语言特定规范（ESLint、PEP 8、Clippy）
• 项目特定规范

4. 测试覆盖

• 测试文件存在性
• 测试用例数量
• 关键功能测试

5. 文档完整性

• 函数/类注释
• README 文档
• API 文档

6. 安全检查

• SQL 注入风险
• XSS 漏洞
• 硬编码密钥
• 不安全的函数调用

📊 检查报告示例

## 代码质量检查报告

### 总体评分：85/100

### 完成度分析
✅ 用户登录功能 (100%)
✅ 数据库连接 (100%)
⚠️  API 错误处理 (60%) - 缺少部分错误码
❌ 日志记录 (0%) - 未实现

### 代码质量
- TODO: 3 个
- 空函数: 0 个
- 被注释代码: 2 处
- 占位符: 1 个

### 修复建议（按优先级）
1. [高] 实现日志记录模块
2. [高] 补充 API 错误码
3. [中] 清理被注释的代码
4. [低] 处理 TODO 项

🛠️ 故障排除

通知不工作

1. 检查依赖是否安装：

   pip install plyer pygame
   

2. 测试通知：

   python ~/.claude/hooks/notification-sender.py test
   

3. 检查配置文件中的 notification.enabled 是否为 true

Hook 不触发

1. 检查 settings.json 配置是否正确
2. 检查 Python 脚本是否有执行权限
3. 查看 Claude Code 日志：~/.claude/logs/

声音文件缺失

系统会自动使用 Windows 系统 Beep 音效作为回退，不影响功能。

如需自定义声音，参考 sounds/README.md。

📝 卸载

使用部署脚本

1. 运行 deploy.bat
2. 选择"卸载"
3. 选择要卸载的组件（全局/项目）

手动卸载

# 全局部署
rm ~/.claude/hooks/auto-complete-check.py
rm ~/.claude/hooks/requirements-tracker.py
rm ~/.claude/hooks/code-analyzer.py
rm ~/.claude/hooks/notification-sender.py
rm -rf ~/.claude/custom-skills/code-quality
rm ~/.claude/code-quality-config.json

# 项目部署
rm -rf .claude

🤝 贡献

欢迎提交问题和改进建议！

📄 许可

MIT License

🔗 相关资源

• Claude Code 官方文档
• Hook 开发指南 - 项目根目录的 Hook 使用指南
• Superpowers 技能集

---

让 AI 写出更完善的代码！ 🚀