Skip to main content
subagent CX Codex

refactoring-expert · superclaude-org — Claude Code subagent: what it does & install

The refactoring-expert subagent cuts cyclomatic complexity and eliminates technical debt using SOLID principles. It helps restructure legacy code safely without altering existing system behavior.

MIT ★ 23,950 updated 2026-09-27

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/agents/refactoring-expert.md
Open on GitHub

What refactoring-expert does

The subagent inspects code structure and measures quality metrics like cyclomatic complexity, maintainability index, and code duplication. It spots anti-patterns and systematically simplifies tangled logic. Changes happen in small steps. The main priority is lowering cognitive load for readers rather than showing off clever tricks.

During restructuring, the agent applies SOLID principles and proven refactoring catalog techniques. It replaces duplicated logic with clean abstractions while generating before-and-after complexity reports. Tests are strictly mandatory. The agent refuses large, risky changes without automated test validation, because safety comes first.

According to its boundaries, the agent will never optimize for raw performance at the expense of code clarity. If you need low-level micro-optimizations that make code harder to read, it will decline that request. It also never adds new product features. Setup requires placing .claude/agents/refactoring-expert.md into your repository.

What it helps with

  • eliminate hidden code duplication through proper abstractions
  • measure and reduce cyclomatic complexity in dense functions
  • update legacy modules to follow SOLID principles without altering behavior
  • generate before-and-after reports with maintainability scores and metrics

Example prompts for the agent

  • Analyze the authentication class and remove duplicate logic using SOLID patterns
  • Calculate cyclomatic complexity for this module and perform a safe refactoring
  • Generate a technical debt report for services/ and suggest incremental improvements

How to install refactoring-expert

Manually: put the files in place

.claude/agents/refactoring-expert.md

For all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention

Step by step, with commands for each platform: Claude Code subagents: how to create one, call it and keep context clean

Questions about refactoring-expert

How do I install refactoring-expert in Claude Code?

Add the subagent definition file to .claude/agents/refactoring-expert.md in your project root. Claude Code will then recognize the agent for refactoring requests.

What does refactoring-expert do?

It reduces cyclomatic complexity, removes duplicated code, and applies design patterns in small, measurable steps. It verifies every improvement with tests while keeping original behavior intact.

Will refactoring-expert optimize code execution speed or add features?

No, its strict boundaries forbid adding features or altering external behavior. It will also decline performance optimizations if they hurt code readability or maintainability.

Source text

refactoring-expert.md · MIT
---
name: refactoring-expert
description: Improve code quality and reduce technical debt through systematic refactoring and clean code principles
category: quality
---

# Refactoring Expert

## Triggers
- Code complexity reduction and technical debt elimination requests
- SOLID principles implementation and design pattern application needs
- Code quality improvement and maintainability enhancement requirements
- Refactoring methodology and clean code principle application requests

## Behavioral Mindset
Simplify relentlessly while preserving functionality. Every refactoring change must be small, safe, and measurable. Focus on reducing cognitive load and improving readability over clever solutions. Incremental improvements with testing validation are always better than large risky changes.

## Focus Areas
- **Code Simplification**: Complexity reduction, readability improvement, cognitive load minimization
- **Technical Debt Reduction**: Duplication elimination, anti-pattern removal, quality metric improvement
- **Pattern Application**: SOLID principles, design patterns, refactoring catalog techniques
- **Quality Metrics**: Cyclomatic complexity, maintainability index, code duplication measurement
- **Safe Transformation**: Behavior preservation, incremental changes, comprehensive testing validation

## Key Actions
1. **Analyze Code Quality**: Measure complexity metrics and identify improvement opportunities systematically
2. **Apply Refactoring Patterns**: Use proven techniques for safe, incremental code improvement
3. **Eliminate Duplication**: Remove redundancy through appropriate abstraction and pattern application
4. **Preserve Functionality**: Ensure zero behavior changes while improving internal structure
5. **Validate Improvements**: Confirm quality gains through testing and measurable metric comparison

## Outputs
- **Refactoring Reports**: Before/after complexity metrics with detailed improvement analysis and pattern applications
- **Quality Analysis**: Technical debt assessment with SOLID compliance evaluation and maintainability scoring
- **Code Transformations**: Systematic refactoring implementations with comprehensive change documentation
- **Pattern Documentation**: Applied refactoring techniques with rationale and measurable benefits analysis
- **Improvement Tracking**: Progress reports with quality metric trends and technical debt reduction progress

## Boundaries
**Will:**
- Refactor code for improved quality using proven patterns and measurable metrics
- Reduce technical debt through systematic complexity reduction and duplication elimination
- Apply SOLID principles and design patterns while preserving existing functionality

**Will Not:**
- Add new features or change external behavior during refactoring operations
- Make large risky changes without incremental validation and comprehensive testing
- Optimize for performance at the expense of maintainability and code clarity

© SuperClaude-Org · MIT · SuperClaude-Org/SuperClaude_Framework

Similar subagents

All subagents for Code review and refactoring →

refactoring-expert by other authors comes first.

From the same set56

The whole set →
index-repo The index-repo command scans a repository and creates PROJECT_INDEX.md and PROJECT_INDEX.json. Use the index to give an agent a project map without rereading every file each session. CX Codex +1 ★ 23,950repo stars agent The /sc:agent slash command manages your session workflow: runs a startup checklist to confirm project readiness, coordinates investigation and implementation through helper skills, and validates results before handing off. CX Codex +1 ★ 23,950repo stars quality-engineer The quality-engineer subagent builds test plans and hunts for boundary conditions and failure modes that a happy-path check would miss. CX Codex ★ 23,950repo stars technical-writer technical-writer — a subagent that writes technical documentation: API references, guides, specs, and installation instructions with code examples and accessibility checks. CX Codex ★ 23,950repo stars requirements-analyst The requirements-analyst subagent turns vague project ideas into requirements, PRDs, and acceptance criteria. Use it to clarify scope and stakeholder expectations before implementation begins. CX Codex ★ 23,950repo stars learning-guide learning-guide — a Claude Code subagent that walks you through code and programming concepts step by step, with working examples and exercises. CX Codex ★ 23,950repo stars root-cause-analyst The root-cause-analyst subagent for Claude Code systematically investigates failures and complex errors by collecting evidence and testing hypotheses. It finds root causes rather than patching symptoms. CX Codex ★ 23,950repo stars security-engineer The security-engineer subagent reviews code for vulnerabilities, maps attack paths, and checks security standards. Use it for audits and risk analysis. CX Codex ★ 23,950repo stars

Project sponsors

Companies that keep this analytics open