「5 个 Markdown 文件 + 1 句提示词」让 AI 精准重构你的 React 组件 | 附完整模板

这个场景你一定经历过你给 ChatGPT/Claude 一个又臭又长的 React 组件说帮我重构一下让它更清晰。结果要么改错了交互逻辑导致功能崩溃改变了接口契约后端完全适配不了代码风格跳戏跟项目里其他组件风格完全不一样反复来回折腾半天还是不对劲问题不在 AI 不够聪明。问题在于你给 AI 的信息不够系统。AI 就像一个新来的实习生如果你只甩给他一个组件说帮我改他没有背景知识、没有项目约定、不知道你的底线在哪儿改出来的东西自然南辕北辙。但如果你给他一套「风格指南」「反例库」「项目背景」「具体任务说明」他就能在你的框架内精准操作。这篇文章我就给你一套可复用的「多文件提示词系统」。只需要维护 5 个 Markdown 文件用一句简短的提示词就能让 AI 精准重构代码。核心方法为什么「多文件分离」比「长提示词」更有效很多人的第一反应是提示词写得长一点不就行了你好 AI请帮我重构这个 React 组件。 要求如下 1. 使用函数组件 2. 避免超大文件 3. 类型安全 4. 不破坏现有交互 5. ...后面还有 20 条这样的长提示词有个问题AI 很容易看花眼优先级搞错。一行行列下来AI 可能记住了 1、2、3但在真正写代码的时候面对一个复杂的决策点它往往会忘记 4、5 的重要性。多文件系统的精妙之处在于 好的风格 (01_good_patterns.md) ↓ AI 学习标准做法 ↓ 坏的做法 (02_bad_patterns.md) ↓ AI 理解边界和禁区 ↓ 项目约束 (03_context.md) ↓ AI 知道这个项目的特殊性 ↓ 具体任务 (04_task.md) ↓ ✅ AI 精准执行避免偏离关键区别长提示词 AI 逐项检查清单容易遗漏多文件系统 AI 先学习标准再理解禁区最后执行任务层层递进不易出错这也是 Anthropic 等大公司的工程师在与 AI 协作时的常用方法。完整系统5 个文件分别做什么先看架构图主提示词 (1 句话) ↓ ├─→ 01_good_patterns.md (正面示范) ├─→ 02_bad_patterns.md (反面警示) ├─→ 03_project_context.md (项目背景) ├─→ 04_current_task.md (具体任务) └─→ 05_output_checklist.md (交付标准)文件 1️⃣好的 React 模式 (01_good_patterns.md)目的给 AI 示范你期望的代码风格。为什么需要没有正面示范AI 猜你的品味猜不准。这个文件里放 3-5 个你喜欢的代码样例标注为什么这样写。比如# Good React Patterns ## 函数组件 Hooks 我们统一用函数组件和 Hooks不写 Class 组件。 ✅ 推荐这样写 tsx export function UserForm({ onSubmit }) { const [name, setName] useState(); const handleSubmit async (e) { e.preventDefault(); await onSubmit(name); }; return form onSubmit{handleSubmit}.../form; }为什么简洁没有 this 的混乱Hooks 更容易组合和复用TypeScript 支持更好文件 2️⃣坏的 React 模式 (02_bad_patterns.md)AI 看到这个就知道你的底线是什么。 **目的**告诉 AI 「绝对不要这样写」。 **为什么需要**有些错误很容易重犯你不明确禁止AI 会踩坑。 比如 markdown # Bad React Patterns ## ❌ 不要写超大组件 tsx export default functionOrderForm() { const [a, setA] useState(); const [b, setB] useState(); // ... 30 个 useState useEffect(() { fetch(/api/init).then(...); fetch(/api/validate).then(...); // ... 混乱的副作用 }, []); return div/* 200 行 JSX *//div; }问题一个文件做了 5 件事状态乱飞难以追踪一改就容易破坏文件 3️⃣项目背景 (03_project_context.md)明确列出来AI 就不会重蹈覆辙。 **目的**告诉 AI 你的技术栈和团队约定。 **为什么需要**AI 需要知道这是 Vue 项目还是 React 项目用 CSS Modules 还是 styled-components。 比如 markdown # Frontend Project Context ## 技术栈 - React 18 - TypeScript - React Query (数据请求) - Ant Design (UI 组件库) - CSS-in-JS (styled-components) ## 团队约定 - 所有组件必须有 TypeScript 类型标注 - 表单逻辑用 React Hook Form 封装 - API 请求通过 React Query 的 hooks - 不再维护任何 Class 组件 ## 设计风格 - 表单交互保持简洁直接 - 错误提示友好而不恐怖 - 尽量保持现有交互习惯AI 知道了这些就能在重构时保持一致性。文件 4️⃣具体任务 (04_current_task.md)目的明确告诉 AI「这次重构的目标是什么」。为什么需要不同的任务目标重构方向完全不同。比如# Current Task: OrderForm Component Refactor ## 目标 - 拆分 OrderForm让结构更清晰 - 减少组件体积现在 400 行 - 改进状态管理避免 useState 散乱 - 保持用户看到的交互完全不变 ## 当前代码问题 - 数据获取、表单逻辑、提交逻辑混在一个组件 - 没有类型标注 - 难以测试和复用 ## 约束条件 - ⚠️ 不能改 API 契约/api/order/init 和 /api/order/submit - ⚠️ 不能改用户看到的字段和文案 - ✅ 可以拆成多个子组件 - ✅ 可以引入 React Query如果需要 ## 成功标志 - 主组件 150 行 - 有 TypeScript 类型 - 能清晰看到数据流向这样 AI 就明白了这不是随便改而是有边界的改。文件 5️⃣交付标准 (05_output_checklist.md)目的告诉 AI「完成后我会怎么检查你的工作」。为什么需要让 AI 知道质量标准自己会主动检查。比如# Output Checklist 重构完成后我会检查这些 ## 代码质量 - [ ] 没有 any 类型全是有效的 TS 类型 - [ ] 组件职责清晰一个组件只做一件事 - [ ] 状态最小化不重复保存可计算的值 - [ ] 没有多余的 useEffect副作用集中管理 ## 功能完整性 - [ ] 所有原有功能都保留 - [ ] 用户看到的界面和交互一模一样 - [ ] API 请求的入参出参没变 ## 代码美学 - [ ] 没有注释掉的代码 - [ ] 命名清晰有意义 - [ ] 缩进和格式一致 - [ ] 可以直接跑没有报错 ## 可维护性 - [ ] 如果要再加一个字段改在哪儿很明显 - [ ] 同事看这个代码能在 5 分钟内理解AI 看到这个清单会自觉地朝这个方向努力。实战演示从混乱的 OrderForm 到清晰的组件结构现在我们用一个真实的例子演示这套系统怎么用。第 1 步准备 5 个 Markdown 文件假设你在项目里建了一个文件夹project/ ├── refactor-prompts/ │ ├── 01_good_patterns.md │ ├── 02_bad_patterns.md │ ├── 03_project_context.md │ ├── 04_current_task.md │ └── 05_output_checklist.md ├── src/ └── ...第 2 步填充这些文件参考下面的「完整模板」部分你就能快速填充这 5 个文件。一般来说01_good_patterns从你们项目现有的好代码里摘抄 2-3 个例子02_bad_patterns列出你见过的最常见的 3-5 个错误做法03_project_context复制粘贴团队 wiki改个名字04_current_task描述这次重构的目标和约束05_output_checklist定义什么叫重构成功第 3 步用一句简短提示词打开 Claude/ChatGPT上传这 5 个文件然后发这一句我想重构一个遗留的 React 订单表单组件 让代码更容易理解、更好维护 但要保证在不改变现有交互和业务行为的前提下更安全地修改。 请先完整阅读这 5 个文件 然后在开始修改前向我提出澄清问题 比如能否拆组件、能否引入新库、是否要加校验等。 只有在我们对齐后你再给出重构方案和代码。简洁、清晰、有边界。第 4 步AI 会反问你澄清问题AI 此时不会立刻改代码而会问你我注意到当前的 OrderForm 调用了 3 个不同的 API。我看到项目里用了 React Query。我能问几个问题吗我可以用 React Query 来管理这些请求吗还是要继续用 fetch按你的 03_project_context.md能拆出一个 OrderFormContainer 吗提交时有错误重试机制吗这正是你想要的。AI 在你的框架内思考而不是凭空猜测。第 5 步你回答问题AI 执行重构你回答完AI 就会给出重构方案 1. OrderFormContainer (数据获取 提交逻辑) 2. OrderForm (表单 UI 状态管理) 3. ShippingOptions (配送方式子组件) 4. CouponInput (优惠券子组件) 然后是完整的代码每个组件都有类型标注。整个过程从混乱的一句需求变成了系统化的对话和交付。模板递出直接复制这 4 个文件以下是你可以直接拿去用的模板。每个文件基于 React 18 TypeScript 的通用最佳实践改成你自己的项目细节就行。模板 1️⃣01_good_patterns.md# Good React Patterns ## 函数组件 Hooks必须 ✅ 使用函数组件和 Hooks \\\tsx type UserFormProps { initialValues: User; onSubmit: (values: User) Promisevoid; }; export function UserForm({ initialValues, onSubmit }: UserFormProps) { const [values, setValues] useState(initialValues); const [loading, setLoading] useState(false); const [error, setError] useStatestring | null(null); const handleSubmit async (e: React.FormEvent) { e.preventDefault(); setLoading(true); setError(null); try { await onSubmit(values); } catch (err) { setError(提交失败); } finally { setLoading(false); } }; return ( form onSubmit{handleSubmit} {/* UI */} /form ); } \\\ **为什么** 简洁清晰没有 thisHooks 可复用。 ## 容器组件分离逻辑 ✅ 数据获取和 API 调用单独处理 \\\tsx export function UserFormContainer() { const { data: initialValues } useUserQuery(); const mutation useUpdateUserMutation(); if (!initialValues) return Spinner /; return ( UserForm initialValues{initialValues} onSubmit{values mutation.mutateAsync(values)} / ); } \\\ **为什么** 容器管理数据表单只管 UI职责明确。 ## 清晰的 JSX 结构 ✅ 不在标签里嵌套复杂逻辑 \\\tsx return ( form onSubmit{handleSubmit} Input label名字 value{values.name} onChange{value setValues(prev ({ ...prev, name: value }))} / Button typesubmit disabled{loading} {loading ? 提交中... : 提交} /Button {error Alert typeerror{error}/Alert} /form ); \\\ **为什么** 一眼能看清结构代码脑力消耗少。 ## 类型安全 ✅ 所有东西都有类型 \\\tsx // 定义类型 type FormValues { name: string; email: string; age: number; }; // 组件声明时标注 props 类型 type MyFormProps { onSubmit: (values: FormValues) void; }; export function MyForm({ onSubmit }: MyFormProps) { // ... } \\\ **为什么** 编译期间就能发现错误比运行时发现早。模板 2️⃣02_bad_patterns.md# Bad React Patterns to Avoid ## ❌ 不要写超大组件一个文件 200 行 \\\tsx export default function OrderForm() { const [name, setName] useState(); const [phone, setPhone] useState(); const [address, setAddress] useState(); const [shipping, setShipping] useState(standard); const [loading, setLoading] useState(false); const [message, setMessage] useState(); useEffect(() { fetch(/api/order/init) .then(res res.json()) .then(data { setName(data.name); setPhone(data.phone); // ... }); }, []); const submit () { setLoading(true); fetch(/api/order/submit, { /* ... */ }) .then(res res.json()) .then(data setMessage(data.ok ? 成功 : 失败)) .finally(() setLoading(false)); }; return div/* 这里 150 行 JSX *//div; } \\\ **问题** 初始化、表单、提交、展示消息四件事混在一起。改一个东西容易破坏其他的。 ## ❌ 不要在 JSX 里写复杂逻辑 \\\tsx {items.map(item ( div key{item.id} {item.price 100 user user.vip ? ( span{item.price * 0.8}/span ) : item.price 100 ? ( span{item.price * 0.9}/span ) : ( span{item.price}/span )} /div ))} \\\ **问题** 规则隐藏在标签里无法单独测试以后改价格逻辑很痛苦。 ## ❌ 不要滥用 any 类型 \\\tsx function handleChange(e: any) { setValue(e.target.value); } const data: any response.data; \\\ **问题** any 就是放弃了 TypeScript 的保护。等于开了个后门随时可能出错。 ## ❌ 不要混乱的 useEffect 依赖 \\\tsx useEffect(() { fetch(/api/data) .then(setData) .catch(setError); }, []); // ❌ 空依赖数组但后面可能会用到 userId导致重复请求 useEffect(() { const timer setTimeout(() { setMessage(); }, 3000); // ❌ 没有清理 timer会导致内存泄漏 }, [message]); \\\ **问题** 依赖管理不清副作用不可预期。模板 3️⃣03_project_context.md# Frontend Project Context ## 技术栈 - React 18 - TypeScript 5.x - React Query v5 (数据请求) - React Router v6 (路由) - Ant Design v5 (UI 组件库) - styled-components (样式) ## 编码约定 1. **组件必须用函数组件 Hooks不写 Class 组件** 2. **所有文件都要有 TypeScript 类型标注不许用 any** 3. **表单用 React Hook Form 或 AntD Form自己不要写 useState** 4. **API 请求通过 React Query 的 custom hooks 封装** 5. **单文件不超过 200 行超过就要考虑拆** ## 项目结构 \\\ src/ ├── pages/ # 页面级组件 ├── components/ # 可复用组件 ├── hooks/ # custom hooks ├── api/ # API 调用用 React Query 封装 ├── types/ # TypeScript 类型定义 └── utils/ # 工具函数 \\\ ## UI 交互原则 - 表单提交后 Loading 时按钮禁用 - 错误提示用友好的语气出错了请稍后重试 而非 ERROR - 成功提示 2-3 秒后自动消失 - 不删除已填的内容除非用户明确确认 ## 性能和测试 - 关键业务逻辑要有简单的 Jest 单测 - 避免在 render 时做复杂计算 - 列表渲染 50 项时考虑虚拟滚动 ## 风格示例 - 使用 Ant Design 的 Button、Input、Form、Modal 等组件 - 自定义样式用 styled-components不用 inline style - 响应式设计mobile first模板 4️⃣04_current_task.md# Current Task: [组件名称] Refactor ## 重构目标 - [ ] 降低圈复杂度代码逻辑分支清晰 - [ ] 拆分为更小的子组件单一职责 - [ ] 完善 TypeScript 类型标注 - [ ] 不改变 API 接口契约和用户交互 ## 现有代码问题 - 单文件 [400] 行包含初始化、表单、提交、错误处理 - 有 [10] 个 useState状态管理混乱 - 没有类型标注全是隐式 any - useEffect 依赖管理不清 ## 重构边界什么能改什么不能改 ### ✅ 可以改 - 拆成多个子组件 - 引入 React Query 管理数据请求 - 添加 TypeScript 类型 - 重组 useState减少状态数量 - 调整内部函数的组织方式 ### ⚠️ 不能改 - **API 契约**/api/order/init 和 /api/order/submit 的请求参数和返回值 - **UI 外观**用户看到的表单字段、按钮位置、样式风格 - **交互流程**提交、加载、错误提示的顺序和行为 ## 成功标志 - [ ] 主组件 150 行 - [ ] 拆分了 2-3 个有意义的子组件 - [ ] 完整的 TypeScript 类型 - [ ] 没有 any 或隐式 any - [ ] 所有功能都能正常跑没有破坏关键经验这套系统的实战细节如何快速填充这 5 个文件不用从零开始。01 和 02从你们项目现有代码里摘抄。找 3-5 个做得好的组件和 3-5 个做得不好的放进去就行。03就是你们团队的 wiki改个名字。04复制上面的模板填进你的组件名称和约束。05定义什么叫成功。一般就是没有 any、职责清晰、功能完整。整个过程可能 30 分钟搞定。多个项目怎么复用建一个refactor-templates/文件夹放 4 个基础模板refactor-templates/ ├── 01_good_patterns_base.md ├── 02_bad_patterns_base.md ├── 03_project_context_base.md └── 04_current_task_base.md每次新的重构任务复制这 4 个文件改个项目细节就行。能和其他 AI 工具用吗完全可以。这套系统对 Claude、ChatGPT、Gemini 都有效因为原理是一样的给 AI 足够的上下文和边界它就能精准执行。总结从祈祷 AI 别搞砸到信心满满地交付这套「5 文件 1 提示词」系统的核心价值是可复用建一次用一年。每次改个项目细节就行。系统化不是凭感觉改是有标准、有边界、有检查清单。可控AI 不会瞎改。改之前会问你澄清问题确保方向对。易于协作你和 AI 有了共同语言。而且新成员加入看这 5 个文件就懂团队的约定。一旦你建立了这套系统你会发现不是 AI 不够聪明是我之前没有给它足够的框架。好了现在你手里有了完整的模板。下一步就是新建一个 refactor-prompts/ 文件夹填充这 5 个文件然后试一次。我敢保证效果会比之前甩代码瞎改好十倍。结尾这套方法我用过很多次每次都起效。但我很好奇你在用 AI 改代码时最常遇到的问题是什么是代码风格不对劲还是改错了逻辑还是 API 接口对不上在评论区分享一下你的AI 踩坑记。也许下一篇我们可以针对你遇到的具体问题设计一个更细化的提示词系统 《Claude Code 从入门到精通》推荐阅读大部分人用 Claude Code 的方式是错的。这本手册教你从AI键盘升级到AI开发团队一个人做出三个人的活。这本手册解决什么问题你可能已经在用 Claude Code 了——让它帮你写函数、补全代码、跑测试。但你有没有想过你现在的用法可能只发挥了它 10% 的能力。大多数开发者把 Claude Code 当成更快的键盘——你说一步它做一步每个任务来回对话十几轮。而真正高效的用法是把它当成你的开发团队——你说清楚要什么结果它自己规划、自己执行、自己验证一轮对话搞定。这个转变不难但需要一套系统的方法。这本手册就是这套方法。你会学到什么地基篇第01-04课——建立正确认知完成第一次实操Claude Code 的真实定位不是代码补全是能自主执行的 AI 开发团队你的第一次 Director Mode 体验同一个任务从 8 轮对话缩减到 1 轮结构化 Prompt 四要素目标、上下文、质量标准、约束——10 组正反对比纠错方法论三种偏差类型对症下药最多 3 轮修正到位核心技能篇第05-09课——掌握 Director Mode 三大支柱目标优于指令5 个场景演示怎么把指令型改写成目标型效果差 3 倍并行策略让 Claude 同时处理多个任务30 分钟的活压到 10 分钟结果验证5 个维度的系统检查法 一段自查指令让 Claude 自己先验一轮CLAUDE.md写一次、永远生效的项目规范文件——附 3 个行业模板前端/后端/全栈10 个高频场景 Prompt 模板复制、改几个词、直接发给 Claude⚡工作流篇第10-13课——把技能串成日常习惯从晨会到代码提交一天的工作流中每个环节怎么用 Claude Code团队协作怎么在团队里推广共享规范统一效率自动化Hooks让 Claude 在特定条件下自动执行不需要手动发 prompt效率度量可量化的数据证明你变快了实战篇第14-16课——三个完整项目案例从零开发一个完整 API 模块需求分析→设计→实现→测试→上线的全流程线上紧急 Bug 修复在老板催你的压力下保持效率的完整方案老项目系统性重构两年的烂代码怎么分阶段安全重构适合谁✅ 已经在用 Claude Code但觉得效果一般的开发者✅ 想系统学习 AI 辅助编程而不只是零散试试的开发者✅ 想在团队里推广 Claude Code 的技术负责人✅ 能看懂代码、能描述需求但不一定是资深架构师的开发者不适合谁❌ 完全不懂编程的人本手册不教编程基础❌ 期望AI替我做所有事的人Claude 是团队你是导演导演不能缺席这本手册的特点不是文档翻译是实战方法论。每一课都有真实的开发场景、可运行的代码示例、可以直接复制的 prompt 模板。不只讲成功也讲翻车。每一课都有常见错误翻车场景纠错方法——因为你一定会遇到提前知道比踩了再学代价小得多。每一课都有课后实操。不是想一想那种是打开终端、发一个 prompt、看到结果那种。看完不练等于没看。附赠实用工具包10 个高频场景 Prompt 模板可直接套用3 份 CLAUDE.md 行业模板前端 React / 后端 NestJS / 全栈 Next.js验证矩阵速查表 安全检查清单 并行决策流程图《Claude Code 从入门到精通》—— 16 课系统教学让你从 Claude Code 的使用者变成导演。 开始阅读《Claude Code 从入门到精通》目标优于指令Director Mode 第一支柱五第06课让 Claude 自己分配任务——并行 Agent 策略