The Complete Claude Code Refactoring Workflow Guide: AI-Powered Code Transformation

> Run vitest with coverage. Show me which files I'm about to refactor
> that have less than 70% coverage: Navigation.tsx, formatters.ts, useAuth.ts.

git checkout -b refactor/split-navigation          # feature branch
# or for large refactors:
git worktree add ../refactor-nav refactor/split-navigation  # isolated worktree

## Refactoring Rules
- Run existing tests before and after each refactoring step
- Preserve public API signatures unless explicitly asked to change
- When splitting files, update all import paths in the same commit
- Use barrel exports (index.ts) when splitting a module into multiple files
- Commit each step separately — never combine refactoring with feature changes

> In src/utils/dataProcessor.ts, the processUserData function is 80 lines.
> Extract the validation logic into a separate validateUserInput function.
> Keep it in the same file. Run tests after.

function validateUserInput(raw: unknown): Record<string, unknown> {
  if (!raw || typeof raw !== 'object') throw new ValidationError('Input must be an object');
  // ... all validation checks moved here
  return data;
}
 
export function processUserData(raw: unknown): ProcessedUser {
  const data = validateUserInput(raw);  // one line replaces 20
  return { name: (data.name as string).trim(), /* ... */ };
}

> src/lib/api.ts is 450 lines. Split it into:
> - src/lib/api/client.ts (base fetch wrapper and error handling)
> - src/lib/api/users.ts (user-related API calls)
> - src/lib/api/posts.ts (post-related API calls)
> - src/lib/api/index.ts (barrel export that re-exports everything)
> Update all import paths across the project. Run tests after.

// src/lib/api/index.ts
export { apiClient, ApiError } from './client';
export { getUser, updateUser, deleteUser } from './users';
export { getPosts, createPost, updatePost } from './posts';

> src/components/Dashboard.tsx is 350 lines handling header, sidebar, content, footer.
> Split into DashboardHeader, DashboardSidebar, DashboardContent, DashboardFooter.
> Dashboard.tsx becomes the composition root. Keep all state there, pass via props.
> Create TypeScript interfaces for each sub-component's props.

# Variable, function, or file rename — same pattern
> Rename `userData` to `authenticatedUser` in src/hooks/useAuth.ts. Update all references.
> Rename `formatDate` to `formatDateForDisplay` in src/utils/formatters.ts. Update all 12 call sites.
> Rename src/components/Card.tsx to ContentCard.tsx. Update all imports and tests.

# Step 1: Scope
> How many files import `useUserData` from src/hooks/useUserData.ts? List them all.
 
# Step 2: Execute
> Rename the hook to `useCurrentUser`, rename the file to useCurrentUser.ts.
> Update all 23 files. Run tests after.

> Move all hook files from src/utils/ that start with "use" to src/hooks/.
> Update all import paths. Maintain the same export names.

# Phase 1: Setup
> Add TypeScript with strict mode and allowJs: true so existing .js files still work.
 
# Phase 2: Convert one file at a time (start with utilities, end with pages)
> Convert src/utils/formatters.js to TypeScript. Add proper types for all
> parameters and return values. Don't use `any` — infer from usage patterns.
 
# Phase 3: Convert consumers
> Convert files that import from formatters.ts, starting with fewest dependencies.

> Refactor the Event type in src/types/events.ts from a loose union with optional
> fields to a discriminated union. Each event type should have exactly the fields
> it needs. Update all consumers to use type narrowing via switch statements.

// Loose union — everything is optional, nothing is safe
type Event = { type: string; payload?: any; userId?: string; timestamp?: number; };
 
function handleEvent(event: Event) {
  if (event.type === 'login') console.log(event.userId); // might be undefined!
}

// Discriminated union — each variant is fully typed
type LoginEvent = { type: 'login'; userId: string; timestamp: number };
type PurchaseEvent = { type: 'purchase'; userId: string; productId: string; amount: number };
type PageViewEvent = { type: 'pageview'; path: string; timestamp: number };
 
type Event = LoginEvent | PurchaseEvent | PageViewEvent;
 
function handleEvent(event: Event) {
  switch (event.type) {
    case 'login':    console.log(event.userId);  break; // guaranteed string
    case 'purchase': console.log(event.amount);  break; // guaranteed number
    case 'pageview': console.log(event.path);    break; // guaranteed string
  }
}

# Step 1: Audit
> Search src/ for all uses of `any`. Categorize by: function params, return types,
> type assertions (as any), and explicit variable types. Show counts per category.
 
# Step 2: Fix by category
> Replace all `any` types in src/utils/ with concrete types.
> Infer correct types from downstream usage. Use `unknown` for truly dynamic values.

> I have UserListResponse, PostListResponse, CommentListResponse — all identical
> except the item type. Refactor into a generic PaginatedResponse<T>.

export interface PaginatedResponse<T> { items: T[]; total: number; page: number; }
// Usage: PaginatedResponse<User>, PaginatedResponse<Post>, etc.

