Planning Refactors With AI — Plans First, Code Second

Letting an agent loose on a refactor without a plan is how repos die. Learn the plan-first refactor workflow, the planning prompts that produce real plans, and the gates that keep the agent from going wide.

12 min · Reviewed 2026

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

Are the goals concrete? "Cleaner" is not a goal. "Reduce auth.py from 600 to <300 lines while maintaining all tests" is.
Are the non-goals comprehensive? Add the ones the agent missed.
Is each step independently committable? If not, split it.
Does each step have a verify command? If not, you can't gate progress.
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.

End-of-lesson check

15 questions · take it digitally for instant feedback at tendril.neural-forge.io/learn/quiz/end-coding-debug-refactor-planning-creators

What is the core idea behind "Planning Refactors With AI — Plans First, Code Second"?
1. Letting an agent loose on a refactor without a plan is how repos die. Learn the plan-first refactor workflow, the planning prompts that produce real plans, and the gates that keep the agent from going wide.
2. deliberate practice
3. The bug is in code you cannot legally paste (sensitive auth logic)
4. App Router
Which term best describes a foundational idea in "Planning Refactors With AI — Plans First, Code Second"?
1. plan-first
2. refactor
3. non-goals
4. ADR
A learner studying Planning Refactors With AI — Plans First, Code Second would need to understand which concept?
1. refactor
2. non-goals
3. plan-first
4. ADR
Which of these is directly relevant to Planning Refactors With AI — Plans First, Code Second?
1. refactor
2. plan-first
3. ADR
4. non-goals
Which of the following is a key point about Planning Refactors With AI — Plans First, Code Second?
1. Are the goals concrete? "Cleaner" is not a goal. "Reduce auth.
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.
Which of these does NOT belong in a discussion of Planning Refactors With AI — Plans First, Code Second?
1. Are the non-goals comprehensive? Add the ones the agent missed.
2. Is each step independently committable? If not, split it.
3. deliberate practice
4. Are the goals concrete? "Cleaner" is not a goal. "Reduce auth.
Which statement is accurate regarding Planning Refactors With AI — Plans First, Code Second?
1. Approving a step without reading the diff — you'll find out in production
2. Skipping the verify command because "it looked right" — that's how regressions ship
3. Letting the agent run multiple steps in one go — defeats the gate
4. Not committing per step — when something breaks, you can't bisect
Which of these does NOT belong in a discussion of Planning Refactors With AI — Plans First, Code Second?
1. deliberate practice
2. Approving a step without reading the diff — you'll find out in production
3. Skipping the verify command because "it looked right" — that's how regressions ship
4. Letting the agent run multiple steps in one go — defeats the gate
What is the key insight about "Non-goals are the secret sauce" in the context of Planning Refactors With AI — Plans First, Code Second?
1. Telling the agent what NOT to change is more powerful than telling it what to change.
2. deliberate practice
3. The bug is in code you cannot legally paste (sensitive auth logic)
4. App Router
What is the key insight about "Branch protection during refactors" in the context of Planning Refactors With AI — Plans First, Code Second?
1. deliberate practice
2. Run a refactor on a dedicated branch with required CI checks. Even a tiny refactor should pass CI green between every st…
3. The bug is in code you cannot legally paste (sensitive auth logic)
4. App Router
Which statement accurately describes an aspect of Planning Refactors With AI — Plans First, Code Second?
1. deliberate practice
2. The bug is in code you cannot legally paste (sensitive auth logic)
3. Asking an agent to "refactor this codebase" or "clean up this module" is asking for chaos.
4. App Router
What does working with Planning Refactors With AI — Plans First, Code Second typically involve?
1. deliberate practice
2. The bug is in code you cannot legally paste (sensitive auth logic)
3. App Router
4. If the plan involves a real architectural choice (move from REST to RPC, switch ORM, restructure modules), write an ADR (Architecture Decisi…
Which of the following is true about Planning Refactors With AI — Plans First, Code Second?
1. The big idea: refactors are where AI agents do the most damage when unleashed and the most good when constrained.
2. deliberate practice
3. The bug is in code you cannot legally paste (sensitive auth logic)
4. App Router
Which best describes the scope of "Planning Refactors With AI — Plans First, Code Second"?
1. It is unrelated to ai-coding workflows
2. It focuses on Letting an agent loose on a refactor without a plan is how repos die. Learn the plan-first refactor
3. It applies only to the opposite beginner tier
4. It was deprecated in 2024 and no longer relevant
Which section heading best belongs in a lesson about Planning Refactors With AI — Plans First, Code Second?
1. deliberate practice
2. The bug is in code you cannot legally paste (sensitive auth logic)
3. The plan-first workflow
4. App Router

← Back to interactive lesson

Tendril · Creators · AI-Assisted Coding