refactoring-assistant
Assists with code refactoring by detecting code smells, suggesting improvements, and providing refactoring patterns. Activates when writing/editing code, explicitly requested refactoring, or when code quality issues are detected. Maintains awareness of core principles while providing detailed patterns and examples.
When & Why to Use This Skill
The Refactoring Assistant is a specialized Claude skill designed to systematically improve code quality and maintainability. It proactively identifies 'code smells'—such as long methods, deep nesting, and duplicated logic—and provides actionable refactoring patterns. By integrating tech-stack specific best practices for environments like TypeScript, React, and Go, it helps developers reduce technical debt and ensure long-term project scalability through automated detection and guided implementation.
Use Cases
- Technical Debt Mitigation: Automatically scanning legacy modules to identify and break down 'God Objects' or overly complex functions into manageable, testable components.
- Real-time Coding Standards Enforcement: Providing immediate feedback during the development process when code exceeds complexity thresholds, such as excessive nesting or parameter counts.
- Tech-Stack Specific Optimization: Applying specialized patterns for modern frameworks, such as optimizing React hooks or refining Go interface designs to improve performance and readability.
- Pre-merge Quality Assurance: Serving as an automated first-pass code reviewer to catch common architectural issues before human review, ensuring a higher standard of submitted pull requests.
| name | refactoring-assistant |
|---|---|
| description | Assists with code refactoring by detecting code smells, suggesting improvements, and providing refactoring patterns. Activates when writing/editing code, explicitly requested refactoring, or when code quality issues are detected. Maintains awareness of core principles while providing detailed patterns and examples. |
| allowed-tools | [Read, Grep, Glob, AskUserQuestion] |
Refactoring Assistant Skill
Purpose
Support code quality improvement through:
- Automatic code smell detection during development
- Suggesting appropriate refactoring patterns
- Providing tech-stack specific best practices
- Maintaining code consistency and readability
Activation Triggers
Automatic Activation
- When writing or editing source code files
- When file length exceeds thresholds
- When code duplication is detected
- When complex nesting is identified
Manual Activation
- User says "リファクタリング", "refactor", "code smell"
- User asks about code quality improvement
- User requests design pattern suggestions
Core Principles (Always Active)
These principles are always kept in mind during coding, regardless of Skill activation.
Code Smells to Detect
Long Method (関数が長すぎる)
- Threshold: > 50 lines
- Action: Suggest extraction into smaller functions
Duplicate Code (重複コード)
- Threshold: Same code appears 3+ times
- Action: Extract to shared function/constant
Deep Nesting (ネストが深すぎる)
- Threshold: > 3 levels
- Action: Use early return, extract conditions
Long Parameter List (引数が多すぎる)
- Threshold: > 5 parameters
- Action: Use structured parameters (RORO pattern in TS, struct in Go)
Large Class/Module (クラス/モジュールが大きすぎる)
- Threshold: > 300 lines
- Action: Split into smaller modules
Complex Conditional (複雑な条件式)
- Threshold: > 3 conditions in single expression
- Action: Extract to named function/variable
Workflow
Phase 1: Detection
Read the code
- Use Read tool to examine target files
- Identify patterns matching code smells
Measure complexity
- Count lines in functions
- Count nesting levels
- Count parameters
- Detect duplication patterns
Prioritize issues
- Critical: Security risks, bugs
- High: Code smells affecting readability
- Medium: Minor style inconsistencies
Phase 2: Analysis
Check against tech-stack rules
- TypeScript/React: Refer to
patterns/typescript-react.md - Go: Refer to
patterns/go.md
- TypeScript/React: Refer to
Consider context
- Is this a one-time case or recurring pattern?
- Is the complexity justified by business logic?
- Would refactoring improve or harm clarity?
Review existing patterns
- Check
~/.claude/knowledge/patterns/for similar cases - Ensure consistency with project CLAUDE.md
- Check
Phase 3: Suggestion
Present findings
- List detected code smells with severity
- Show specific locations (file:line)
- Explain why it's a problem
Propose solutions
- Suggest appropriate refactoring pattern
- Show before/after code examples
- Explain benefits and trade-offs
Ask for approval
- Use AskUserQuestion for user decision
- Allow partial acceptance (fix some, not all)
Phase 4: Implementation
Apply refactoring
- Make changes incrementally
- Maintain backward compatibility if needed
- Update tests accordingly
Verify quality
- Ensure tests still pass
- Run linter if available
- Check for new code smells
Document if needed
- If this is a new pattern, suggest recording to Knowledge Base
- Update project CLAUDE.md if this establishes new standard
Code Smell Detection Details
Refer to rules/code-smells.md for detailed detection criteria and refactoring patterns for each code smell.
Tech-Stack Specific Patterns
TypeScript/React
See patterns/typescript-react.md for:
- React component refactoring patterns
- Hook extraction and optimization
- State management improvements
- CSS Modules organization
Go
See patterns/go.md for:
- Function extraction patterns
- Interface design improvements
- Error handling refactoring
- Goroutine and channel optimization
Integration with Knowledge Base
When discovering new refactoring patterns or solutions:
Record to Knowledge Base
- Use knowledge-manager Skill to document
- Category:
patterns/refactoring-{tech-stack}.md
Update INDEX
- Ensure pattern is searchable
- Add relevant tags and categories
Guardrails
When NOT to Refactor
- Working on tight deadline - Defer to post-release
- No test coverage - Write tests first
- Unclear requirements - Clarify before refactoring
- Code is working and stable - If it ain't broke, consider carefully
Safety Checks
- Always run tests before and after refactoring
- Make small, incremental changes - easier to review and rollback
- Preserve behavior - refactoring should not change functionality
- Document breaking changes if unavoidable
Usage Tips
For User
- This Skill helps detect code smells, but core principles remain in Global CLAUDE.md
- You should always be aware of basic refactoring principles during coding
- Use this Skill for detailed patterns and examples, not just principles
For Claude
- Always keep core principles in mind regardless of Skill activation
- Don't wait for explicit "refactor" request - suggest improvements during normal coding
- Balance between code quality and practical constraints
- Prefer incremental improvements over massive rewrites
Supporting Files
rules/code-smells.md: Detailed code smell detection and refactoring patternspatterns/typescript-react.md: TypeScript/React specific refactoring patternspatterns/go.md: Go specific refactoring patterns~/.claude/knowledge/patterns/: Real-world refactoring examples
Maintenance
Update this Skill when:
- New code smells are discovered
- New refactoring patterns are established
- Tech-stack best practices evolve
- Team coding standards change