Refactoring a Legacy Codebase with Claude Code

I recently started using Claude Code to tackle a long-overdue codebase cleanup, and the experience was smoother than I expected, largely thanks to Matt Pocock's "grill-me" skill.

The idea behind the skill is simple: you describe a goal, and the AI asks targeted questions until it fully understands what you actually want. I kicked things off with:

/grill-me I want to modernize the codebase, do a good cleanup, and incorporate AI in the workflows.

Taking stock of the codebase

Before asking a single question, Claude audited the project. It surfaced an outdated Next.js version, a legacy Pages Router setup alongside an abandoned App Router directory, magic numbers scattered throughout, zero test coverage, and a CI pipeline with no quality checks.

With that picture in hand, it started grilling me:

• Full App Router migration or incremental? Incremental, keep static export
• GSAP to Framer Motion, or extract into hooks? Keep GSAP, extract hooks
• Vitest or Jest? Vitest, all test types
• AI in CI: PR reviews, changelogs, or both? Changelogs only

Shaping the plan together

Claude's first proposal was cleanup, then tests, then migration. Reasonable, but wrong order for my needs. I pushed back since I wanted tests and linting in place before touching anything, so the site couldn't quietly break during refactoring.

Claude adjusted without friction:

1. Tests — establish the safety net first
2. CI quality gates — lint and test on every push
3. Cleanup — delete dead code, fix fragile patterns, tighten TypeScript
4. GSAP hooks — extract duplicated animation logic
5. Code smells — remove dangerouslySetInnerHTML
6. App Router migration — incremental, one page at a time
7. AI tooling — changelog generation, CLAUDE.md, blog drafting script

Turning the plan into a living document

Once the plan was finalised, Claude created a GitHub issue capturing every step and the reasoning behind each decision. That's not just tidiness — it means any agent or human picking up the work later can immediately understand the context and continue without a handoff conversation.

Takeaway

What struck me most wasn't the technical output, it was the back-and-forth. The grill-me skill forced the planning to be explicit, which surfaced assumptions I hadn't considered. The result is a phased, reviewable refactor I can execute in small pull requests, with tests proving nothing broke along the way.

If you're staring down a messy legacy project, having an AI help you plan the work rather than just do it might be the most underrated part of the whole workflow.