verify-quality

代码质量验证

用途

检查代码中的质量反模式，包括命名不佳、缺少文档、魔法值和组织结构问题。所有分析均在本地进行。

适用场景

用户提出以下请求时，触发此技能：

• “验证 Agent 质量”
• “验证质量”
• “检查代码质量”
• “审查代码组织结构”
• “检查命名规范”

注意： 如需完整验证（包括安全性、模式和特定语言的检查），请告诉用户说 “verify agent”。

流程

步骤 1：发现文件

定位要分析的文件：

源文件：

• *.py、*.ts、*.js、*.go、*.rs — 源代码
• 重点检查主要实现文件，而非测试文件

要检查的目录：

• src/、lib/、app/、项目根目录
• agent/、tools/、utils/

排除：

• node_modules/、.venv/、venv/、__pycache__/
• 测试文件（*.test.*、*.spec.*、*_test.go）
• 生成的文件、迁移文件

步骤 2：运行质量检查

此技能中的所有检查均为 [HEURISTIC] — 需要判断。请使用 [H] 标记发现的问题。

---

2.1 [HEURISTIC] 命名规范

检查以下问题：

问题	示例
单字母变量（循环变量除外）	x = get_data()、d = {}
含义不清的缩写	proc_usr_req()、calc_val()
大小写风格不一致	同一文件中混用 camelCase 和 snake_case
名称未能说明用途	data、temp、result、info
布尔变量名称不含 is/has/can	enabled = check() 与 is_enabled = check()

良好的命名：

# ✅ Clear, descriptive
user_profile = get_user_profile(user_id)
is_authenticated = check_authentication(token)
max_retry_attempts = 3

# ⚠️ Unclear
x = get_up(uid)
auth = check(t)
n = 3

严重程度：⚠️ 警告

---

2.2 [HEURISTIC] 代码组织结构

检查以下问题：

问题	描述
文件过大	单个模块超过 500 行
函数过大	单个函数超过 50 行
嵌套过深	缩进超过 4 层
关注点混杂	同一函数中将业务逻辑与 I/O 混在一起
上帝对象	类包含超过 10 个公共方法或超过 20 个属性

问题示例：

# ⚠️ Warning - Deep nesting
def process(data):
    if condition1:
        if condition2:
            for item in items:
                if condition3:
                    if condition4:  # Too deep
                        ...

# ⚠️ Warning - Mixed concerns
def save_user(user):
    # Validation
    if not user.email:
        raise ValueError("...")
    # Business logic
    user.created_at = datetime.now()
    # Database I/O
    db.session.add(user)
    db.session.commit()
    # Email sending
    send_welcome_email(user)  # Multiple concerns

严重程度：⚠️ 警告

---

2.3 [HEURISTIC] 魔法数字和字符串

检查以下问题：

• 代码中未使用常量的数字字面量
• 多次重复出现的字符串字面量
• 硬编码在逻辑中的配置值

示例：

# ⚠️ Warning - Magic numbers
if retry_count > 3:  # What does 3 mean?
    ...
time.sleep(60)  # Why 60?

# ⚠️ Warning - Repeated strings
if status == "pending":
    ...
elif status == "pending":  # Typo risk
    ...

# ✅ Good - Named constants
MAX_RETRIES = 3
RETRY_DELAY_SECONDS = 60
STATUS_PENDING = "pending"

if retry_count > MAX_RETRIES:
    ...
time.sleep(RETRY_DELAY_SECONDS)

严重程度：⚠️ 警告

---

2.4 [HEURISTIC] 文档

检查以下缺失项：

缺失项	预期位置
模块文档字符串	.py 文件顶部
类文档字符串	class 定义之后
函数文档字符串	公共函数的 def 之后
README	项目根目录
类型提示	公共函数的参数和返回值

示例：

