verify-quality

コード品質の検証

目的

命名の不適切さ、ドキュメントの不足、マジック値、構成上の問題など、コード品質に関するアンチパターンを検証します。すべての分析はローカルで実行されます。

使用するタイミング

ユーザーが次のように依頼したときに、このスキルを起動します。

• 「エージェントの品質を検証して」
• 「品質を検証して」
• 「コード品質をチェックして」
• 「コードの構成をレビューして」
• 「命名規則をチェックして」

注： セキュリティ、パターン、言語固有のチェックを含む完全な検証を行うには、**「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] 命名規則

次の項目を確認します。

問題	例
（ループを除く）1文字の変数名	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] ドキュメント

次の項目を確認します。

不足しているもの	想定される場所
モジュールのdocstring	.pyファイルの先頭
クラスのdocstring	class定義の直後
関数のdocstring	パブリック関数の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」と言ってください。