安全重构 React 组件的提示词
结构化 AI 代理提示词，用于通过阅读-审计-重构-验证循环安全地重构复杂 React 组件，防止回归问题。
CursorClaude CodeCodexWindsurf Next.jsTypeScript
使用此提示词进行规范化的组件重构 —— 让代理在修改前进行审计，逐个提取子组件，并在每一步后验证类型，而不是一次性重写整个文件。
主要提示词
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 withoutchanging 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.实现说明
- 关键约束是行为保持：重构必须是纯粹的结构性更改。要求代理在每个阶段后通过检查差异不包含逻辑更改来确认这一点。
- TypeScript 是安全网：每次提取后运行
typecheck能立即捕获缺失的 props 或不正确的类型收窄。 - 自定义 hook 提取仅在该 hook 的状态局限于单个组件实例时才安全。如果状态需要共享，则不要提取 —— 记录并停止。
期望的文件变更
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)验收标准
bun run typecheck在每个阶段后退出码为 0。- 父组件 props 接口保持不变。
- 不引入任何
any类型。 - UI 输出在前后保持像素级一致（通过视觉检查或快照测试验证）。
测试命令
bun run typecheckbun 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常见的 AI 错误
- 在将回调提取到子组件时更改其行为（例如，添加带有错误依赖项的
useCallback，悄悄改变其触发时机）。 - 提取持有跨多个组件实例共享状态的 hook，导致状态丢失。
- 在提取的组件 props 上引入
any类型以规避复杂泛型的解析。 - 在阶段之间跳过
typecheck，导致错误累积且难以追踪。
修复提示词
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.