Guia Completo de Configuração do .cursorrules: Do Zero ao Avançado

O .cursorrules é um arquivo de texto simples que você coloca na raiz do projeto para dizer à IA do Cursor como se comportar -- qual estilo de código seguir, quais frameworks você está usando, quais padrões evitar. Pense nele como um prompt de sistema específico do projeto que é injetado em toda interação com a IA.

Se você passou algum tempo no Fórum do Cursor, já viu a mesma pergunta aparecer toda semana: "Como configuro o .cursorrules corretamente?" A documentação oficial cobre o básico, mas existe muita nuance que só se descobre usando no dia a dia. Este guia resume o que a comunidade descobriu até agora.

Três Tipos de Regras: Qual Você Precisa?

Esta é a principal fonte de confusão no fórum. O Cursor na verdade tem três mecanismos diferentes de regras, e cada um serve para um propósito diferente. Aqui está o resumo:

Rules for AI (Global)

Encontrado em Configurações > Geral > Rules for AI. São regras globais que se aplicam a todos os projetos que você abre no Cursor. Elas ficam nas suas configurações locais, não em nenhum diretório do projeto.

Bom para:

• Preferências pessoais ("sempre use TypeScript strict mode")
• Convenções universais que você segue em todos os projetos
• Ajustes de comportamento do modelo ("responda de forma concisa, sem explicações a menos que solicitado")

Rules for AI (Global)

Always use functional components with TypeScript.
Prefer named exports over default exports.
When fixing bugs, explain the root cause briefly before showing the fix.

.cursorrules (Nível de Projeto)

Um arquivo chamado .cursorrules colocado no diretório raiz do seu projeto. Esta é a abordagem clássica -- um único arquivo, texto simples ou markdown, que descreve como a IA deve trabalhar dentro deste projeto específico.

Bom para:

• Stack tecnológico e convenções específicas do projeto
• Regras compartilhadas com a equipe (faça commit no git)
• Padrões específicos de frameworks (Next.js, Django, Rails, etc.)

Regras .mdc (Modernas, com Escopo)

O formato mais recente. Você coloca arquivos .mdc dentro do diretório .cursor/rules/. Cada arquivo pode ter escopo para padrões de arquivo específicos, e você pode ativar/desativar regras individuais pela interface.

Bom para:

• Controle granular sobre quando as regras se aplicam
• Projetos grandes onde diferentes diretórios têm convenções diferentes
• Equipes que querem habilitar/desabilitar regras seletivamente

Estrutura de projeto com regras .mdc

.cursor/
  rules/
    react-components.mdc
    api-endpoints.mdc
    database.mdc
    testing.mdc

Tabela Comparativa

Recurso	Rules for AI	.cursorrules	Regras .mdc
Escopo	Global (todos os projetos)	Projeto único	Projeto único
Localização	Configurações do Cursor	Raiz do projeto	.cursor/rules/
Padrão de arquivo	N/A	N/A	Escopo por regra
Ativar/desativar na UI	Sim	Não	Sim
Compartilhar via git	Não	Sim	Sim
Múltiplos arquivos	Não	Não (arquivo único)	Sim
Status	Estável	Estável (legado)	Recomendado

dica

Você pode usar os três ao mesmo tempo. Rules for AI define sua linha de base pessoal, .cursorrules ou arquivos .mdc cuidam das especificidades do projeto. Quando há conflitos, as regras de nível de projeto têm precedência.

Escrevendo um Arquivo .cursorrules Eficaz

A maioria dos tutoriais diz para escrever seu .cursorrules em markdown. Isso funciona, mas o usuário do fórum razbakov fez um forte argumento a favor de usar JSON estruturado em vez disso. O raciocínio: LLMs analisam dados estruturados de forma mais confiável do que prosa, então suas regras são seguidas de forma mais consistente.

Aqui está um arquivo .cursorrules real para um projeto Next.js + TypeScript usando a abordagem JSON:

.cursorrules