> Refactor UserService in src/services/userService.ts:
> 1. Create UserServiceV2 with improved interface
> 2. Create adapter wrapping V2 with the old interface
> 3. Export adapter as default (no breaking change)
> Don't migrate consumers yet.

// src/services/userService.ts — After adapter refactoring
 
// New clean interface
class UserServiceV2 {
  async findById(id: string): Promise<User | null> { /* ... */ }
  async search(query: UserQuery): Promise<PaginatedResponse<User>> { /* ... */ }
  async upsert(data: UpsertUserInput): Promise<User> { /* ... */ }
}
 
// Adapter preserves old interface — no breaking change for consumers
class UserServiceAdapter {
  private v2 = new UserServiceV2();
 
  async getUser(id: string) { return this.v2.findById(id); }
  async searchUsers(name: string, page: number, limit: number) {
    const result = await this.v2.search({ name, page, limit });
    return { users: result.items, total: result.total };
  }
}
 
export const userService = new UserServiceAdapter();  // old consumers use this
export const userServiceV2 = new UserServiceV2();     // new consumers use this

> Mark fetchUser, fetchPosts, updateUserProfile in src/lib/api.ts as deprecated.
> Add JSDoc @deprecated tags with replacement names and migration examples.

/** @deprecated Use `getUser(id)` instead. Will be removed in v3.0. */
export async function fetchUser(id: string): Promise<User> {
  console.warn('fetchUser is deprecated. Use getUser instead.');
  return getUser(id);
}

> Create v2 routes at /api/v2/posts/ with these changes:
> - Rename `id` to `slug` in detail route
> - Add pagination metadata to list response
> - Accept markdown instead of HTML for content creation
> Keep v1 routes working unchanged.

# Step 1: Plan first, don't change anything
> I want to migrate state management from React Context to Zustand.
> Affected: src/contexts/, src/providers/, and all useContext consumers.
> Create a step-by-step migration plan. List files and changes per step.
 
# Step 2: Execute incrementally
> Execute step 1: Install zustand, create auth store to replace AuthContext.
> Execute step 2: Migrate useAuth consumers to zustand store. Run tests.
> Execute step 3: Remove AuthContext and AuthProvider. Run tests.

# Three terminals, each handling an independent module
claude "Refactor src/features/auth/ — convert Context to Zustand. Run tests after."
claude "Refactor src/features/dashboard/ — convert Context to Zustand. Run tests after."
claude "Refactor src/features/settings/ — convert Context to Zustand. Run tests after."

git worktree add ../refactor-state refactor/zustand-migration
cd ../refactor-state && claude    # work in isolation
# When done:
cd ../main-project
git merge refactor/zustand-migration
git worktree remove ../refactor-state

> Create a refactoring progress tracker for the Context → Zustand migration.
> List all files grouped by module, marked as: pending, in-progress, done, or verified.

# Write characterization tests before refactoring
> I'm about to refactor parseMarkdown in src/utils/markdown.ts.
> Write comprehensive tests capturing its CURRENT behavior (including quirks).
> Run them to confirm they pass. Don't change the implementation yet.

# Before refactoring: capture current rendering
> Generate snapshot tests for Navigation: default, mobile menu open, active route.
 
# After refactoring: compare
> Run snapshot tests. Show me any diffs so I can verify changes are intentional.

describe('Navigation snapshots', () => {
  it('renders default state', () => {
    expect(render(<Navigation locale="en" />).container).toMatchSnapshot();
  });
  it('renders with mobile menu open', () => {
    render(<Navigation locale="en" />);
    fireEvent.click(screen.getByLabelText('Open menu'));
    expect(screen.getByRole('dialog')).toMatchSnapshot();
  });
});

git checkout -- src/components/Navigation.tsx  # undo uncommitted changes
git reset --soft HEAD~1                        # undo last commit, keep changes staged
git reset --hard pre-refactor                  # return to pre-refactoring tag

> Run post-refactoring verification: vitest, tsc --noEmit, eslint, build. Report results.

# Refactoring Guidelines
 
## Naming
- Components: PascalCase (UserProfile, NavBar)
- Hooks: camelCase with "use" prefix (useAuth, useDarkMode)
- Utilities: camelCase (formatDate, parseMarkdown)
- Constants: UPPER_SNAKE_CASE (MAX_RETRIES, API_BASE_URL)
- Types: PascalCase with descriptive suffix (UserProps, ApiResponse)
 
