I've developed a process for working with Claude Code that accomplishes two things at once: cleaning up technical debt and generating content about the work. Here's how it works.
The Problem with AI-Driven Refactoring
Left to its own devices, an AI will happily refactor code. But it often:
- Guesses at intent - Applies patterns that seem right without understanding the codebase
- Over-engineers - Extracts abstractions you don't need
- Loses context - Forgets why certain decisions were made
The fix isn't less AI. It's a structured process that keeps human judgment in the loop.
The Five-Step Process
(a) Define Intent
Human specifies what to change and why. The AI should never guess at refactoring patterns.
Bad: "Refactor this controller"
Good: "Extract filter options to a presenter. Move edit tracking to a service. Rename nix to reject."
This step is quick but critical. It prevents the AI from wandering off to "improve" things you don't care about.
(b) Implement & Verify
The AI implements each change incrementally. After each change:
- Run tests
- Review the diff
- Confirm it matches intent
If something looks wrong, stop and clarify before continuing.
This step is iterative. After the initial commit, I reviewed and noticed a 50-line case statement still in the controller. One comment—"this should not be in the controller"—triggered another extraction. The AI proposed patterns; I picked one; we amended the commit.
The process isn't linear. It's: implement → review → refine → amend.
(c) Write Rules
Prevent the pattern from recurring. After you've fixed something, document it:
- What was the anti-pattern?
- What's the correct pattern?
- When are exceptions appropriate?
These rules live in .ai/ files that future AI sessions can reference. This creates institutional memory that survives conversation boundaries.
(d) Search for Similar Patterns
The problem you just fixed probably exists elsewhere. Search the codebase:
grep -r "pluck.*uniq.*sort" app/controllers/
grep -r "EDITABLE_FIELDS" app/controllers/
(e) Apply Everywhere
Fix all instances found in step (d). You now have confidence the pattern is correct—you've already verified it works.
Creating Content From the Process
Here's the meta-move: document the conversation as you go.
During refactoring, I note:
- The original problem ("controller was 317 lines with inline filter logic")
- The specific changes ("extracted presenter, created service, renamed action")
- The before/after code
- Lines of code reduced (317 → 256)
This material becomes tactics articles almost automatically. The work is already done—you just need to format it.
Example: Controller Cleanup
Starting point: Admin::JobListingsController at 317 lines with:
- Inline filter option building in 2 actions
- Edit tracking constants and methods
- Inline field configuration (50-line case statement)
- Colloquial action name (nix)
- Unused JSON response data
After the first pass: 256 lines. Then I reviewed and said "that case statement shouldn't be in the controller." The AI proposed four patterns. I picked convention-based inference. We extracted it. Amended the commit.
Then another review: "we'll use this inline editing pattern elsewhere—abstract it." One more extraction: the update_field action moved to a controller concern. Amend again.
Final result:
- 166 lines (48% reduction)
- JobListingsFilterPresenter - filter options
- JobListingEditService - edit tracking
- InlineEditable concern + InlineFieldResolver - field config on model, inference in service
- InlineEditableController concern - reusable update_field action
- Clear action name (reject)
- Clean JSON responses
From this single session:
- Four tactics articles
- This strategy article
- Reusable patterns for any model/controller with inline editing
- Rules documentation for future AI sessions
Why This Works
The process creates compounding returns:
- Code improves - Obvious benefit
- Rules accumulate - Future sessions start smarter
- Content emerges - Blog posts write themselves
- Patterns transfer - What works in one codebase applies to others
Most importantly: the human stays in control. The AI executes. The human decides what's worth doing.
Getting Started
Next time you have a controller that feels bloated:
- Write down 3-4 specific changes you want
- Tell your AI tool to implement them, one at a time
- Verify each change before moving to the next
- Document the pattern to prevent recurrence
- Search for similar issues
- Turn the session into a blog post
The refactoring takes the same time it always would. The content is a free bonus.