{
  "project": {
    "name": "My SaaS App",
    "stack": ["Next.js 14", "TypeScript", "Tailwind CSS", "Prisma"],
    "packageManager": "pnpm"
  },
  "conventions": {
    "naming": {
      "components": "PascalCase",
      "functions": "camelCase",
      "files": "kebab-case",
      "constants": "SCREAMING_SNAKE_CASE"
    },
    "imports": {
      "order": ["react", "next", "lib/*", "components/*", "relative paths"],
      "noCircularImports": true,
      "alias": "@/ for src/"
    },
    "components": {
      "preferFunctional": true,
      "folderByFeature": true,
      "colocateStyles": true
    }
  },
  "rules": [
    "Always define TypeScript interfaces for component props",
    "Use 'use client' directive only when component needs interactivity or hooks",
    "Prefer server components by default in Next.js app router",
    "No default exports -- use named exports for everything",
    "API routes go in app/api/ following REST conventions",
    "Database queries use Prisma client from lib/db.ts only",
    "Error handling: use try/catch with proper error types, never swallow errors",
    "Environment variables must be validated with zod in env.ts"
  ],
  "antiPatterns": [
    "Never use 'any' type -- use 'unknown' and narrow with type guards",
    "Never put business logic in page.tsx files",
    "Never use inline styles -- use Tailwind classes or CSS modules",
    "Never import from relative paths like '../../' -- use @/ alias"
  ]
}

Por Que Isso Funciona Melhor Que Texto Simples

Quando você escreve regras como parágrafos em linguagem natural, a IA tem que interpretar o que você quer dizer. Com JSON estruturado:

• Cada regra é uma instrução discreta e inequívoca
• A IA não precisa adivinhar quais partes são regras versus contexto
• Você pode organizar por categoria, facilitando a manutenção
• Adicionar ou remover regras não quebra o formato

Nota: Se você prefere markdown, tudo bem também. O insight principal é estrutura sobre prosa. Mesmo em markdown, use bullet points e títulos claros em vez de parágrafos longos.

Uma Alternativa em Markdown

Se JSON parece muito rígido, aqui está uma versão bem estruturada em markdown que ainda evita o problema do "muro de texto":

.cursorrules (Versão Markdown)

# Regras do Projeto

## Stack Tecnológica
- Next.js 14 (App Router)
- TypeScript (strict mode)
- Tailwind CSS
- Prisma ORM

## Nomenclatura
- Componentes: PascalCase (UserProfile.tsx)
- Utilitários: camelCase (formatDate.ts)
- Constantes: SCREAMING_SNAKE_CASE (MAX_RETRY_COUNT)
- Arquivos: kebab-case (user-profile.tsx)

## Regras Rígidas
- Sempre use named exports
- Todo componente precisa de tipos de props TypeScript
- Componentes server por padrão, adicione 'use client' apenas quando necessário
- Não use o tipo `any`, nunca
- Todas as variáveis de ambiente validadas com zod

## Estrutura de Arquivos
- Componentes em src/components/[feature]/
- Hooks em src/hooks/
- Utilitários de API em src/lib/
- Tipos em src/types/

Deixe a IA Escrever Seu .cursorrules Para Você

Aqui está um truque do usuário do fórum tomredman que é genuinamente útil: em vez de escrever regras do zero, use o modo Agent do Cursor para analisar sua base de código e gerá-las automaticamente.

O Método

1. Abra o painel de chat do Cursor
2. Mude para o modo Agent
3. Dê este prompt:

Analyze this codebase and generate a comprehensive .cursorrules file.
Look at:
- Existing files and directory structure
- Package.json dependencies
- Config files (tsconfig, eslint, prettier, etc.)
- Existing code patterns and conventions

Output a .cursorrules file that captures the actual conventions
already used in this project. Use JSON format with clear categories
for tech stack, naming conventions, coding rules, and anti-patterns.

4. Revise a saída com cuidado -- a IA vai capturar padrões que você nem percebia que estava seguindo
5. Edite o arquivo gerado para remover qualquer coisa imprecisa e adicionar o que faltou
6. Salve na raiz do projeto como .cursorrules

info

Isso funciona melhor em projetos que já existem há um tempo com padrões consistentes. Para projetos novos, é melhor escrever as regras manualmente ou começar de um template.

Iterando Sobre Regras Geradas

Não espere um resultado perfeito na primeira tentativa. Aqui está meu fluxo de trabalho:

1. Gere com o modo Agent
2. Teste pedindo ao Cursor para escrever um novo componente -- ele segue as regras?
3. Anote onde ele desvia e adicione regras explícitas para esses casos
4. Repita por algumas iterações até que a saída esteja consistentemente correta

O processo todo leva cerca de 15-20 minutos e economiza horas de idas e vindas de "corrige isso, não, não assim" depois.

Recursos da Comunidade

Você não precisa começar do zero. A comunidade construiu várias bibliotecas de regras que valem a pena explorar:

cursor.directory

cursor.directory é uma coleção curada de arquivos .cursorrules organizados por framework e linguagem. É o recurso mais popular no fórum para encontrar regras iniciais.

cursorrules.agnt.one

