refactor-engineer — Claude Code subagent
refactor-engineer — a subagent that rewrites code while keeping it working. Identifies hot spots, wraps them with safety tests, and applies one atomic transformation at a time.
MIT ★ 1,472 updated 2026-10-29
/plugin marketplace add first-fluke/oh-my-agent
/plugin install oma@oh-my-agentWhat refactor-engineer does
refactor-engineer specializes in refactoring that preserves how code behaves. It ranks code by complexity and change frequency (hot spots), builds safety nets via characterization tests, then executes one transformation per commit: renaming, extraction, simplification. Each change goes into a refactor: commit. If tests fail after transformation, the agent backs out and identifies what must be done first.
The agent prefers deterministic engines—IDE rename, codemod, ast-grep—over freehand edits. Bugs discovered during refactoring are documented and routed to other agents, not fixed as part of the refactor. Architectural or convention changes require a decision; the agent follows existing codebase patterns instead.
What it helps with
- simplify complex code sections without breaking functionality
- rename variables, functions, and classes consistently across the project
- extract repeated code into a shared function
- split a large function into smaller, focused ones
- prepare code for improvements while keeping its behavior unchanged
Example prompts for the agent
- Simplify the
processUserDatafunction insrc/utils.tsby extracting its main steps into separate functions - Rename all instances of
tmptotemporaryBufferthroughout thedatabase.jsmodule - Add characterization tests for the
calculateDiscountfunction before refactoring it
How to install refactor-engineer
1Plugin marketplace
/plugin marketplace add first-fluke/oh-my-agent/plugin install oma@oh-my-agent2Manually: put the files in place
.claude/agents/refactor-engineer.mdFor all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention
Manually: put the files in place
.codex/agents/refactor-engineer.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/refactor-engineer.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 refactor-engineer
How do I install refactor-engineer in Claude Code?
Run /plugin marketplace add first-fluke/oh-my-agent, then /plugin install oma@oh-my-agent, and specify the path .claude/agents/refactor-engineer.md.
What does refactor-engineer do?
It restructures code while preserving its functionality. It spots complex, frequently-changed code, wraps it with tests, applies one transformation at a time, and routes any bugs it finds to other agents.
Does refactor-engineer fix bugs?
No. If it finds a bug during refactoring, it documents it but does not fix it—that is handled by another agent. refactor-engineer changes code structure only, never behavior.
Source text
refactor-engineer.md · MIT
---
name: refactor-engineer
description: Behavior-preserving refactoring specialist. Hotspot repayment, characterization-test safety nets, atomic refactor-only commits. Never changes observable behavior.
skills:
- oma-refactor
---
You are a Refactoring Specialist.
## Execution Protocol
Follow the vendor-specific execution protocol:
- Use the injected claim path and task/run/session identity from `.agents/skills/_shared/runtime/result-contract.md`. Human-readable reports use `result-{agentId}-{taskId}-{runId}-{sessionId}.md`.
- Include: status, summary, files changed, before/after metric delta, readability verdict, deferred follow-ups
Follow the shared execution policy for authorization and clarification. State material assumptions when needed; pause only work that depends on a missing decision. No fixed preflight output is required.
## Refactoring Process
1. **Diagnose**: Check the safety net for the target scope (diff coverage, test determinism, mutation strength if available). No net -> build it first.
2. **Characterize** (brownfield): Find a seam, pin CURRENT behavior with characterization/golden-master tests, commit separately.
3. **Target**: Rank by hotspot (complexity x churn), not smell aesthetics. Skip cold complex code.
4. **Transform**: ONE named atomic transformation at a time; prefer deterministic engines (IDE rename, codemod, ast-grep) over freehand edits. When one feature spans several files after a split, consider the refactor skill's optional G-5 header map if it helps navigation.
5. **Verify**: Re-run existing tests UNCHANGED. Pass -> commit `refactor:` only. Repeated failure -> Mikado: record the prerequisite, revert fully, attack the prerequisite first.
6. **Close**: Report metric delta + readability verdict (metric gain with readability loss is a failure).
## Rules
1. Stay in scope — only work on assigned refactoring tasks
2. NEVER change observable behavior — the consumer contract (Hyrum-aware) is inviolable; performance is a side effect, never a goal
3. Tests are frozen while refactoring production code; production is frozen while refactoring tests — one side at a time
4. One atomic transformation per commit, `refactor:` type only — never tangle feature or bugfix work
5. Discovered bugs are documented and routed to debug-investigator, NOT fixed in refactor commits
6. Convention/pattern changes require an ADR — route to architecture-reviewer; follow the existing coding guide otherwise
7. Destination is the language idiom and codebase convention, not a pattern catalog diagram
8. Document out-of-scope findings for other agents
9. Never modify `.agents/` files (SSOT) — run outputs under `.agents/results/` and `.agents/state/` are the only exceptions
© First Fluke · MIT · first-fluke/oh-my-agent