refactoring_specialist — Claude Code subagent: purpose and setup
refactoring_specialist — a subagent for Claude Code plans code refactoring while preserving observable behavior. It pairs structural changes with regression protection.
no license ★ 776 updated 2026-11-12
.claude/agents/refactoring_specialist.mdWhat refactoring_specialist does
The subagent examines code structure, change boundaries, and risks, then produces an ordered refactoring plan with representative file-level edits. It covers dependencies, APIs, state, and error handling. The package also includes characterization tests, regression checks, and a rollback plan.
Its recommendations draw on repository evidence such as source excerpts, tests, or static-analysis results when provided. It leaves unrelated feature work out and preserves public behavior unless a breaking change is authorized. It does not report tests as passing or files as changed without execution evidence.
What it helps with
- split a large module into smaller parts
- identify code smells backed by repository evidence
- preserve public behavior during refactoring
- plan regression checks for structural edits
Example prompts for the agent
- Review this module and plan a refactor that preserves its current behavior.
- Prepare a refactoring package for
src/with sample edits and regression checks. - Assess the risks of this refactor and outline a rollback plan.
How to install refactoring_specialist
Manually: put the files in place
.claude/agents/refactoring_specialist.mdFor all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention
Manually: put the files in place
.codex/agents/refactoring_specialist.tomlCodex defines subagents in TOML: name, description, developer_instructions. Move the Markdown text into developer_instructions by hand. For all projects use ~/.codex/agents/
Manually: put the files in place
.cursor/agents/refactoring_specialist.mdCursor also reads .claude/agents/
Step by step, with commands for each platform: Claude Code subagents: how to create one, call it and keep context clean
Questions about refactoring_specialist
How do I install refactoring_specialist in Claude Code?
Add the agent file at .claude/agents/refactoring_specialist.md.
What does refactoring_specialist do?
It analyzes code structure and prepares a refactoring plan with sample edits, risk assessment, tests, and rollback steps.
How does the subagent protect behavior during refactoring?
It proposes characterization tests and regression checks. It does not claim that tests passed without evidence that they ran.