# ⚠️ Warning - Missing docstrings
def calculate_score(user, items, weights):
    total = 0
    for item, weight in zip(items, weights):
        total += item.value * weight
    return total

# ✅ Good - Documented
def calculate_score(user: User, items: list[Item], weights: list[float]) -> float:
    """
    Calculate weighted score for a user's items.
    
    Args:
        user: The user to calculate score for
        items: List of items to score
        weights: Weight multipliers for each item
        
    Returns:
        Total weighted score
    """
    ...

严重程度：⚠️ 警告

---

2.5 [HEURISTIC] 错误处理

检查以下问题：

问题	描述
裸 except	未指定具体异常的 except:
静默失败	except: pass
引发通用异常	raise Exception("...")
缺少错误处理	可能失败但未处理错误的函数

示例：

# ⚠️ Warning - Bare except
try:
    process_data()
except:
    pass

# ⚠️ Warning - Generic exception
raise Exception("Something went wrong")

# ✅ Good - Specific handling
try:
    process_data()
except ValueError as e:
    logger.warning(f"Invalid data: {e}")
    return default_value
except ConnectionError as e:
    logger.error(f"Connection failed: {e}")
    raise ServiceUnavailableError from e

严重程度：⚠️ 警告

---

2.6 [HEURISTIC] 代码重复

检查以下问题：

• 相同或近乎相同的代码块（超过 5 行）
• 仅有细微差异的复制粘贴函数
• 可抽象提取的重复模式

示例：

# ⚠️ Warning - Duplication
def get_user_by_id(user_id):
    response = requests.get(f"{BASE_URL}/users/{user_id}")
    if response.status_code == 200:
        return response.json()
    return None

def get_order_by_id(order_id):
    response = requests.get(f"{BASE_URL}/orders/{order_id}")
    if response.status_code == 200:
        return response.json()
    return None

# ✅ Good - Abstracted
def get_resource(resource_type: str, resource_id: str):
    response = requests.get(f"{BASE_URL}/{resource_type}/{resource_id}")
    if response.status_code == 200:
        return response.json()
    return None

严重程度：⚠️ 警告

---

2.7 [HEURISTIC] 注释掉的代码

检查以下问题：

• 大段注释掉的代码（超过 5 行）
• 过时的 TODO 注释（若有日期，则已过去数月）
• 表明已知问题的 FIXME 注释

示例：

# ⚠️ Warning - Commented code should be removed
# def old_implementation():
#     for item in items:
#         process_item(item)
#     return results

# ⚠️ Warning - Stale TODO
# TODO: Fix this before launch (added 2024-01-15)

# ✅ Acceptable - Brief explanatory comment
# Note: Using legacy API format for backwards compatibility

严重程度：⚠️ 警告

---

步骤 3：生成报告

# Code Quality Verification Report

**Project:** [name or path]
**Date:** [current date]
**Files analyzed:** [count]

## Summary

✅ X checks passed | ⚠️ Y warnings | ❌ Z issues

## Naming

- [x] Naming conventions consistent
- [ ] ⚠️ Unclear names at `[file:line]`

## Organization

- [x] Code well-organized
- [ ] ⚠️ Large function at `[file:line]` ([X] lines)

## Documentation

- [x] Key functions documented
- [ ] ⚠️ Missing docstring at `[file:line]`

## Error Handling

- [x] Errors properly handled
- [ ] ⚠️ Bare except at `[file:line]`

## Findings

> `[H]` = heuristic (all quality checks require judgment)

### ✅ Passing
- `[H]` Consistent naming conventions throughout
- `[H]` Functions are well-scoped and focused

### ⚠️ Warnings
- `[H]` [Check]: [description]
  - **Location:** [file:line]
  - **Impact:** [why this matters]
  - **Suggestion:** [how to improve]

## Recommendations

1. [Priority recommendation]
2. [Additional improvements]

---

如需完整验证（包括安全性、模式和特定语言的检查），请说 “verify agent”。