核心导读与中文摘要
聚焦全仓库上下文索引、多文件协同重构与 .cursorrules 工程规范编写,帮助开发者建立可复用的 AI 编程工作流。
为什么要在团队中使用 Project Rules
在大型 TypeScript / Next.js 仓库中,仅仅在聊天框里重复提示“请用 Tailwind、请写中文注释”不仅低效,还容易在长对话中被遗忘。通过 .cursor/rules/*.mdc 规则文件,可以将工程约束、目录约定、组件规范自动注入到每一次 Agent 上下文中。
💡 个人经验:建议将规则拆分为“全局基础规范(
alwaysApply: true)”与“按目录匹配规范(globs: src/app/**)”,避免无关规则占用过多 Token。
快速上手配置清单
- 在项目根目录创建
.cursor/rules/目录 - 为 Next.js App Router 与数据库操作拆分独立
.mdc文件 - 配置团队共享的 Code Review Checklist 提示词模板
- 将规则文件纳入 Git 版本管理,随 PR 一起迭代
推荐规则模板(可直接复制使用)
将以下内容保存为 .cursor/rules/nextjs-conventions.mdc:
markdown
---
description: Next.js 16 App Router 与 TypeScript 开发规范
globs: src/**/*.{ts,tsx}
alwaysApply: false
---
# 核心约束
1. 优先使用 Server Components 获取数据,仅在需要交互状态时标记 'use client'。
2. 所有外部数据查询必须包含超时控制与降级兜底逻辑,禁止页面直接抛出未捕获白屏。
3. UI 组件优先复用 src/components/ui 下的 shadcn/ui 基础组件。
常见规则作用域对比
| 规则文件位置 | 生效范围 | 适用场景 | 推荐权重 |
|---|---|---|---|
.cursor/rules/base.mdc | 全局始终生效 | 代码风格、命名规范、安全红线 | ⭐⭐⭐⭐⭐ |
.cursor/rules/api.mdc | 仅匹配后端路由 | Supabase 鉴权、参数校验、错误码格式 | ⭐⭐⭐⭐ |
.cursor/rules/ui.mdc | 仅匹配前端组件 | Tailwind 间距规范、响应式断点、无障碍 | ⭐⭐⭐⭐ |
实用命令速查
验证当前仓库配置与类型完整性:
bash
npx tsc --noEmit && npm run lint && npm run build
更多官方文档细节可参考 Cursor Rules 官方文档 进行扩展配置。
