在软件工程领域，“vibe coding”（凭借自然语言意图与直觉驱动 AI 生成代码的开发范式）正在迅速普及。许多开发者在初期体验后往往会陷入调试深渊，代码仓库充斥着风格冲突、幻觉引入的私有 API 以及跨文件依赖断裂。表面看这是底层大语言模型推理能力的局限，本质是开发者在提示词输入阶段缺乏精准的上下文控制，把架构决策与状态维护完全丢给了无状态的推理引擎。
要让 vibe coding 从“碰运气的黑盒实验”变成工业级交付工具，核心在于重塑与 Cursor 的交互工作流。通过结构化的上下文工程（Context Engineering）和系统化的 Rules 配置体系，开发者能够将随机性极高的自然语言收敛为具备强约束的工程指令，从根本上解决多文件协同与代码漂移问题。
认知重塑：从自然语言闲聊转向精准的上下文工程
在 Cursor 中，上下文工程指主动筛选、组织并注入与当前任务最相关的代码定义、依赖关系和运行状态，避免模型在海量无关标记（Token）中迷失。默认状态下，Cursor 会自动抓取当前处于激活状态的标签页与光标选区，但当项目规模扩张到数十个模块时，这种被动机制会导致模型经常“胡思乱想”。
模糊的提示词会直接导致高熵的代码生成。 许多开发者习惯输入“帮我修一下这个支付接口的报错”，这迫使 AI 在缺少入参类型定义、外部依赖库版本以及具体堆栈上下文的情况下进行盲猜。高效的做法是在提示词中明确遵循“位置、期望状态、变更因由”三元组，彻底剥离多余的修饰词。
目标文件：@src/services/payment.ts
依赖接口：@src/types/order.ts 中的 CreatePaymentPayload
问题现象：当 payload.amount 为浮点数时，Stripe SDK 抛出 400 错误
修改要求：在调用 SDK 前将其转换为整数分（cents），并补充边界测试
在日常对话与行内编辑中，灵活运用 @ 符号系统能直接降低模型检索开销。例如使用 @Files 精准挂载数据结构定义，使用 @Codebase 进行全局语义检索，或使用 @Docs 直接调用第三方框架的最新官方规范。明确喂给模型高相关度的局部上下文，模型生成可用代码的概率会呈指数级提升。
Rules 与 MDC 机制：为项目构建不可撼动的确定性护栏
大语言模型在完成单次会话后并不会在全局保留记忆，每次对话都是独立的推演过程。Cursor 提供的 Rules 规则体系（早期使用 .cursorrules，目前演进为 .cursor/rules/*.mdc 文件架构），本质是直接插入在每次模型上下文起始位置的系统级约束，赋予 AI 跨会话的项目级统一标准。
合理的规则配置能强制模型遵循现有的架构选型，防止其随意引入未经审批的第三方库。在 .cursor/rules/ 目录下，开发者可以根据文件匹配模式（Glob）切分出多个轻量化的 .mdc 文件，避免单个规则文件体积膨胀挤占有效的上下文窗口。
---
description: React 前端组件编码规范
globs: src/components/**/*.{tsx,jsx}
alwaysApply: false
---
# 前端开发规范与约束
1. 基础架构：
- 必须使用 TypeScript 严格模式，禁止使用 any 类型。
- UI 样式统一采用 Tailwind CSS，禁止书写内联 style。
2. 状态与组件：
- 优先使用 React 19 Server Components，交互逻辑下沉至 client.tsx。
- 异步数据请求必须使用 TanStack Query 封装，禁止直接在 useEffect 中请求。
3. 绝对禁止事项：
- 禁止引入 lodash，请使用原生 ESNext 特性。
- 禁止在组件内部直接调用 localStorage，统一通过 @src/lib/storage.ts 抽象层访问。
通过这种细粒度的模式匹配，当开发者在修改前端组件时，Cursor 只会自动加载前端规则，而不会被后端微服务或数据库迁移的规范所干扰。规则文件应当保持在 100 行到 500 行之间，以清晰的代码片段示例替代抽象的概念解释。
阶段演进中的研发痛点与质量代价
开发者在拥抱 AI 辅助编程的过程中，通常会经历从盲目信任到规则化重构的几个阶段。各个阶段所面临的技术阻碍与历史包袱存在显著差异：
| 阶段 | 核心问题 | 留下的硬伤 |
|---|---|---|
| 初期：直觉提示词 | 依赖模糊的自然语言描述，缺失具体文件与数据模型上下文 | 生成大量未引用的冗余函数，产生类型不匹配与幽灵依赖 |
| 进阶：多文件大爆炸 | 在 Composer 中一次性塞入庞大需求，让 AI 自主扫描修改整个项目 | 跨模块调用产生循环引用，核心业务逻辑被静默删除或篡改 |
| 成熟：上下文与规则驱动 | 团队规则库维护滞后，旧规则与新架构之间产生语义冲突 | 提示词 Token 消耗略有上升，需要定期治理失效的过期配置 |
Composer 多文件协同：拆解任务与保持原子化改动的实战心法
Composer 模式（快捷键 Cmd/Ctrl + I）是 Cursor 进行多文件架构级修改的核心代理工具，能够根据自然语言指令同时在多个文件中生成差异比对（Diff）并支持一键应用。许多开发者在使用 Composer 时最常犯的错误，就是将一个包含 5 个子功能的宏大需求直接扔给模型，导致其在处理多文件逻辑分支时发生注意力衰减。
将复杂需求拆解为微型原子步骤，是保持多文件编辑可控的唯一手段。 开发者应当将一次完整的业务迭代切分为“定义类型层 → 实现业务层 → 更新暴露层 → 编写测试”的线性序列，每一步均在 Composer 中单独发起对话并审查变更。
[Step 1 提示词示例]
当前任务：为用户模块新增 API Key 管理能力。
上下文：参考 @src/types/user.ts
操作：仅在 @src/types/user.ts 中增加 APIKey 相关的类型定义与枚举，不要修改任何业务逻辑文件。
在 Composer 生成修改方案后，绝对不要直接点击“全部接受”（Accept All）。开发者必须逐个文件审阅 Git 样式的差异视图（Visual Diff），检查 AI 是否在不经意间删除了现存的边缘逻辑分支，或者生成了已经废弃的旧版本语法。
闭环验证：终端交互、精准报错注入与 Diff 审查体系
完全依靠肉眼检查 AI 生成的代码是不现实的，高效的 vibe coding 必须依赖自动化流水线建立“改动 → 验证 → 修正”的执行闭环。Cursor 内置了深度集成的终端环境，开发者可以直接在聊天窗口中唤起终端执行单元测试、类型检查和代码格式化工具。
当代码在本地运行失败时，简单的“这段代码跑不通，帮我重写”几乎无法让模型找到真正根因。将完整的错误堆栈、运行环境与触发测试用例一并注入提示词，是快速定位 Bug 的标准路径。
运行命令：pnpm test:unit src/services/auth.test.ts
控制台报错：
TypeError: Cannot read properties of undefined (reading 'verifyToken')
at AuthService.validateSession (src/services/auth.ts:42:18)
at Object.<anonymous> (src/services/auth.test.ts:15:23)
相关文件：@src/services/auth.ts @src/services/auth.test.ts
要求：修复 AuthService 中的空指针异常，确保在未注入 JWTClient 时抛出明确的 ConfigError。
当模型修复代码后，要求其再次通过终端运行对应的测试命令。只要测试套件全部变绿且 git diff 显示的改动完全符合预期范围，开发者即可放心地将代码推进至暂存区。
综合判断与认知澄清
从工程实践的角度来评判，vibe coding 绝非让非技术人员凭感觉构建企业级系统的魔法，而是将资深工程师的系统架构经验转化为高度结构化的上下文配置与提示词控制。 规则库（Rules）不是用来完全替代开发者思考的代码生成器，而是为 AI 划定技术边界的电子围栏。
社区中常有一种误读，认为只要给大模型足够大的上下文窗口（如百万级别的 Token），就可以直接把整个代码库一股脑塞入提示词，不再需要开发者进行精细的 @ 文件管理。事实恰恰相反，上下文窗口的扩大带来了更高的注意力稀释风险与幻觉率；越是庞大的项目，越需要开发者通过精准的模块切分与规则约束，强制模型将注意力集中在特定的执行路径上。
尚未解决的工程挑战
即便建立起完善的上下文工程与规则体系，目前的 Cursor 工作流依然面临一个长期的技术瓶颈：动态上下文膨胀与规则冲突检测的缺失。当项目的 .cursor/rules/ 累积到数十个文件，且各类依赖库在快速迭代时，不同规则之间可能产生隐性的语义互斥。
例如，某个通用规则要求全局使用严格的不变性模式，而另一个性能优化模块的局部规则要求使用原生可变数组进行批量计算。当前的 IDE 和底层推理模型尚无法在提示词编译阶段自动化检测此类矛盾，往往会导致模型在生成代码时发生逻辑摇摆或退化为折中妥协的低效写法。如何在工程层面建立规则集的静态类型检查与依赖拓扑分析，仍需等待下一代 AI 编程架构的突破。
引用来源
- Cursor 官方团队，《Rules for AI Documentation》，2025 年 3 月更新，https://cursor.com/docs/rules
- Anysphere 官方博客，《Cursor Composer: Multi-File Editing Architecture》，2024 年 8 月，https://www.cursor.com/
- Steve Kinney，《Context is King in Cursor: Developing with AI Tools》，2026 年 6 月，https://stevekinney.com/courses/ai-development/cursor-context
- Cloud Security Alliance，《Secure Vibe Coding: Level Up with Cursor Rules and the RAILGUARD Framework》，2025 年 5 月，https://cloudsecurityalliance.org/blog/2025/05/06/secure-vibe-coding-level-up-with-cursor-rules-and-the-r-a-i-l-g-u-a-r-d-framework
- Kirill Markin，《Cursor IDE Rules for AI: Guidelines for Specialized AI Assistant》，2025 年 4 月，https://kirill-markin.com/articles/cursor-ide-rules-for-ai/
