refactor-expert
Guide safe, incremental refactoring that improves code quality without changing behavior.
Best use case
refactor-expert is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
Guide safe, incremental refactoring that improves code quality without changing behavior.
Teams using refactor-expert should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/refactor-expert/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How refactor-expert Compares
| Feature / Agent | refactor-expert | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
Guide safe, incremental refactoring that improves code quality without changing behavior.
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
Related Guides
SKILL.md Source
> **AI-consumed reference.** Optimized for Claude to read during execution.
> Human-readable explanation: see [docs/architecture/HIERARCHICAL_PLANNING.md](../../../docs/architecture/HIERARCHICAL_PLANNING.md)
> or [docs/getting-started/](../../../docs/getting-started/) depending on topic.
# Skill: Refactor Expert
Safe, incremental refactoring. Improve quality without changing behavior.
---
## Commands
| Command | Output |
|---------|--------|
| `refactor:analyze <file>` | `.claude/logs/refactors/{target}-analysis.md` |
| `refactor:plan <file>` | `.claude/logs/refactors/{target}-plan.md` |
| `refactor:docs <file>` | Analysis + Plan + Summary |
| `refactor:quick <file>` | Skip approvals |
| `refactor:performance <file>` | Performance-focused |
| `refactor:structure <file>` | Structure-focused |
---
## Decision
| Signal | Action |
|--------|--------|
| Code smell detected | Identify specific smell |
| Tests passing | Safe to refactor |
| No tests | Write tests FIRST |
| Large change | Break into small steps |
**Golden Rule:** Never refactor and add features simultaneously.
---
## Code Smells -> Refactoring
| Smell | Refactoring |
|-------|-------------|
| Long Method | Extract Method |
| Large Class | Extract Class |
| Long Parameter List | Parameter Object |
| Duplicate Code | Extract Method/Class |
| Feature Envy | Move Method |
| Primitive Obsession | Replace with Object |
| Switch Statements | Polymorphism |
| Dead Code | Delete it |
---
## Safe Process
```
1. Ensure tests pass
2. ONE small change
3. Run tests
4. Commit
5. Repeat
```
Never multiple changes between test runs.
---
## Checklist
**Before:** Tests exist and pass, understand current behavior, identify smell.
**During:** One change at a time, test after each, commit frequently.
**After:** All tests pass, code cleaner, behavior unchanged.
---
## Related Rules
- `rules/core/simplicity-over-complexity.md` — the point of refactoring: Rule of 3 before abstracting, delete before extracting, flatten before nesting
- `rules/core/tdd-workflow.md` — refactor only when tests are green
- `rules/core/verification.md` — tests must still pass after every step
- `rules/workflow/cross-review-workflow.md` — refactorer ≠ reviewer
- `skills/code-simplifier/SKILL.md` — companion skill for pure simplification passes
---Related Skills
vue-expert
Vue 3 gotchas and decision criteria. Covers reactivity traps, Composition API pitfalls, and Pinia patterns.
typescript-expert
TypeScript gotchas and decision criteria covering nullish coalescing pitfalls (|| vs ??), strict tsconfig settings (noUncheckedIndexedAccess, exactOptionalPropertyTypes), type guard patterns, discriminated unions, and as const vs enum. Use when writing TypeScript, configuring tsconfig, implementing type guards, or debugging null/undefined errors.
react-native-expert
React Native gotchas and decision criteria. Covers FlatList optimization, storage hierarchy, and platform-specific pitfalls.
react-expert
React gotchas and decision criteria covering stale closure bugs in useEffect, conditional rendering traps (falsy 0/empty string), state management selection (useState vs Context vs Zustand vs TanStack Query), and hooks rules. Use when writing React components, debugging re-renders, choosing state management, or encountering useEffect infinite loops.
python-expert
Python gotchas and decision criteria. Covers async pitfalls, FastAPI/Django patterns, and type hint traps.
nodejs-expert
Node.js gotchas and decision criteria. Covers async pitfalls, Express/NestJS patterns, and common mistakes.
nextjs-expert
Next.js 14+ gotchas and decision criteria. Covers server/client boundary, caching strategy, and data fetching patterns Claude commonly gets wrong.
laravel-expert
Laravel/PHP gotchas and decision criteria. Covers N+1 prevention, Eloquent traps, and migration safety.
go-expert
Go gotchas and decision criteria. Covers error handling patterns, concurrency pitfalls, and interface design.
design-expert
UI/UX design expertise — component design, design system selection, responsive layout. Includes auto-detection from package.json and Context7 integration for library docs.
angular-expert
Angular 17+ gotchas and decision criteria. Covers signals vs observables, standalone patterns, and common pitfalls Claude gets wrong.
tree-of-thoughts
Branch, evaluate, prune, expand — structured search over solution space. Use for architecture with multi-step decisions, refactor planning, or complex debug hypothesis trees. Paper: Yao et al. 2023.