Refactoring in the AI Era: Evolving Code for Cleanliness

“Any fool can write code that a computer can understand. Good programmers write code that humans can understand.” – Martin Fowler

After learning to read AI‑generated code with UML (Chapter 22), the next challenge is that the code runs but is a mess: huge methods, classes doing many things, duplicated logic. The solution is refactoring.

What Refactoring Is and Why Technical Debt Grows

Refactoring improves the internal structure of code without changing its external behavior—turning dirty code into clean code while keeping the program’s output identical.

Dirty code results from inexperience, tight deadlines, poor management, and shortcuts.

Clean code is readable, understandable, and maintainable, making development predictable.

Ward Cunningham’s concept of technical debt explains why code degrades: shortcuts (e.g., skipping tests) accelerate delivery now but incur “interest” that slows future work.

Business pressure → rushed patches.

Invisible consequences → managers ignore debt, reducing refactoring time.

Strong coupling → changes ripple across the codebase.

Lack of tests → risky releases, possible data loss.

Missing documentation/communication → onboarding delays, knowledge loss.

Long‑running parallel branches → merge‑time debt accumulation.

Procrastinated refactoring → continuous addition of new code on top of old, increasing rework.

In the AI era, missing tests and postponed refactoring are especially dangerous because an AI can generate thousands of lines in minutes, inflating debt at unprecedented speed.

When to Refactor: The Rule of Three

First time you do something, just do it.

Second time you repeat a similar task, endure the discomfort.

Third time you encounter the same pattern, start refactoring.

Additional natural triggers:

When adding new features—clean code is easier to extend.

When fixing bugs—clean code reveals hidden defects.

During code review—the last chance to tidy before merging.

How to Refactor Correctly

Three essential rules (from refactoring.guru):

Code must become clean; avoid large, monolithic changes.

Do not add new functionality while refactoring; keep commits separate.

All existing tests must pass after each change; failing tests indicate a mistake or a need to rewrite the test.

The /refactor skill encodes these rules into a mechanical safety protocol.

Fowler’s Catalog: Smells and Techniques

Refactoring.guru lists two groups: code smells (symptoms) and refactoring techniques (prescriptions). The catalog is organized into six categories of techniques (e.g., composing methods, moving features, organizing data, simplifying conditionals, method‑call simplifications, dealing with generalization).

Examples of smell categories and typical techniques:

Bloated class : long method → Extract Method , Replace Temp with Query .

OO abuse : Switch statements → Replace Conditional with Polymorphism .

Redundant class : comments → Extract Method , Rename Variable .

… (other categories follow the same pattern).

Turning the Catalog into an AI Skill

Goal Workflow provides two skills: /refactor – wraps the entire Fowler catalog as an AI‑callable ability. /smell – scans a codebase, identifies where the problems are, and prioritizes them.

Installation (run once):

npx skills add smallnest/goal-workflow --skill refactor

Trigger the skill directly: /refactor Or use natural‑language prompts, e.g.:

Refactor: the UserManager class is too large.
smell: this function has Feature Envy, fix it.
extract method: split this long method into smaller functions

22 Code Smells (Five Major Groups)

Bloated class : long methods, oversized classes.

OO abuse : switch statements.

Redundant class : unnecessary comments.

Coupling issues : love affairs, global state.

Other : duplicate code, magic numbers, dead code, etc.

40+ Refactoring Techniques (Six Major Groups)

Composing Methods – Extract Method, Inline Method, Extract Variable, Replace Temp with Query, Substitute Algorithm.

Moving Features – Move Method, Move Field, Extract Class, Inline Class, Hide Delegate.

Organizing Data – Replace Data Value with Object, Encapsulate Field, Replace Type Code with Subclasses, Replace Magic Number.

Simplifying Conditionals – Decompose Conditional, Guard Clauses, Replace Conditional with Polymorphism, Introduce Null Object.

Method Calls – Rename Method, Separate Query from Modifier, Introduce Parameter Object, Replace Error Code with Exception.

Generalization – Pull Up Method, Push Down Method, Extract Interface, Template Method, Replace Inheritance with Delegation.

Five‑Stage Safety Protocol for /refactor

Preparation : write characterization tests, commit the current state, create a refactor branch.

Each Step : change one location, compile, run all tests, commit.

Verification : all tests pass, manual smoke test, diff review, final commit.

Ironclad Rule : never change external behavior, never mix feature work with refactoring, each step must be test‑backed.

These map directly to the three checklist items from Section 23.3.

Language‑Specific Guidance

Java – final locals, IDE refactor, Records, Sealed Classes.

TypeScript – destructuring, const first, Union Types, optional chaining ( ?.).

Python – type hints, dataclasses, @property, context managers.

Go – small interfaces, named returns, table‑driven tests, early returns.

Rust – Result/Option, pattern matching, From trait, derive macros.

/smell: Diagnose Before You Cut

Installation:

npx skills add smallnest/goal-workflow --skill smell

Trigger: /smell /smell scans a large AI‑generated codebase, reports where the worst problems are, and ranks them by severity (critical / warning / suggestion). The report includes an overall health score, architecture style comparison, dependency graph analysis, and a prioritized refactoring roadmap (immediate, short‑term, long‑term).

Combining /smell and /refactor

/smell

produces a report: locate hotspots and set priorities. /refactor addresses each reported smell using Fowler’s techniques and the five‑stage protocol.

Run /smell again to verify that the health score improves.

This loop enforces the “code must become clean” rule with measurable before‑and‑after scores.

Conclusion

The refactoring methodology has changed little in twenty years: detect smells, consult the catalog, apply small, test‑backed steps, and never mix feature work. What has changed in the AI era is that Fowler’s book is no longer a human reference but an executable AI skill, and the safety protocol turns human shortcuts into machine‑enforced guardrails. Goal Workflow splits this into two skills— /smell for diagnosis and /refactor for treatment—creating a closed loop that keeps codebases healthy.

Chapter 22 taught you to read AI‑generated code; this chapter shows you how to improve it. Understanding is the prerequisite, fixing is the payoff, and together they embody the principle “you can outsource thinking, but not understanding.”