A comprehensive refactoring opportunity scanner for Claude Code that identifies code complexity, duplication, design patterns, code smells, modernization opportunities, and architecture debt using specialized AI agents.
- Code Complexity Analysis - Cyclomatic/cognitive complexity, nesting depth, method/class length
- Duplication Detection - Copy-paste code, similar patterns, DRY violations
- Design Pattern Opportunities - Factory, Strategy, Observer, Decorator, Builder patterns
- Code Smell Detection - All Martin Fowler's classic code smells
- Modernization Suggestions - Legacy patterns to modern alternatives
- Architecture Debt Analysis - Circular dependencies, coupling, layer violations
- Claude Code CLI installed and configured
- A project to scan
- Clone or download this repository
- Copy the folders to your project's
.claude/directory:
# From your project root
cp -r path/to/claude-code-refactor-scan/commands .claude/
cp -r path/to/claude-code-refactor-scan/refactor .claude/Your project structure should look like:
your-project/
├── .claude/
│ ├── commands/
│ │ └── refactor-scan.md
│ └── refactor/
│ ├── agents/
│ │ ├── complexity.md
│ │ ├── duplication.md
│ │ ├── patterns.md
│ │ ├── code-smells.md
│ │ ├── modernization.md
│ │ └── architecture-debt.md
│ └── templates/
│ └── refactor-report.md
├── src/
└── ...
- (Optional) Add
refactor-reports/to your.gitignore:
echo "refactor-reports/" >> .gitignoreAfter installation, you can optimize the refactor scanner for your specific codebase. This improves detection accuracy by focusing on patterns and idioms specific to your frameworks.
Run this prompt in Claude Code:
I just installed the refactor-scan command in .claude/. Please:
1. Analyze my codebase to detect my tech stack (language, frameworks, design patterns in use)
2. Read the command files in .claude/commands/refactor-scan.md and .claude/refactor/agents/
3. Optimize each refactor agent by:
- Removing patterns for languages/frameworks I don't use
- Adding modernization suggestions specific to my framework versions
- Detecting my project's existing design patterns to suggest consistent improvements
- Adjusting complexity thresholds based on my codebase conventions
4. Keep the agent structure, refactoring categories, and output format unchanged
Show me what you'll change before applying.
In Claude Code, run the refactor scan command:
/refactor-scan
| Command | Description |
|---|---|
/refactor-scan |
Full scan (all refactoring checks) |
/refactor-scan quick |
High-priority issues only (faster) |
/refactor-scan complexity |
Only code complexity analysis |
/refactor-scan duplication |
Only duplication detection |
/refactor-scan patterns |
Only design pattern opportunities |
/refactor-scan modernize |
Only modernization suggestions |
/refactor-scan debt |
Only architecture debt analysis |
/refactor-scan extract |
Focus on extract method/class opportunities |
| Issue | Description | Priority |
|---|---|---|
| Cyclomatic Complexity | Functions with complexity > 10 | High |
| Cognitive Complexity | Hard-to-understand logic | High |
| Deep Nesting | Conditionals nested > 3 levels | Medium |
| Long Methods | Methods > 50 lines | Medium |
| Long Classes | Classes > 500 lines | Medium |
| Long Parameter Lists | Functions with > 4 parameters | Medium |
| Issue | Description | Priority |
|---|---|---|
| Clone Blocks | Similar code blocks > 10 lines | High |
| Logic Duplication | Same logic with minor variations | High |
| Pattern Repetition | Repeated patterns across files | Medium |
| Config Duplication | Duplicate constants/configs | Low |
| Pattern | When to Apply | Priority |
|---|---|---|
| Factory | Multiple object creation logic | Medium |
| Strategy | Multiple algorithm variations | High |
| Observer | Event-driven communication | Medium |
| Decorator | Dynamic behavior addition | Medium |
| Builder | Complex object construction | Medium |
| Repository | Data access abstraction | High |
| Smell | Description | Priority |
|---|---|---|
| Feature Envy | Method uses other class more than its own | High |
| Data Clumps | Same data groups appear together | Medium |
| Primitive Obsession | Overuse of primitives vs objects | Medium |
| Long Parameter List | Too many function parameters | Medium |
| Divergent Change | One class changed for different reasons | High |
| Shotgun Surgery | One change requires many class edits | High |
| Dead Code | Unused code | Low |
| Legacy Pattern | Modern Alternative | Priority |
|---|---|---|
| Callbacks | async/await | High |
| var declarations | const/let | Medium |
| Class Components | Functional Components (React) | Medium |
| Deprecated APIs | Modern alternatives | High |
| Old Syntax | ES6+ features | Low |
| Issue | Description | Priority |
|---|---|---|
| Circular Dependencies | Modules depending on each other | Critical |
| God Classes | Classes doing too much | High |
| Layer Violations | Skipping architectural layers | High |
| Tight Coupling | Hard dependencies on implementations | Medium |
| Missing Abstractions | No interfaces for dependencies | Medium |
- Tech Stack Detection - Automatically detects your frameworks and patterns
- Agent Execution - Spawns specialized agents for each refactoring domain
- Finding Collection - Aggregates findings with effort estimates
- Report Generation - Creates a markdown report in
refactor-reports/ - Refactor Mode - Optionally offers to apply refactorings
Reports are saved to refactor-reports/YYYY-MM-DD-HHmm-scan.md with:
- Executive Summary (refactoring score 0-100)
- Quick Wins (low effort, high impact)
- Major Refactors (high effort, prioritized)
- Technical Debt Register
- Prioritized Refactoring Plan
- Estimated Effort
- Risk Assessment
- Before/After Code Examples
The scanner auto-detects and adapts to:
Languages:
- TypeScript/JavaScript
- Python
- PHP
- C#/.NET
- Go
- Java
- Rust
Frontend:
- React, Angular, Vue, Svelte, Next.js
Backend:
- Node.js (Express, NestJS, Fastify)
- Django, Flask, FastAPI
- Laravel, Symfony
- ASP.NET Core
- Spring Boot
- Gin, Echo
To adapt for your specific needs:
- Tech stack detection - Modify Step 1 in
refactor-scan.md - Agent behavior - Edit individual agents in
refactor/agents/ - Report format - Modify
refactor/templates/refactor-report.md - Thresholds - Adjust complexity/length limits in agent files
Contributions welcome! Please:
- Fork the repository
- Create a feature branch
- Submit a pull request
MIT License - see LICENSE file.
This tool performs static analysis and pattern matching. It provides suggestions based on common best practices but may not be applicable to all contexts. Always apply engineering judgment when refactoring.
- Refactoring: Improving the Design of Existing Code - Martin Fowler
- Clean Code - Robert C. Martin
- Design Patterns - Gang of Four
- Claude Code Documentation