Planning Refactors With AI — Plans First, Code Second

Refactor Without a Plan Is Vandalism

Asking an agent to "refactor this codebase" or "clean up this module" is asking for chaos. The agent has no opinion on what "clean" means and will produce a 5,000-line diff that nobody can review. The fix is plan-first refactoring — a written plan reviewed before any code is touched.

The plan-first workflow

1. EXPLORE — Agent reads the relevant code, summarizes architecture 2. PROPOSE — Agent writes a refactor plan: goals, non-goals, steps, risks 3. REVIEW — You read and edit the plan. NO CODE TOUCHED YET. 4. EXECUTE — Agent implements ONE step at a time, running tests between each 5. STOP — At any failure or surprise, stop and replanFive phases. Phase 3 is where most teams skip — and where most refactor disasters originate.

The planning prompt that works

"Don't write any code. Read src/auth/ and produce a refactor plan with these sections: 1. CURRENT STATE - What does this module do? - What's the architecture (1-paragraph)? - What are its public exports? 2. PROBLEMS YOU SEE (concrete, with file:line references) 3. GOALS — what should be true after the refactor? 4. NON-GOALS — explicitly NOT changed (write 5-10 of these) 5. STEPS — numbered, each step: - 1-line description - Files touched - Risk level (low/med/high) - How we'll know the step succeeded (test command) 6. RISKS - What could go wrong? - What's the rollback for each step? Return this as Markdown. Do not edit any files."A 250-word plan template that produces a reviewable plan instead of a sprawling diff.

Reading the plan

1. Are the goals concrete? "Cleaner" is not a goal. "Reduce auth.py from 600 to <300 lines while maintaining all tests" is.
2. Are the non-goals comprehensive? Add the ones the agent missed.
3. Is each step independently committable? If not, split it.
4. Does each step have a verify command? If not, you can't gate progress.
5. Is the risk-est step first or last? Last is safer (more context built up before the dangerous bit).

Step-by-step execution with gates

# After plan is approved: "Execute step 1 only. Run the verify command. Show me the diff and the test output. Do not start step 2 until I confirm step 1 is good." # Then, after each step: # - Read the diff # - Run tests yourself # - Commit the step (atomic commit per step) # - Approve next step # Most teams using this approach see ~3-5 minute review per step, # 5-10 minute execution per step. A 10-step refactor takes ~2 hours # and ships clean instead of taking a day and breaking things.Gate per step. Atomic commit per step. Easy revert per step.

Architectural decisions belong in ADRs, not vibes

If the plan involves a real architectural choice (move from REST to RPC, switch ORM, restructure modules), write an ADR (Architecture Decision Record) before any code. AI is great at drafting ADRs from a plan — but the decision is human. The ADR makes the choice legible to your future self and your team.

# Generate an ADR from the plan: "Convert section 3 of the refactor plan into an ADR with these sections: - Context (why this is being considered now) - Decision (what we're doing) - Status (proposed) - Consequences (positive, negative, neutral) - Alternatives considered (at least 2, with why-rejected) Number the ADR sequentially based on existing files in docs/adr/."Refactor plans become ADRs. ADRs become institutional memory.

Common mistakes during plan execution

• Letting the agent run multiple steps in one go — defeats the gate
• Approving a step without reading the diff — you'll find out in production
• Skipping the verify command because "it looked right" — that's how regressions ship
• Not committing per step — when something breaks, you can't bisect

A plan is the cheapest possible refactor.

— An ex-Google engineering manager

The big idea: refactors are where AI agents do the most damage when unleashed and the most good when constrained. Make the plan first, review it, execute one step at a time with verification gates. Slow is smooth. Smooth is fast.