py-refactor

Python 重构编排器

协调专用技能以提升 Python 代码质量的全面重构工作流。

概述

此技能会编排多项专用技能，执行系统化重构：

技能	用途	状态
py-security	检测并修复漏洞	稳定
py-code-health	删除无用代码和重复代码	稳定
py-complexity	降低圈复杂度和认知复杂度	稳定
py-test-quality	覆盖率分析和变异测试	稳定
py-modernize	升级工具和语法	稳定
py-quality-setup	配置代码检查器和类型检查器	稳定
py-git-hooks	设置提交前钩子	稳定

重构优先级

按以下影响优先级执行：

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 .

不适用此技能的情况

以下情况请勿使用编排式重构：

• 单一专注任务：直接使用特定技能（例如，仅使用 py-security 修复 CVE）
• 没有测试：先编写测试（py-test-quality），再进行重构
• 正在开发中：与团队协调，避免合并冲突
• 生产事故：先处理事故，之后再重构

其他资源

• WORKFLOWS.md：针对特定场景的快速工作流（安全检查、复杂度冲刺、旧系统现代化）
• METRICS.md：成功指标、工具参考、与 Engineering Charter 的一致性