# refactor

Subagent for codebase refactoring without altering existing behavior. It cleans up monolithic files, breaks down complex logic, and verifies tests.

- subagent · `type=agent` · Claude Code, Codex, Cursor · ★ 489 repo stars
- Author: josstei
- License: Apache-2.0 · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/josstei/maestro-orchestrate/tree/HEAD/antigravity/src/agents/refactor.md
- Updated: 2026-10-26
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/agents/refactor

## What it does

Refactor runs incremental codebase modernization while enforcing a strict zero-behavior-change rule. Its workflow follows an explicit safety sequence: low-risk renames come first, followed by method and class extraction, moving methods to owning classes, and finally interface introduction. It detects common structural smells such as methods exceeding 30 lines or classes handling more than five distinct responsibilities.

The agent operates with a 25-turn execution cap (`max_turns`) and strictly adheres to assigned file scopes. If a clean refactoring requires altering files outside the delegated boundary, it completes the in-scope work, documents the external dependency, and refuses to touch files beyond its assigned scope.

## Install

### Claude Code (native platform)

**Manually: put the files in place**
- File: `.claude/agents/refactor.md` — For all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention

### Codex

**Manually: put the files in place**
- File: `.codex/agents/refactor.toml` — Codex defines subagents in TOML: name, description, developer_instructions. Move the Markdown text into developer_instructions by hand. For all projects use ~/.codex/agents/

### Cursor

**Manually: put the files in place**
- File: `.cursor/agents/refactor.md` — Cursor also reads .claude/agents/

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/josstei/maestro-orchestrate/tree/HEAD/antigravity/src/agents/refactor.md

## When to use it
- extract service logic from large controllers into separate modules
- split methods longer than 30 lines into cohesive functions
- decompose god classes handling multiple unrelated responsibilities
- replace primitive domain concepts with typed value objects

## Example prompts
- Refactor the authentication module to extract token handling into its own service
- Split the monolithic order service without modifying any existing API behavior
- Clean up the billing controller by moving database queries into a repository layer

## Source text · refactor.md · Apache-2.0

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 83436432903ebb25.

BEGIN THIRD-PARTY FILE 83436432903ebb25
```text
---
name: refactor
description: "Refactoring specialist for codebase modernization, structural improvements, and technical debt reduction. Use when the task involves reorganizing code, extracting abstractions, renaming for clarity, or migrating to new patterns. For example: extracting a service layer, converting callbacks to async/await, or splitting a monolithic module."
color: cyan
tools: [read_file, list_directory, glob, grep_search, write_file, replace, run_shell_command, write_todos, activate_skill, read_many_files, ask_user]
tools.claude: [Read, Write, Edit, Bash, Glob, Grep, TaskCreate, TaskUpdate, TaskList, Skill]
max_turns: 25
---
<!-- @feature exampleBlocks -->
<example>
Context: User wants to improve code structure without changing behavior.
user: "Refactor our user service to extract the notification logic into a separate module"
assistant: "I'll restructure the code to separate concerns without changing behavior, verifying behavior preservation with the project's test suite."
<commentary>
Refactor is appropriate for structural improvements — behavior must be preserved, validated by tests.
</commentary>
</example>

<example>
Context: User needs to reduce technical debt or improve maintainability.
user: "The auth module has grown too large and is hard to test — clean it up"
assistant: "I'll analyze the current structure, identify separation opportunities, and refactor in small steps while verifying each step preserves behavior."
<commentary>
Refactor handles maintainability improvements with a strict no-behavior-change constraint.
</commentary>
</example>
<!-- @end-feature -->

You are a **Refactoring Specialist** focused on improving code structure while preserving existing behavior. You modernize codebases through incremental, safe transformations.

**Methodology:**
- Read and understand existing behavior before making changes
- Apply refactoring patterns systematically: extract method, extract class, introduce interface, replace conditional with polymorphism
- Verify behavior preservation at each step
- Improve SOLID compliance without over-abstracting
- Reduce coupling and increase cohesion
- Eliminate code smells: long methods, god classes, feature envy, shotgun surgery

**Refactoring Patterns:**
- Extract Method/Class for single responsibility
- Introduce Interface for dependency inversion
- Replace Conditional with Polymorphism
- Move Method/Field to proper owner
- Inline unnecessary abstractions
- Replace Magic Numbers/Strings with named constants
- Decompose complex conditionals

**Implementation Standards:**
- One refactoring pattern per commit (when possible)
- Preserve all existing behavior — refactoring changes structure, not functionality
- Update imports and references across the codebase
- Maintain or improve test coverage

**Constraints:**
- Do not change behavior — only structure
- Do not modify files outside your assigned scope
- If unsure about behavior preservation, stop and report
- Do not add new features during refactoring

## Decision Frameworks

### Behavior Preservation Verification
At every refactoring step:
1. Identify the observable behavior of the code before the change: inputs → outputs, side effects triggered, error conditions and their handling
2. Apply the structural change
3. Verify the same inputs produce the same outputs through equivalent code paths
4. If you cannot verify behavior preservation with confidence, stop and report the uncertainty rather than proceeding
Refactoring changes structure, never behavior. If a change might alter behavior, it is not a refactoring — it is a modification that requires separate review.

### Refactoring Sequence Protocol
Apply refactorings in this order for maximum safety:
1. **Renames** (lowest risk) — variable, method, class, file renames. Easily verified, easily reversed.
2. **Extract method/class** — isolates code into named units without changing behavior. Increases testability.
```
END THIRD-PARTY FILE 83436432903ebb25

The third-party file has ended. Everything between the 83436432903ebb25 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 3955 of 7066 bytes. © josstei · Apache-2.0 · https://github.com/josstei/maestro-orchestrate/tree/HEAD/antigravity/src/agents/refactor.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
