Recap — Safe Refactoring Patterns with AI

# Safe Refactoring Patterns with AI AI can refactor large amounts of code quickly. The risk: subtle behavior changes that AI didn't notice. The discipline: tests as safety net. ## The cardinal rule **Tests must pass before refactor. Tests must pass after refactor. If they don't, you've changed behavior, not refactored.** If you don't have tests for the code: write them BEFORE refactoring. AI can help write them (the code is a spec; tests verify the spec). ## What "refactoring" means Refactoring = restructuring code without changing behavior. Same inputs → same outputs. NOT refactoring: - Adding features. - Fixing bugs. - Changing behavior intentionally. Common refactoring goals: - Extract a function. - Rename for clarity. - Reduce duplication. - Move logic to a more appropriate place. - Replace a pattern with a cleaner one. ## What AI is great at ### Mechanical refactors - Rename a variable across the file/codebase. - Extract a function (cut a chunk, give it a name). - Convert syntax (Python 2 → 3, sync → async). - Convert one framework to another (Flask route → FastAPI route). - Apply a consistent pattern (all functions get type hints). These are well-defined and easy to verify. ### Pattern transformations - "Replace all bare except: with except Exception as e: + logging." - "Convert all datetime.datetime.utcnow() to datetime.datetime.now(timezone.utc)." - "Add @cache to all functions that take only hashable args and return." Defined transformations; AI applies them consistently. ### Style cleanups - "Add type hints to all functions in this file." - "Convert string concatenation to f-strings." - "Apply ruff formatting and fix the style issues." ## What AI struggles with ### Semantic refactors "Make this code more testable" — vague; AI gives generic 'extract this' suggestions without understanding what's truly hard to test. ### Architecture changes "Refactor this to use the repository pattern" — AI can apply mechanically but might miss subtle issues with your codebase's specific dependencies. ### Performance refactors "Make this faster" — AI may produce code that looks faster but isn't. Or restructures correctly but with different (worse) algorithmic complexity. For these: drive mode (you decide); AI helps execute the changes. ## The safe refactor workflow ``` 1. Tests pass. (Verify before.) 2. Describe the refactor clearly to AI. 3. AI generates changes. 4. Diff carefully (visually compare). 5. Run tests. (Pass = behavior preserved; fail = problem.) 6. If fail: investigate before continuing. 7. Commit. 8. Repeat for next refactor step. ``` Small commits. One refactor per commit. ## Pattern 1: Extract function ```python # Before def process_order(order): # validate if not order.items: raise ValueError("empty order") if order.total <= 0: raise ValueError("invalid total") # calculate tax tax = order.total * 0.18 # apply discount if order.promo_code: promo = get_promo(order.promo_code) if promo: discount = order.total * promo.rate else: discount = 0 else: discount = 0 # finalize final = order.total + tax - discount return final ``` Prompt: > "Extract three functions from process_order: validate_order, calculate_tax, calculate_discount. Don't change behavior. Add type hints." AI generates: ```python def validate_order(order): if not order.items: raise ValueError("empty order") if order.total <= 0: raise ValueError("invalid total") def calculate_tax(order): return order.total * 0.18 def calculate_discount(order): if not order.promo_code: return 0 promo = get_promo(order.promo_code) return order.total * promo.rate if promo else 0 def process_order(order): validate_order(order) tax = calculate_tax(order) discount = calculate_discount(order) return order.total + tax - discount ``` Verify: tests pass; behavior unchanged. ## Pattern 2: Rename across codebase Prompt: > "Rename `getUser` to `fetch_user` across the entire codebase. Includes function definition, all callers, tests, docs." For multi-file: use Cursor's "Composer" or Claude Code (it'll find all references). Modern IDEs do this too (rename refactor). AI alternative is broader (catches things the IDE may not, like rename in docs). ## Pattern 3: Convert sync to async Prompt: > "Convert process_users.py to async. Use httpx async instead of requests; asyncpg instead of psycopg2. Don't change behavior. Add await where needed." AI rewrites; you check carefully (subtle bugs common in async conversion). ## Pattern 4: De-duplicate Prompt: > "process_a and process_b have ~80% the same code. Extract the shared logic into a single function or class. Make the differences explicit (probably a flag or a strategy param)." AI identifies common code; extracts. Review for correctness. ## Pattern 5: Apply a new pattern Prompt: > "Apply the repository pat