Cursor + GPT-5-Codex：从技术债泥潭到现代化前端的工程化重构实战
接手一个遗留的React项目，就像走进一间堆满旧家具的仓库。组件文件动辄上千行，状态逻辑和UI渲染纠缠不清，样式表是十年前的技术栈，测试覆盖率几乎为零。每次新增功能都如履薄冰，生怕触动哪根脆弱的神经，导致整个应用崩溃。这种技术债的累积，不仅拖慢开发速度，更让团队士气低落。然而，现在你手中多了一件前所未有的利器——Cursor IDE 与 GPT-5-Codex 的深度联动。这不再仅仅是代码补全工具，而是一个能理解项目上下文、执行复杂工程任务、甚至能连续工作数小时的'数字编程伙伴'。本文将带你深入实战，看我们如何利用这套组合拳，对一个基于React 16和传统CSS的遗留学习应用，进行一场彻底的、工程化的现代化重构，最终将其升级为React 18 + TypeScript + Chakra UI的现代化应用。
1. 环境搭建与项目诊断：建立清晰的改造基线
在挥舞重构大锤之前，我们必须先给项目做一次全面的'体检'。盲目动手只会让混乱的代码更加混乱。我们的目标项目是一个名为'LingoLearn'的英语学习应用，代码库已经存在了三年，混合了Class组件和Function组件，样式直接写在style属性里，没有任何类型检查。
首先，我们需要在Cursor中配置好GPT-5-Codex环境。安装官方Codex插件后，你会在侧边栏看到一个全新的机器人图标。关键一步是在项目根目录创建 AGENTS.md 文件。这个文件是Codex理解你项目规范、技术栈和重构目标的'项目圣经'。它远比简单的提示词有效，因为它能持续地为AI提供上下文。
# AGENTS.md - LingoLearn重构项目指南 ## 项目概述 本项目是一个遗留的英语学习单页应用（SPA），当前技术栈为React 16 + 内联CSS。本次重构的目标是将其现代化，提升可维护性、性能及开发体验。 ## 目标技术栈 - **框架**: React 18 (使用严格模式) - **语言**: TypeScript 5.x (启用严格类型检查) - **UI库**: Chakra UI v2.x (移动端优先的响应式设计) - **构建工具**: Vite 5.x (替代Create React App) - **状态管理**: 逐步引入Zustand，替换原有的Context滥用 - **测试**: Vitest + React Testing Library，目标覆盖率 > 80% - **代码规范**: ESLint (Airbnb配置扩展) + Prettier ## 重构核心原则 1. **渐进式重构**: 优先重构高频访问和即将修改的模块，确保业务连续性。 2. **关注点分离**: 将业务逻辑、状态管理和UI渲染拆分为独立单元。 3. **组件原子化**: 大型组件拆分为更小、可复用的Presentational组件和Container组件。 4. **类型安全**: 为所有函数、组件Props和API响应添加完整的TypeScript接口定义。 5. **性能优先**: 应用React.memo、useCallback、useMemo，并对长列表实施虚拟滚动。 ## 文件结构规范
src/ ├── components/ # 通用UI组件 (原子设计：atoms, molecules, organisms) ├── features/ # 功能模块 (e.g., auth, flashcards, quiz) ├── hooks/ # 自定义React Hooks ├── stores/ # Zustand状态切片 ├── services/ # API客户端与业务逻辑 ├── utils/ # 纯函数工具 ├── types/ # 全局TypeScript类型定义 └── assets/ # 静态资源
## 代码风格 - 使用函数式组件和React Hooks。 - 组件命名使用PascalCase，文件使用kebab-case。 - 默认导出React组件，命名导出工具函数和类型。 - 禁止使用`any`类型，优先使用更具体的类型或`unknown`。
