Cursor 与 Codex：从技术债到现代化前端的工程化重构实战
接手一个遗留的 React 项目，就像走进一间堆满旧家具的仓库。组件文件动辄上千行，状态逻辑和 UI 渲染纠缠不清，样式表是十年前的技术栈，测试覆盖率几乎为零。每次新增功能都如履薄冰，生怕触动哪根脆弱的神经，导致整个应用崩溃。这种技术债的累积，不仅拖慢开发速度，更让团队士气低落。然而，现在你手中多了一件前所未有的利器——Cursor IDE 与 Codex 的深度联动。这不再仅仅是代码补全工具，而是一个能理解项目上下文、执行复杂工程任务、甚至能连续工作数小时的智能编程伙伴。本文将带你深入实战，看我们如何利用这套组合拳，对一个基于 React 16 和传统 CSS 的遗留学习应用，进行一场彻底的、工程化的现代化重构，最终将其升级为 React 18 + TypeScript + Chakra UI 的现代化应用。
1. 环境搭建与项目诊断：建立清晰的改造基线
在挥舞重构大锤之前，我们必须先给项目做一次全面的'体检'。盲目动手只会让混乱的代码更加混乱。我们的目标项目是一个名为'LingoLearn'的英语学习应用，代码库已经存在了三年，混合了 Class 组件和 Function 组件，样式直接写在 style 属性里，没有任何类型检查。
首先，我们需要在 Cursor 中配置好 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`。
创建好这个文件后，我们在 Cursor 中打开终端，启动 Codex CLI，并让它先对项目进行一轮静态分析。
# 在项目根目录下启动 Codex CLI 交互模式
codex --auto-edit
# 在打开的交互界面中，输入诊断指令
请分析当前 src 目录下的代码结构，识别出以下问题：
1. 最大的单个文件（行数>300）及其主要职责。
2. 混合了 UI 和业务逻辑的组件。
3. 潜在的性能瓶颈（如内联函数定义、不必要的重新渲染。）