py-refactor

Python リファクタリングオーケストレーター

Python コードの品質を向上させるために、専門スキルを連携させる包括的なリファクタリングワークフローです。

概要

このスキルは、複数の特化したスキルをオーケストレーションし、体系的なリファクタリングを実行します。

スキル	目的	ステータス
py-security	脆弱性の検出と修正	安定
py-code-health	デッドコードと重複の削除	安定
py-complexity	循環的複雑度・認知的複雑度の低減	安定
py-test-quality	カバレッジ分析とミューテーションテスト	安定
py-modernize	ツールと構文のアップグレード	安定
py-quality-setup	リンターと型チェッカーの設定	安定
py-git-hooks	pre-commit フックのセットアップ	安定

リファクタリングの優先順位

影響度に基づいて、次の優先順位に従ってください。

1. 重大：セキュリティの脆弱性（py-security を使用）
2. 高：コードの重複、テストされていないコード（カバレッジ 80% 未満）
3. 中：複雑度の低減、デッドコードの削除
4. 低：構文のモダナイズ、スタイルの改善

標準的なリファクタリングワークフロー

フェーズ 1：セットアップ（必要な場合）

1. If quality tools not configured (pyproject.toml):
   → Invoke: py-quality-setup
   (also configures .claude/settings.local.json permissions for all tools)

2. Add analysis tools to [dependency-groups] dev in pyproject.toml:
   "radon", "vulture", "pylint", "bandit", "lizard",
   "pytest-cov", "mutmut", "wily", "ruff", "mypy", "basedpyright"

3. Install and activate:
   uv sync && source .venv/bin/activate

フェーズ 2：包括的な分析

すべての自動スキャナーを実行して、ベースラインを取得します。

mkdir -p reports

# Security
ruff check . --select S > reports/security.txt
bandit -r . -f json -o reports/security.json

# Code health
vulture . --min-confidence 80 > reports/dead_code.txt
pylint --disable=all --enable=duplicate-code --recursive=y . > reports/duplication.txt

# Complexity
radon cc . -n C -s > reports/complexity.txt
lizard -l python -w > reports/cognitive_complexity.txt
radon mi . -n B > reports/maintainability.txt

# Test quality
pytest --cov=. --cov-report=html --cov-report=term > reports/coverage.txt

# Initialize complexity tracking
wily build .

フェーズ 3：優先順位に沿った修正

ステップ 1：セキュリティ（重大）

If security.txt shows issues:
→ Invoke: py-security
   - Fix SQL injection, hardcoded secrets, weak crypto
   - Verify: ruff check . --select S (clean)
   - Run tests to ensure no regressions

ステップ 2：テスト品質（高 — 安全なリファクタリングを可能にします）

If coverage < 80%:
→ Invoke: py-test-quality
   - Write tests for untested code
   - Run mutation testing to verify test quality
   - Target: ≥80% coverage, ≥75% mutation score

ステップ 3：コードの健全性（高）

If duplication.txt or dead_code.txt show issues:
→ Invoke: py-code-health
   - Remove dead code (vulture findings)
   - Consolidate duplicates (pylint findings)
   - Verify: Tests still pass, coverage maintained

ステップ 4：複雑度の低減（中）

If complexity.txt shows C+ functions or maintainability < 65:
→ Invoke: py-complexity
   - Extract functions, simplify conditionals
   - Use guard clauses, lookup tables
   - Track improvement with wily
   - Verify: radon cc . -n C (clean)

ステップ 5：モダナイズ（任意）

If project uses old patterns or pip:
→ Invoke: py-modernize
   - Migrate pip → uv
   - Upgrade syntax to Python 3.13+
   - Consolidate to pyproject.toml
   - Verify: Tests pass, type checking works

フェーズ 4：自動化

Set up git hooks to prevent regressions:
→ Invoke: py-git-hooks
   - Pre-commit hooks run ruff, mypy, basedpyright
   - Optionally add security checks (bandit)
   - Test hook works correctly

フェーズ 5：最終検証

# Run complete validation suite
ruff check .
mypy . && basedpyright .
ruff check . --select S
radon cc . -n C
vulture . --min-confidence 80
pytest --cov=. --cov-fail-under=80

# Track overall improvement
wily diff HEAD~1
wily report .

このスキルを使用しない場合

次の場合は、オーケストレーションされたリファクタリングを使用しないでください。

• 単一の対象に絞ったタスク：該当するスキルを直接使用してください（例：CVE の修正には py-security のみを使用）
• テストが存在しない：まずテストを作成し（py-test-quality）、その後でリファクタリングしてください
• 開発が進行中：マージコンフリクトを避けるため、チームと調整してください
• 本番環境でのインシデント：まずインシデントに対処し、リファクタリングは後で行ってください

追加リソース

• WORKFLOWS.md：特定のシナリオ（セキュリティの一括チェック、複雑度改善スプリント、レガシーシステムのモダナイズ）向けのクイックワークフロー
• METRICS.md：成功指標、ツールのリファレンス、Engineering Charter との整合性