## File Organization
- Components: src/components/ (shared) or src/features/*/components/
- When splitting: create directory with index.ts barrel export
- Max file: 300 lines, max function: 30 lines, max params: 3
 
## Code Style
- Prefer named exports, interfaces over type aliases, early returns
- Always destructure props in component signatures
 
## Commits
- Format: refactor(scope): description
- One logical change per commit
- Never combine refactoring with feature changes or bug fixes
 
## Workflow
- Run `npx vitest --run` before and after each step
- Create git tag `pre-refactor-{feature}` before large refactors
- If tests fail, fix the refactoring (not the tests)
- Preserve public API signatures unless explicitly asked to change
 
## Post-Refactoring
- Run: vitest, tsc --noEmit, eslint, build
- Verify no new circular dependencies

> Read src/components/Navigation.tsx and analyze its structure.
> Identify: state variables, event handlers, JSX sections, props, imports.
> Don't make any changes yet.

> Write tests for Navigation covering: all nav links render, hamburger opens
> mobile menu, Escape closes it, active link has aria-current="page", theme toggle present.
> Use @testing-library/react. Mock next-intl and usePathname. Run to confirm they pass.

// src/components/__tests__/Navigation.test.tsx
jest.mock('next-intl', () => ({ useTranslations: () => (key: string) => key }));
jest.mock('next/navigation', () => ({ usePathname: () => '/en/blog' }));
 
describe('Navigation', () => {
  it('renders all nav links', () => {
    render(<Navigation locale="en" />);
    expect(screen.getByText('Blog')).toBeInTheDocument();
  });
  it('marks active link', () => {
    render(<Navigation locale="en" />);
    expect(screen.getByText('Blog').closest('a')).toHaveAttribute('aria-current', 'page');
  });
  it('opens mobile menu', () => {
    render(<Navigation locale="en" />);
    fireEvent.click(screen.getByLabelText('Open menu'));
    expect(screen.getByRole('dialog')).toBeVisible();
  });
  it('closes on Escape', () => {
    render(<Navigation locale="en" />);
    fireEvent.click(screen.getByLabelText('Open menu'));
    fireEvent.keyDown(document, { key: 'Escape' });
    expect(screen.queryByRole('dialog')).not.toBeVisible();
  });
});

> Extract nav link rendering from Navigation.tsx into NavLink.tsx.
> Props: href, label, isActive, onClick?. Handle aria-current and active styling.
> Update Navigation.tsx to use NavLink. Run tests after.

// src/components/NavLink.tsx
'use client';
import Link from 'next/link';
 
interface NavLinkProps {
  href: string; label: string; isActive: boolean; onClick?: () => void;
}
 
export function NavLink({ href, label, isActive, onClick }: NavLinkProps) {
  return (
    <Link href={href} onClick={onClick} aria-current={isActive ? 'page' : undefined}
          className={`nav-link ${isActive ? 'nav-link-active' : ''}`}>
      {label}
    </Link>
  );
}

# Step 4: Mobile menu
> Extract mobile menu from Navigation.tsx into MobileMenu.tsx.
> Props: isOpen, onClose, locale, currentPath, navItems.
> Handle: slide-out panel, Escape key, focus trap. Run tests after.
 
# Step 5: Desktop nav bar
> Extract desktop nav bar into NavBar.tsx.
> Props: locale, currentPath, navItems, onMenuToggle.
> Render: logo, NavLinks, theme toggle, hamburger. Run tests after.

// MobileMenu — handles Escape key, focus trap, backdrop
interface MobileMenuProps {
  isOpen: boolean;
  onClose: () => void;
  locale: Locale;
  currentPath: string;
  navItems: Array<{ href: string; label: string }>;
}
 
// NavBar — desktop layout with hamburger for mobile
interface NavBarProps {
  locale: Locale;
  currentPath: string;
  navItems: Array<{ href: string; label: string }>;
  onMenuToggle: () => void;
}

> Simplify Navigation.tsx to a composition root under 40 lines.
> Manage isMenuOpen state, build navItems, render NavBar + MobileMenu. Run tests.

// src/components/Navigation.tsx — Final: 35 lines, composition root only
'use client';
 
import { useState } from 'react';
import { usePathname } from 'next/navigation';
import { useTranslations } from 'next-intl';
import { NavBar } from './NavBar';
import { MobileMenu } from './MobileMenu';
import type { Locale } from '@/i18n/routing';
 
export function Navigation({ locale }: { locale: Locale }) {
  const [isMenuOpen, setIsMenuOpen] = useState(false);
  const pathname = usePathname();
  const t = useTranslations('nav');
  const navItems = navigationItems.map((item) => ({
    href: `/${locale}${item.path}`, label: t(item.labelKey),
  }));
 
  return (
    <>
      <NavBar locale={locale} currentPath={pathname}
              navItems={navItems} onMenuToggle={() => setIsMenuOpen(true)} />
      <MobileMenu isOpen={isMenuOpen} onClose={() => setIsMenuOpen(false)}
                  locale={locale} currentPath={pathname} navItems={navItems} />
    </>
  );
}

# Final verification
> Run the Navigation tests.
# Result: 5/5 passing ✓

> Run vitest (all tests), tsc --noEmit, and npm run build. Report results.

✓ vitest: 47 tests passed, 0 failed
✓ tsc: no errors
✓ build: compiled successfully
 
git add -A
git commit -m "refactor(nav): complete Navigation split into NavBar, MobileMenu, NavLink"