18.3 Safe refactoring prompts (small steps, diffs, tests)

Goal: refactor without breaking behavior

Refactoring is a behavior-preserving transformation. In existing repos, the cost of accidental behavior change is high.

Your goal is to:

• keep diffs small and reviewable,
• preserve public behavior and interfaces,
• improve structure for future work,
• use tests as your truth source.

Preconditions: freeze behavior first

Before refactoring, ensure you have a behavioral anchor:

• run the existing test suite
• add characterization tests for the behavior you care about (if missing)
• write acceptance criteria for “must not change” outputs

If tests are weak, strengthen them before moving code around.

Plan-first refactor workflow

1. Explain: ask the model to explain current code behavior (no changes).
2. Plan: 3–8 steps, each with verification.
3. Implement step 1: diff-only, small scope.
4. Verify: run tests.
5. Repeat: step-by-step until complete.

This prevents the classic “refactor by rewrite” failure.

Diff-only enforcement (how to prevent rewrites)

Use explicit constraints:

• “Output unified diff only.”
• “Only touch these files.”
• “Keep diff under ~N lines; stop if it exceeds.”
• “No behavior change; tests must pass.”

If the model still outputs a rewrite, stop and restate the rules.

Verification after each step

Verification is what makes refactors safe. After each step:

• run tests
• run a targeted smoke command (CLI or HTTP request)
• confirm exit codes and error messages (if part of contract)

If something breaks, revert to the last ship point and reattempt with a smaller diff.

Copy-paste refactor prompts

Prompt A: explain only

Explain this code without proposing changes.

Output:
- High-level behavior summary
- Inputs/outputs
- Error behavior
- Assumptions/invariants
- Risky areas

Do not write code yet.

Prompt B: plan a refactor

We are refactoring for maintainability WITHOUT changing behavior.

Constraints:
- Only touch these files: [...]
- No new dependencies
- Keep diffs small; diff-only output

Task:
Propose a 3–8 step plan.
For each step: files touched + verification.
Stop after the plan.

Prompt C: implement step 1 only

Implement step 1 only.

Constraints:
- Diff-only changes
- Keep diff under ~100 lines
- Preserve behavior; tests must pass

After diff: list verification commands.

Red flags (stop signals)

• the diff touches many files for a small change
• the model introduces new dependencies
• the model changes public interfaces without necessity
• tests were weakened or deleted to “make it pass”
• the model claims behavior without pointing to code/tests

When you see a red flag, stop and shrink scope.

Ship point: refactor commit

Commit after each major refactor step or after the entire planned refactor if it stayed small:

• tests pass
• diff reviewed
• commit message references intent (“Refactor: extract parser module”)

Where to go next

• 18.4 Legacy seams
• 18.5 Migrations