Expert Python backend code reviewer that identifies over-complexity, duplicates, bad optimizations, and violations of best practices...
Expert analysis and refactoring of Python backend code to eliminate duplication, reduce complexity, and enforce best practices.
This skill helps identify and fix common issues in Python backend code, particularly problems introduced by AI code generation:
The skill provides automated analysis tools and comprehensive refactoring guidance.
Static analysis finds issues, but architectural context determines priority.
Before prioritizing fixes, identify:
Critical paths: Which code runs on every request?
Secondary paths: Less critical code
Concurrency model: How is state shared?
Prioritization rule: Correctness in critical paths > Complexity in secondary paths
| Finding | Critical Path | Secondary Path |
|---|---|---|
| Shared state mutation | 🔴 Fix immediately | 🟡 Review |
| High complexity (>25) | 🟡 Refactor carefully | 🟢 Backlog |
| Duplicates | 🟡 Extract if >3 occurrences | 🟢 Nice to have |
| God class | 🟡 Migrate to façade | 🟢 Low priority |
For orchestration/workflow code, use realistic thresholds:
| Metric | Strict Threshold | Pragmatic Threshold | Notes |
|---|---|---|---|
| Cyclomatic complexity | 10 | 25 | Orchestrators naturally have decision points |
| Function length | 50 lines | 150 lines | Async flows can be longer |
| Nesting depth | 4 | 5 | Guard clauses help more than extracting |
| God class methods | 20 | N/A | OK if it's a façade that delegates |
Hard limits (always fix):
Start with automated tools to identify issues:
# Detect duplicate code blocks
uv run python scripts/detect_duplicates.py <path>
# Analyze imports and utility reimplementation
uv run python scripts/analyze_imports.py <path>
# Check code complexity
uv run python scripts/complexity_analyzer.py <path>
# Check for concurrency issues (shared state mutation)
uv run python scripts/concurrency_analyzer.py <path>
Each tool outputs:
Use the reference guides to refactor issues:
When a user asks to review a specific file:
Run all analysis tools on the file:
python scripts/detect_duplicates.py path/to/file.py
python scripts/analyze_imports.py path/to/file.py
python scripts/complexity_analyzer.py path/to/file.py
Analyze results and categorize issues:
Provide specific fixes:
Offer to implement fixes if requested
When a user asks to check a project/module for duplicates:
Run duplicate detection on the entire directory:
python scripts/detect_duplicates.py src/
Group duplicates by severity:
Recommend consolidation strategy:
When code appears over-engineered:
Run complexity analysis:
python scripts/complexity_analyzer.py --max-complexity 10 --max-length 50 path/
Identify over-engineering patterns:
Suggest simplifications:
Reference specific patterns from python_antipatterns.md
When asked to optimize code or ensure best practices:
Run all analysis tools to get baseline metrics
Check against best practices:
Prioritize optimizations:
Reference best_practices.md for specific guidelines
When reviewing async code that handles concurrent requests:
Run concurrency analysis:
uv run python scripts/concurrency_analyzer.py services/ workflows/
Prioritize by severity:
Common fixes for shared state mutation:
# ❌ Before: Mutating shared instance state
class Workflow:
async def run(self, task):
self.current_task = task # Race condition!
# ✅ After: Request-scoped state
class Workflow:
async def run(self, task):
execution = ExecutionContext(task=task)
return await self._execute(execution)
Alternative patterns:
contextvars for request-scoped dataasyncio.Lock for truly shared stateFinds duplicate code blocks using AST analysis.
Usage:
uv run python scripts/detect_duplicates.py <path>
uv run python scripts/detect_duplicates.py --min-lines 10 <path>
Detects:
Options:
--min-lines N: Minimum lines for a block to be considered (default: 5)Analyzes import organization and detects recreated utilities.
Usage:
uv run python scripts/analyze_imports.py <path>
Detects:
from module import *)Common utilities flagged:
json or orjsontenacity or backoffpydanticrequests or httpxMeasures cyclomatic complexity, function length, and nesting depth.
Usage:
uv run python scripts/complexity_analyzer.py <path>
uv run python scripts/complexity_analyzer.py --max-complexity 10 --max-length 50 <path>
Metrics:
Options:
--max-complexity N: Cyclomatic complexity threshold (default: 10)--max-length N: Function length threshold (default: 50)Detects concurrency issues in async Python code.
Usage:
uv run python scripts/concurrency_analyzer.py <path>
Detects:
self.x = y in async def)Severity levels:
client, session, agent, configself.attr mutation in async contextWhen to use: Run on services, handlers, and workflow code that handles concurrent requests.
Comprehensive catalog of anti-patterns with examples:
Use when: You identify an issue but need to see the anti-pattern and solution
Step-by-step refactoring techniques:
Use when: You know what's wrong and need concrete refactoring steps
Python backend best practices and principles:
Use when: Establishing coding standards or need authoritative guidance
User request: "Review this code for quality issues"
Analysis:
uv run python scripts/detect_duplicates.py api/
Finding: Email validation duplicated in 5 files
Recommendation:
# Extract to utils/validation.py
def validate_email(email: str) -> None:
if not email or "@" not in email:
raise ValueError("Invalid email")
# Import everywhere
from utils.validation import validate_email
User request: "Check if we're recreating utility functions"
Analysis:
uv run python scripts/analyze_imports.py services/
Finding: Custom retry logic in 3 services
Recommendation:
# Replace with tenacity
from tenacity import retry, stop_after_attempt, wait_exponential
@retry(stop=stop_after_attempt(3), wait=wait_exponential())
async def fetch_data(url: str):
return await client.get(url)
User request: "This function is hard to understand"
Analysis:
uv run python scripts/complexity_analyzer.py utils/processor.py
Finding: Complexity 23, nesting depth 6
Recommendation: Extract nested logic into helper functions (see refactoring_patterns.md)
⚠️ Avoid refactoring when:
When reviewing code, structure feedback as:
Always include:
