1. 项目概述一个为 Cursor 编辑器量身定制的 AI 编程伴侣如果你和我一样日常开发重度依赖 Cursor 这款“AI 驱动的编辑器”那你肯定对它的智能补全、代码生成和对话能力又爱又恨。爱的是它确实能极大提升效率恨的是它有时过于“天马行空”生成的代码需要你反复用自然语言去“调教”和修正上下文切换频繁反而打断了流畅的编程心流。real-jacket/todo-cursor这个项目就是为了解决这个痛点而生的。它不是一个独立的插件而是一个精心设计的“AI 编程提示工程”项目。简单来说它提供了一套结构化的、可复制的 Markdown 文档.cursorrules文件专门用来“训练”和“约束” Cursor 中的 AI 助手无论是 Claude 3.5 Sonnet 还是其他模型让 AI 生成的代码更符合你的个人习惯、项目规范和技术栈要求。你可以把它理解为一本给 AI 助手看的“员工手册”或“编程规范”。在没有这份手册之前AI 助手就像一个才华横溢但缺乏纪律的新人需要你事无巨细地指挥。而有了这份手册AI 助手就变成了一个深刻理解你团队文化、编码风格和最佳实践的核心骨干能产出更高质量、更少返工的代码。这个项目特别适合前端开发者尤其是 React/Vue 技术栈、全栈工程师以及任何希望将 Cursor AI 能力标准化、工程化的开发者。2. 核心设计思路从临时对话到工程化协作2.1 问题根源AI 编程的“上下文碎片化”在使用原生 Cursor 时我们与 AI 的交互模式通常是“一问一答”。比如“帮我写一个 React 函数组件它有一个输入框和一个列表实现过滤功能。” AI 会生成代码。然后你可能接着说“用 TypeScript 重写并且使用 Tailwind CSS 来样式化。” AI 会再次生成。接着你又发现“状态管理用useState太简单了换成Zustand吧。”这个过程存在几个明显问题信息丢失每次新的对话或指令AI 对之前约定的规范如代码风格、目录结构、使用的工具库记忆是模糊的。重复劳动你需要在每个新功能或新文件中反复重申相同的基础要求“请用 TypeScript”、“请遵循 Airbnb 代码规范”。风格不一致不同会话中AI 可能对“代码简洁”或“错误处理完善”有不同的理解导致项目代码风格割裂。todo-cursor项目的核心思路就是利用 Cursor 编辑器对.cursorrules文件的深度支持将那些重复的、基础的、原则性的要求固化到一个配置文件中为所有 AI 会话提供一个持久、统一的上下文背景。2.2 解决方案.cursorrules作为单一事实来源.cursorrules文件是 Cursor 的一个特性它允许你在项目根目录或任何子目录放置一个 Markdown 文件其中的内容会被自动加载到 AI 助手的上下文窗口中。todo-cursor项目本质上是一个.cursorrules文件的最佳实践模板库。它的设计哲学是“分层与模块化”全局规则定义适用于整个项目的基础原则如主要技术栈、代码风格Prettier, ESLint、提交信息规范。技术栈特定规则针对 React、Vue、Node.js 等提供具体的组件模式、API 设计规范、依赖管理建议。架构模式规则倡导如“单一职责”、“函数式核心、命令式外壳”等设计理念引导 AI 写出更易维护的代码。安全与性能守则内置常见的安全漏洞提示如 XSS、SQL 注入和性能优化建议让 AI 在生成代码时就具备“安全意识”。通过这种方式无论你是开启一个新的 Chat 会话还是使用“Cmd/Ctrl K”进行代码生成AI 助手都会优先参考.cursorrules中的“宪法”在此框架下进行创作从而保证输出的一致性。注意.cursorrules文件的内容会占用 AI 模型的上下文令牌Tokens。因此项目的另一个设计要点是“精炼有效”避免放入冗长的示例代码而是用清晰的指令和约束来描述规则。3. 核心规则解析与自定义实践real-jacket/todo-cursor仓库提供了丰富的规则范例我们可以将其核心部分拆解出来并探讨如何根据自身项目进行定制。以下是一个融合了项目思想并加以扩展的.cursorrules文件示例我将分段进行解读。3.1 项目元数据与核心原则# 项目 AI 编程规范 (.cursorrules) **项目名称**: MyAwesomeProject **主要技术栈**: TypeScript, React 18, Next.js 14, Tailwind CSS, Zustand **包管理器**: pnpm **代码风格**: ESLint (Airbnb 配置扩展) Prettier **测试框架**: Vitest React Testing Library ## 核心开发原则 1. **类型安全至上**所有代码必须使用 TypeScript并定义清晰的接口和类型。禁止使用 any 类型如遇复杂类型可暂时使用 unknown 并辅以类型守卫。 2. **函数式优先**优先使用纯函数和 React 函数组件。副作用应被严格管理集中在 useEffect、事件处理器或状态管理库中。 3. **组件设计**遵循单一职责原则。组件应小巧、可复用。UI 组件与逻辑容器组件应尽可能分离。 4. **性能意识**默认使用 React.memo 包装非根组件。注意依赖数组避免不必要的重渲染。对于大型列表必须使用虚拟化。 5. **错误处理**所有异步操作fetch, promises必须有基本的错误处理try-catch 或 .catch。向用户展示友好的错误信息。自定义要点这部分是你的项目“宪法总纲”。明确技术栈能避免 AI 推荐错误的技术方案比如在你的 Next.js 项目里建议使用 Vite 配置。“禁止使用any”是一条黄金指令。我发现在实践中明确告诉 AI“如果无法推断类型请使用unknown并询问我”比单纯禁止更能产生高质量的交互。3.2 目录结构与文件命名规范## 目录结构与命名 - src/components/: 可复用 UI 组件。每个组件一个文件夹包含 index.tsx、types.ts、styles.module.css (如需要) 和 Component.test.tsx。 - 命名PascalCase如 Button, UserAvatar。 - src/hooks/: 自定义 React Hooks。命名useCamelCase如 useLocalStorage, useDebounce。 - src/stores/: Zustand 状态切片。命名use[Feature]Store如 useAuthStore。 - src/lib/: 工具函数、API 客户端配置、常量。命名清晰的小写字母如 api-client.ts, format-date.ts。 - src/app/: (Next.js App Router) 页面和布局。遵循 Next.js 约定。 - 文件命名组件和主要文件使用 PascalCase工具函数、样式文件使用 kebab-case 或 camelCase。实操心得 为 AI 明确目录结构极其重要。当我规定“每个组件一个文件夹”后AI 在创建新组件时会自动生成包含索引文件、类型定义和测试文件的完整结构而不是仅仅扔出一个孤零零的.tsx文件。这大大提升了项目的可维护性起点。3.3 针对特定技术的详细规则这是体现todo-cursor项目价值的关键部分它提供了“如何写”的具体指令。React 组件规则示例## React 组件规范 ### 组件定义 - 使用 export default function ComponentName() 语法。 - 使用 interface 定义组件 Props并为可选参数提供默认值。 - **示例模板** tsx interface ButtonProps { children: React.ReactNode; variant?: primary | secondary; onClick?: () void; } export default function Button({ children, variant primary, onClick }: ButtonProps) { return ( button className{px-4 py-2 rounded ${variant primary ? bg-blue-500 : bg-gray-500}} onClick{onClick} {children} /button ); } ### 状态与副作用 - 优先使用 useState 处理本地 UI 状态。 - 复杂业务状态应提升至 Zustand Store。 - useEffect 必须包含清晰的依赖数组并处理清理函数cleanup。API 调用规则示例## API 交互规范 ### 客户端 - 使用 src/lib/api-client.ts 中导出的、已配置的 axios 或 fetch 实例。 - 所有 API 响应必须进行类型断言或验证建议使用 zod 进行运行时验证。 - **必须进行错误处理** tsx const fetchUser async (id: string) { try { const response await apiClient.getUser(/users/${id}); return response.data; } catch (error) { console.error(Failed to fetch user ${id}:, error); // 将错误抛给上层组件或转译为用户友好信息 throw new Error(获取用户信息失败请稍后重试); } }; 自定义要点 不要只写“要这样做”而要提供具体的、可复制的代码模板。AI 非常擅长遵循示例。当你提供了一个Button组件的完整示例后它后续生成Input、Card等组件时都会自动套用相同的结构和风格。4. 集成与工作流实战4.1 如何在项目中引入与配置获取规则模板访问real-jacket/todo-cursorGitHub 仓库浏览其中的.cursorrules示例文件。不要直接复制整个文件而是挑选与你技术栈相关的部分。创建本地规则文件在你的项目根目录下创建.cursorrules文件。混合与裁剪将挑选出的规则结合我上面提到的结构和你的具体需求编写成你自己的.cursorrules。一个常见的策略是先从一个精简版本开始只包含技术栈和核心原则然后在开发过程中遇到 AI 反复犯的同类错误时再将对应的规则补充进去。分层规则对于大型项目你可以在不同的子目录下放置额外的.cursorrules文件。例如在src/components/ui/下可以有一个更严格的 UI 组件规则覆盖根目录的通用规则。Cursor 会合并这些规则。4.2 与 Cursor 功能的深度结合.cursorrules的真正威力在于与 Cursor 的以下功能结合Chat 会话每次开启新的 ChatAI 助手会自动读取规则。你可以直接说“按照我们的规范创建一个用户设置页面。” AI 会基于规则中定义的 Next.js App Router 结构、Tailwind 样式和组件模式来生成代码。“Cmd/Ctrl K” 代码生成在编辑器中选择一段代码或注释使用此快捷键输入指令如“提取为自定义 Hook”。AI 会参考规则中关于 Hook 的命名规范useCamelCase和位置src/hooks/来执行操作。代码审查你可以将一段代码丢给 AI 并问“这段代码符合我们的规范吗” AI 会依据.cursorrules给出具体的修改建议例如“根据规范第 3 条这个组件过于庞大建议将dataFetching逻辑提取到一个自定义 Hook 中。”4.3 迭代与优化你的规则集规则文件不是一成不变的。一个高效的用法是记录问题在开发中如果 AI 生成了不符合你预期的代码例如用了var而不是const/let或者错误处理不完善不要仅仅手动修改。抽象规则思考这个问题的本质是什么是“变量声明规范”问题还是“异步错误处理规范”问题更新规则将这条新规则用清晰的语言写入.cursorrules。例如“所有变量声明必须使用const或let禁止使用var。” 或者 “所有fetch操作必须包裹在try-catch块中并记录错误日志。”验证规则在后续的类似任务中观察 AI 是否遵循了新规则。如果没有可能需要调整规则的表述方式。5. 常见问题与效能提升技巧5.1 规则不生效或部分失效检查文件位置与名称确保文件名为.cursorrules有点开头的隐藏文件并且位于项目根目录或当前工作目录的上级目录中。检查上下文长度如果规则文件过长可能会超出 AI 模型的上下文窗口导致部分规则被“遗忘”。解决方案是精简规则删除过时的或优先级低的条目优先保留核心、高频的规则。可以将详细的代码示例移出用简练的指令代替。规则冲突子目录的.cursorrules会与父目录的规则合并如果指令冲突可能会导致行为不可预测。确保规则之间是互补而非矛盾的。5.2 如何编写更有效的规则正向指令优于反向禁止与其说“不要写内联样式”不如说“所有样式请使用 Tailwind CSS 工具类定义”。提供具体示例如前所述一个简单的代码片段胜过千言万语。展示“好代码”的样子。使用场景化描述“当需要从服务器获取数据时请使用src/lib/api-client.ts中的get方法并处理错误。” 这比“好好处理错误”要具体得多。设定优先级可以用## IMPORTANT:或**关键**来强调最重要的规则。5.3 超越.cursorrules构建项目知识库.cursorrules主要约束代码风格和通用模式。对于项目特定的业务逻辑、领域知识可以额外创建docs/目录下的 Markdown 文件如docs/business-logic.md,docs/architecture-decisions.md然后在需要时通过 Cursor 的“引用文件”功能符号将这些文档作为上下文提供给 AI。这相当于为 AI 配备了项目的“业务手册”。5.4 实测效能对比在我自己的一个中型 React 项目中引入定制化的.cursorrules后最明显的改变是代码审查时间减少AI 生成的初始代码质量显著提高减少了“变量命名不规范”、“缺少错误处理”等低级问题的审查。沟通成本降低我不再需要频繁地说“请用 TypeScript”、“请按 Airbnb 规范格式化”这些已成为默认前提。新人上手更快即使是团队新成员使用 Cursor也能快速产出符合项目规范的代码降低了统一风格的培训成本。这个项目的精髓不在于那一个文件而在于它所倡导的“将 AI 协作工程化”的思想。它迫使开发者去思考和沉淀什么才是我们项目的好代码标准将这些标准显式化、文档化不仅是为了约束 AI更是为了澄清团队内部的共识最终提升整个代码库的质量和开发体验。从与 AI 的随机对话转向有纪律、可预测的工程协作这才是real-jacket/todo-cursor带来的真正范式转变。