cursorrules.agnt.one foca em regras específicas para agentes. Se você usa muito o modo Agent, vale a pena conferir.

Coleções no GitHub

Pesquise no GitHub por .cursorrules e você encontrará milhares de exemplos do mundo real:

Consulta de busca no GitHub

filename:.cursorrules stars:>5

Filtre por linguagem ou framework para encontrar regras de projetos similares ao seu.

Tópico do Fórum: Compartilhe Seu .cursorrules

Existe um tópico fixo no Fórum do Cursor chamado "Share your .cursorrules" onde os usuários postam suas configurações com explicações. É ouro para ver o que funciona em produção.

atenção

Nunca copie um arquivo .cursorrules verbatim para o seu projeto. Sempre adapte-o para sua stack e convenções reais. Um arquivo de regras de React Native vai causar mais mal do que bem em um projeto Django.

Armadilhas Comuns

Depois de ler dezenas de tópicos do fórum, estes são os problemas que aparecem com mais frequência:

1. Regras Muito Longas = Pior Desempenho

Existe um mito persistente de que mais regras = melhor comportamento da IA. É o oposto. O Cursor injeta suas regras na janela de contexto junto com seu código e a conversa. Regras mais longas significam menos espaço para o contexto real do código.

Mantenha abaixo de 2000 caracteres se possível. Se você está chegando em 5000+, precisa cortar sem dó.

Ruim: Muito verboso

When you are writing React components in this project, you should always make sure
to use functional components instead of class components, and you should define
your prop types using TypeScript interfaces rather than PropTypes, and you should...

Bom: Conciso e direto

- Use functional React components only
- TypeScript interfaces for all props
- Named exports, no defaults

2. Regras Conflitantes

Quando você tem Rules for AI definidas globalmente E um arquivo .cursorrules no projeto, conflitos são inevitáveis. Por exemplo:

• Regra global: "Use indentação de 2 espaços"
• Regra do projeto: "Use indentação de 4 espaços"

O Cursor resolve isso dando prioridade às regras de nível de projeto, mas a IA ainda pode ficar confusa quando ambas estão presentes. A solução: mantenha as regras globais mínimas e genéricas, coloque as específicas nos arquivos do projeto.

3. Regras Que Dizem à IA O Que Ela Já Sabe

Não desperdice seu orçamento de regras com coisas que o modelo já faz bem:

Regras desnecessárias para evitar

- Write clean, readable code          # O modelo já faz isso por padrão
- Follow best practices               # Muito vago para ser útil
- Use proper error handling          # Já é comportamento padrão
- Comment your code                  # Frequentemente ruído desnecessário

Em vez disso, foque no que torna seu projeto diferente dos padrões do modelo:

Regras que realmente agregam valor

- Use Zod schemas for all API input validation
- All database queries go through the repository pattern
- GraphQL resolvers must have @authenticated directive
- Use pnpm workspaces for monorepo package management

4. Esquecer de Fazer Commit do .cursorrules

Se você está em uma equipe e o arquivo .cursorrules não está no controle de versão, você é o único que se beneficia dele. Adicione ao git e faça parte do processo de onboarding.

Adicionar .cursorrules ao git

git add .cursorrules
git commit -m "Add project AI rules for Cursor"

Nota: Algumas equipes preferem manter o .cursorrules fora do git se desenvolvedores diferentes têm preferências diferentes. Nesse caso, use .cursorrules.example como template e adicione .cursorrules ao .gitignore.

5. Não Testar Suas Regras

Escreva suas regras e depois teste-as imediatamente. Peça ao Cursor para:

• Gerar um novo componente
• Refatorar uma função existente
• Corrigir um bug

Se a saída não corresponder às suas expectativas, suas regras precisam de ajustes. Não espere até estar no meio de uma feature para descobrir que suas regras não estão funcionando.

Checklist de Início Rápido

Se você está configurando o .cursorrules pela primeira vez, aqui está o caminho mínimo:

• Decida entre .cursorrules (arquivo único) ou .mdc (múltiplos arquivos)
• Use o modo Agent para analisar sua base de código e gerar um primeiro rascunho
• Corte para menos de 2000 caracteres
• Foque em regras específicas do projeto, não conselhos genéricos
• Teste pedindo ao Cursor para gerar um componente ou função
• Itere até que a saída seja consistente
• Faça commit no controle de versão
• Compartilhe com sua equipe

Artigos Relacionados

• Best Practices for .cursor/rules
• MDC Rules Best Practices
• Using Cursor Rules Effectively
• How to Ignore Sensitive Files in Cursor