必须将 .cursorrules 文件置于项目根目录，用纯文本/markdown 编写，支持 ignore、restrict、suggest、protected 四类指令，路径匹配需用正斜杠和通配符，大小写敏感且顺序影响生效逻辑。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
你想让 Cursor 的 AI 助手在生成代码、补全、改写时严格按你的项目习惯来，但每次手动提醒太累，又怕规则写错导致 AI 完全不认——这时候必须搞懂 .cursorrules 文件到底怎么写才有效，不是随便堆文字就能起作用。
先确认文件位置和基础格式
把文件命名为 .cursorrules，直接放在项目根目录下（和 package.json、.gitignore 同级），不能放在子文件夹里，也不能叫 .cursorrules.md 或 cursorrules.txt。
文件内容用纯文本或 Markdown 都可以，Cursor 不解析 JSON/YAML，只当普通文本读取；所以别写成 JSON 格式，写了也白写。
每一行规则必须顶格写，缩进会被忽略；以 # 开头的行是注释，AI 不会读取，但你写来备注用途很实用。
核心规则类型与写法
目前 Cursor 支持四类明确识别的指令前缀：ignore、restrict、suggest、protected。必须严格拼写，大小写敏感，冒号后要留一个空格。
ignore: 用于屏蔽 AI 读取或修改某些路径，比如测试文件、构建产物、密钥配置；它能防止 AI 错误引用或篡改不该碰的内容。
restrict: 用来约束 AI 的输出行为，比如强制加 TypeScript 类型、禁止使用 eval、要求所有 API 调用带错误处理；这类规则直接影响生成代码的合规性。
suggest: 控制自动补全偏好，例如“优先用 const 声明变量”“React 组件默认用函数式写法”；它不强制，但会显著提升补全建议的命中率。
protected: 指定绝对不可修改的文件路径，比如 src/auth/tokenManager.ts 或 database/migrations/001_init.sql；【一旦被标记为 protected，AI 在 Ctrl+K 或 Chat 中主动改写该文件时会直接拒绝操作】。
路径匹配写法与坑点
路径支持通配符 * 和 **：
* 匹配当前层级任意字符，例如 ignore: *.log 忽略所有同级 .log 文件。
** 匹配多级任意目录，例如 ignore: **/tests/** 忽略所有 tests 目录及其子目录下的全部内容。
注意：路径必须用正斜杠 /，Windows 用户别用反斜杠 \；否则规则失效，AI 仍会读取被屏蔽的文件。
路径区分大小写，src/App.tsx 和 src/app.tsx 是两个不同路径；若项目混合大小写，建议统一用小写路径规则，或分别写两条。
多个 ignore 规则按从上到下顺序生效，后面规则不会覆盖前面——想精确控制，就把更具体的路径写在前面，宽泛的放后面，比如先 ignore: src/legacy/utils.js，再 ignore: src/legacy/**。
实战配置示例
方法一：极简启动版（适合新手快速上手）
# 项目使用 Vue 3 + TypeScript
ignore: node_modules/
ignore: dist/
restrict: "所有函数必须有明确的返回类型声明"
suggest: "组件中优先使用 defineComponent 封装"
方法二：团队生产级（含保护与上下文注入）
# 全局规范
restrict: "使用单引号，结尾不加逗号，缩进为 2 空格"
# 敏感路径保护
protected: src/core/config.ts
protected: **/secrets.env
# 业务上下文提示
我们内部封装了 @/composables/useApi，所有数据请求必须调用此函数，禁止直接使用 fetch 或 axios 实例。
路由定义统一在 src/router/index.ts，新增页面必须在此注册。
方法三：框架专用模板（直接复用）
访问 https://cursor.directory 或 GitHub 仓库 awesome-cursorrules/rules，找到对应技术栈（如 Next.js、FastAPI、Vue 3），复制其 .cursorrules 内容，粘贴到你项目根目录新建的 .cursorrules 文件中即可；这些模板已通过大量项目验证，省去试错成本。
