Prompt to Refactor a React Component Safely

Structured AI agent prompt to refactor a complex React component with a read-audit-refactor-verify loop that prevents regressions.

Use this prompt to drive a disciplined component refactor — making the agent audit before changing, extract sub-components one at a time, and verify types after each step, rather than rewriting the whole file in one shot.

Main Prompt

You are refactoring a React component in a Next.js App Router TypeScript project.
The target file is: [INSERT PATH, e.g. src/components/ProductCard.tsx]

Refactor goal: split a large monolithic component into smaller, reusable pieces without
changing any observable behavior or UI output.

Follow these phases exactly — do not skip or combine them.

Phase 1 — Audit (no changes):
  - List every `useState` and `useEffect` call and what it manages.
  - List every prop the component accepts (with types).
  - List any inline sub-sections that could be extracted (e.g., a header, a list, a footer).
  - Identify any duplicated logic (e.g., the same conditional repeated).
  Output the audit as a numbered list. Stop and wait for my review.

Phase 2 — Extract pure sub-components (one at a time):
  - For each extractable section identified: create a new file, move the JSX and its
    required props, export a typed interface for the props, import and use it in the parent.
  - After each extraction: run `bun run typecheck`. If it fails, fix the error before
    the next extraction.

Phase 3 — Extract custom hooks:
  - If any `useEffect` + `useState` pair manages a single concern (e.g., a data fetch,
    a keyboard listener), extract it to `src/hooks/use<Name>.ts`.
  - After each extraction: run `bun run typecheck`.

Phase 4 — Remove duplication:
  - Consolidate any repeated conditional logic into a shared helper.
  - Do NOT change the logic — only the structure.

Phase 5 — Final verify:
  - Run `bun run typecheck`.
  - Show a summary of all files created or edited.
  - Do NOT change any business logic, API calls, or UI output.

After each phase, show the diff and wait for my confirmation before proceeding.

Implementation Notes

The key constraint is behavior preservation: the refactor must be a pure structural change. Ask the agent to confirm this after each phase by checking the diff contains no logic changes.
TypeScript is the safety net here: running typecheck after each extraction catches missing props or incorrect type narrowing immediately.
Custom hook extraction is only safe when the hook’s state is local to a single component instance. If state needs to be shared, do not extract — note it and stop.

Expected File Changes

src/components/<name>.tsx            (edited — original component, slimmed down)
src/components/<name>Header.tsx      (new — extracted sub-component)
src/components/<name>List.tsx        (new — extracted sub-component)
src/hooks/use<name>.ts               (new — extracted hook, if applicable)

Acceptance Criteria

bun run typecheck exits 0 after each phase.
The parent component props interface is unchanged.
No any types are introduced.
UI output is pixel-identical before and after (verified by visual inspection or snapshot tests).

Test Commands

bun run typecheck
bun run build
# if snapshot tests exist:
bun test --update-snapshots   # run BEFORE refactor to capture baseline
# then after refactor:
bun test                       # snapshots should pass without update

Common AI Mistakes

Changing a callback’s behavior while extracting it to a sub-component (e.g., adding useCallback with wrong deps, silently changing when it fires).
Extracting a hook that holds state shared across multiple component instances, causing state loss.
Introducing any types on extracted component props to avoid resolving complex generics.
Skipping typecheck between phases and accumulating errors that are hard to trace.

Fix Prompt

A type error appeared after an extraction or behavior changed. Fix in order:
1. Run `bun run typecheck` and show me only the errors — do not fix anything yet.
2. For each error: if it is a missing prop, add it to the extracted component's props interface.
   If it is an `any` type, resolve it using the type from the parent component's existing interface.
3. If any logic changed (a conditional, an effect dependency, a callback), revert that specific
   change only. Show the revert diff before applying it.