Alternar tema

Cursor Rules: como fazer a IA gerar código dentro dos padrões do projeto

Easton editorial illustration: step-by-step assembly path

O Cursor tinha acabado de gerar mais um trecho de código. Fiquei olhando para a tela, com o dedo suspenso sobre a tecla Enter — era a terceira vez.

Na primeira, ele declarou variáveis com var. Na segunda, trocou tudo por componentes de classe. Desta vez, simplesmente removeu os tipos TypeScript e espalhou vários any. Apaguei o código e me preparei para escrever tudo à mão.

Foi quando percebi: a IA não era pouco inteligente; eu é que nunca tinha explicado quais eram as minhas regras.

Quando comecei a usar o Cursor, achei que a IA deveria “saber sozinha” o que era um bom código. Só entendi o problema quando alguém da equipe reclamou: “Por que o componente que você pediu ao Cursor não tem nada a ver com o nosso estilo?” A IA precisa de padrões explícitos.

É esse problema que este artigo resolve. Em cerca de cinco minutos, você configura o Cursor Rules para que o código gerado pela IA siga os padrões do projeto, sem trocar a stack nem desrespeitar o estilo de código.

O que é Cursor Rules e por que usar?

A essência do Cursor Rules: definir regras para a IA

Em termos simples, Cursor Rules são arquivos de configuração que informam à IA quais são os seus padrões de código.

É como o manual de desenvolvimento que uma empresa entrega a quem acabou de entrar: quais tecnologias usamos, como nomeamos o código e como organizamos os arquivos. O Cursor Rules faz exatamente isso — entrega à IA um “manual de integração”.

O funcionamento é direto: quando você conversa com o Cursor, o conteúdo dos arquivos de regras é anexado automaticamente ao prompt. Depois de ler as regras, a IA entende que, por exemplo, aquele projeto usa React Hooks e não permite componentes de classe. A partir daí, gera código de acordo com o padrão.

O que acontece sem Rules? Uma experiência nada agradável

No meu primeiro projeto com Cursor, achei que tinha encontrado ouro: a IA escrevia código muito rápido. Três dias depois, os problemas ficaram evidentes.

O estilo do código virou uma bagunça. Alguns arquivos usavam camelCase, outros PascalCase, e havia até arquivos com snake_case. Nem eu lembrava mais qual padrão valia onde.

A stack saía errada. Eu queria componentes funcionais, mas o Cursor gerava vários class Component extends React.Component. Eu dizia “use Hooks” e, no arquivo seguinte, ele voltava ao formato antigo.

As regras do projeto eram ignoradas. A equipe exigia comentários em todas as funções, mas o código gerado pelo Cursor não tinha uma linha de comentário. O mesmo acontecia com o tratamento de erros: embora o padrão exigisse try-catch, a IA chamava a API sem proteção alguma.

Depois disso, passei dois dias refatorando o código. Minhas mãos chegaram a doer.

E depois de configurar Rules? A diferença é clara

Mais tarde, levei cinco minutos para criar um arquivo .cursorrules com estes pontos:

  • A stack era React 18 + TypeScript
  • Somente componentes funcionais e Hooks
  • Nomes sempre em camelCase
  • Tipos obrigatórios e proibição de any

E o resultado?

A partir daquele dia, todos os componentes gerados pelo Cursor passaram a seguir o padrão. A consistência do código melhorou pelo menos 80%, e o tempo gasto em code review caiu pela metade. O restante da equipe começou a perguntar como eu tinha feito o Cursor obedecer tão bem.

Valeu a pena.

Os números ajudam a dimensionar o interesse: segundo as práticas compartilhadas pela comunidade, uma boa configuração de Rules pode melhorar bastante a consistência e reduzir a refatoração posterior. O repositório awesome-cursorrules já passou de 2.000 estrelas no GitHub, um sinal de que essa necessidade é comum entre desenvolvedores.

Como configurar o Cursor Rules em 2026

Primeiro, o essencial: o que mudou entre o formato antigo e o novo

Ao procurar tutoriais de Cursor Rules, você provavelmente encontrará duas instruções: algumas pessoas usam o arquivo .cursorrules, enquanto outras usam o diretório .cursor/rules. As duas estão certas, mas pertencem a momentos diferentes.

Formato antigo (antes de 2025):

Crie um arquivo .cursorrules na raiz do projeto e coloque todas as regras nele. Simples e direto.

Formato novo (recomendado em 2026):

Crie o diretório .cursor/rules na raiz do projeto e coloque vários arquivos .mdc dentro dele. Cada arquivo pode cuidar de uma categoria de regras.

A recomendação oficial já é migrar para o formato novo, pois ele é mais flexível: você pode separar as regras por função e configurar escopos diferentes. O formato antigo ainda funciona, mas será descontinuado em alguma versão futura.

Minha sugestão: em projetos novos, adote o formato novo desde o início. Em projetos antigos, migre quando houver tempo, sem urgência.

Dois níveis de regras: global e projeto

O Cursor oferece dois níveis de regras. Entender a diferença entre eles é importante.

User Rules (regras globais)

São suas preferências pessoais de programação e valem para todos os projetos.

Caminho: File → Preferences → Cursor Settings → Rules → User Rules

Quando usar: para padrões que atravessam projetos. Por exemplo:

  • “Uso TypeScript em todos os projetos”
  • “Não uso var; prefiro const ou let
  • “Todas as operações assíncronas usam async/await, não .then()

Pense nelas como suas preferências pessoais de limpeza do código.

Project Rules (regras do projeto)

São padrões específicos de um projeto e só se aplicam a ele.

Como configurar:

  1. Crie a pasta .cursor na raiz do projeto
  2. Crie a pasta rules dentro de .cursor
  3. Crie arquivos .mdc dentro de rules, como frontend.mdc ou typescript-rules.mdc

Quando usar: para a stack e os padrões específicos do projeto. Por exemplo:

  • “Este é um projeto Next.js 14 + TypeScript + Tailwind CSS”
  • “As APIs seguem o padrão RESTful”
  • “Os componentes ficam em components/ e usam nomes em PascalCase

A prioridade é simples: regras do projeto > regras globais. Em caso de conflito, o projeto prevalece.

Escopo das regras: evite aplicar tudo em qualquer situação

Este é um recurso importante das versões de 2026: você pode controlar quando cada regra entra em ação.

Em um arquivo .mdc, é possível configurar estes escopos:

Always (sempre): a regra vale independentemente da tarefa. É útil para padrões centrais, como “não usar var”. Use com cautela: muitas regras Always ocupam espaço demais no contexto da IA.

Auto Attached (anexada automaticamente): a regra é ativada conforme o tipo de arquivo. Você pode aplicar regras de React a arquivos .tsx e regras de Python a arquivos .py. É o formato que mais recomendo.

Agent Requested (solicitada pelo agente): a IA decide, com base na conversa, se aquela regra é necessária. Funciona bem para regras auxiliares opcionais.

Manual: a regra só entra em ação quando você pede explicitamente que o Cursor a use. É adequada para situações especiais, como regras de desempenho ou de testes.

Na minha prática, 80% ficam em Auto Attached, 10% em Always e os 10% restantes dependem do caso.

Recurso de janeiro de 2026: o comando /rules

Em 8 de janeiro de 2026, o Cursor publicou uma atualização da CLI com um comando bastante útil: /rules.

Agora é possível digitar /rules diretamente no terminal do Cursor para criar e editar arquivos de regras, sem procurar pastas manualmente. Para quem ajusta regras com frequência, isso economiza tempo.

Consulte os detalhes no anúncio da atualização no fórum oficial do Cursor.

Como escrever Cursor Rules eficazes?

Esta é a parte mais importante. A qualidade das regras determina se o Cursor conseguirá segui-las.

Três categorias para organizar as regras

Ao configurar regras, recomendo trabalhar em três níveis.

A. Tecnologia e arquitetura

Primeiro, explique à IA que tipo de projeto é aquele.

Stack do projeto:
- Frontend: React 18 + TypeScript 5.3
- Gerenciamento de estado: Zustand
- Estilos: Tailwind CSS 3.4
- Ferramenta de build: Vite 5.0
- Versão do Node.js: 18+

Também deixe claros os padrões de arquitetura:

Padrões de arquitetura:
- Separação entre frontend e backend
- APIs no estilo RESTful
- Estrutura de pastas:
  - components/ armazena componentes reutilizáveis
  - pages/ armazena componentes de página
  - utils/ armazena funções utilitárias
  - hooks/ armazena Hooks personalizados

Por que tantos detalhes?

Aprendi isso da forma difícil. No começo, escrevi apenas “use React”. O Cursor alternava entre padrões do React 16 e do React 18. Quando informei a versão, o problema desapareceu.

B. Padrões de código

Esta parte mantém o estilo consistente.

Padrões de código:

Nomenclatura:
- Componentes: PascalCase (exemplo: UserProfile)
- Arquivos: kebab-case (exemplo: user-profile.tsx)
- Variáveis e funções: camelCase (exemplo: getUserData)
- Constantes: UPPER_SNAKE_CASE (exemplo: MAX_RETRY_COUNT)

Estilo de código:
- Use apenas componentes funcionais; não use componentes de classe
- Prefira const, depois let; não use var
- Use arrow functions; não use a palavra-chave function, exceto quando this for necessário
- Todos os componentes devem ter tipos TypeScript

Tamanho dos arquivos:
- Cada arquivo deve ter no máximo 300 linhas
- Cada função deve ter no máximo 50 linhas

Comentários:
- Funções importantes devem ter comentários JSDoc
- Lógicas complexas devem ter comentários em linha
- Os comentários devem explicar "por quê", não "o quê"

C. Qualidade e testes

Tratamento de erros:
- Todas as operações assíncronas devem usar try-catch
- Falhas de API devem mostrar mensagens claras para o usuário
- Não ignore erros; registre pelo menos com console.error

Desempenho:
- Renderizações de listas devem ter key
- Listas grandes devem usar rolagem virtual
- Imagens devem informar largura e altura para evitar mudanças de layout

Testes:
- Funções utilitárias devem ter testes unitários
- Lógicas centrais de negócio devem ter cobertura de testes

Princípios fundamentais para escrever regras

Princípio 1: seja específico, executável e verificável

Este é o princípio mais importante.

Exemplo ruim: “escreva um bom código”, “siga as boas práticas”, “preste atenção ao desempenho”

Essas regras não orientam nada. Ao ler “boas práticas”, como a IA saberia a qual prática você se refere?

Exemplos corretos:

  • “Use componentes funcionais, não componentes de classe”
  • “Defina Props com interface, não com type”
  • “Operações assíncronas devem usar async/await, não .then()”

A diferença é clara: uma boa regra é uma instrução que pode ser executada diretamente, não uma sugestão vaga.

Princípio 2: mantenha cada arquivo abaixo de 500 linhas

Essa é uma prática comum na comunidade. Regras muito longas ficam mais difíceis para a IA interpretar e consomem espaço demais no contexto.

Se o arquivo ultrapassar 500 linhas, é hora de dividi-lo:

  • frontend.mdc — regras de frontend
  • backend.mdc — regras de backend
  • typescript.mdc — regras de TypeScript
  • testing.mdc — regras de testes

Princípio 3: mostre exemplos de código, não apenas instruções

A IA entende muito melhor quando vê exemplos.

Apenas a instrução:

Os componentes devem ser funcionais e ter tipos definidos

Com exemplo:

Exemplo de componente:

interface UserCardProps {
  name: string;
  email: string;
}

export const UserCard = ({ name, email }: UserCardProps) => {
  return (
    <div className="user-card">
      <h3>{name}</h3>
      <p>{email}</p>
    </div>
  );
};

Com o exemplo, o Cursor entende exatamente qual formato você espera. Essa abordagem costuma funcionar muito bem.

Princípio 4: coloque as regras mais importantes no início

A IA tende a prestar mais atenção ao conteúdo inicial. Portanto, use esta ordem:

Primeira prioridade: stack e versões

Segunda prioridade: estilo de código

Terceira prioridade: organização dos arquivos

Por último: sugestões opcionais de otimização

Erros comuns que você deve evitar

Erro 1: regras amplas demais

“Siga as boas práticas de React” — quais boas práticas? As de 2016 ou as de 2024?

Prefira: “use React Hooks; use useState e useEffect por padrão e useReducer para estados complexos”.

Erro 2: regras contraditórias

Exigir TypeScript e, ao mesmo tempo, permitir o tipo any é uma contradição.

Quando a IA encontra regras conflitantes, pode ficar sem saber qual seguir e acabar ignorando as duas.

Erro 3: esquecer de informar versões

Os componentes de classe do React 16 diferem bastante dos Hooks do React 18. Se você disser apenas “use React”, a IA pode escolher qualquer estilo.

Informe as versões: React 18.2+, TypeScript 5.3+, Node.js 18+.

Erro 4: escrever as regras como um artigo acadêmico

Algumas pessoas transformam regras em textos longos, explicando teorias e justificativas.

Não faça isso. Você não precisa convencer a IA; precisa dizer o que ela deve fazer.

❌ “Escolhemos TypeScript porque ele oferece verificação estática de tipos, permite encontrar erros durante a compilação e melhora a qualidade do código…” (e ainda há mais 300 palavras)

✅ “Use TypeScript e não use o tipo any”

Curto e objetivo.

Exemplo prático: regras para um projeto React + TypeScript

Depois da teoria, vale olhar um exemplo real.

Imagine um projeto React + TypeScript com esta stack:

  • React 18
  • TypeScript 5.x
  • Tailwind CSS 3.x
  • Vite 5.x

Os padrões da equipe exigem:

  • Somente componentes funcionais
  • Tipagem estrita, sem any
  • Padrões consistentes de arquivos e nomes
  • Tratamento de erros obrigatório

Vamos configurar o arquivo de regras passo a passo.

Etapa 1: criar o arquivo de regras

Na raiz do projeto:

mkdir -p .cursor/rules
cd .cursor/rules
touch react-typescript.mdc

Etapa 2: definir a stack

Abra react-typescript.mdc e comece pela stack:

# Regras do projeto React + TypeScript

## Stack

- React 18.2+
- TypeScript 5.3+
- Tailwind CSS 3.4+
- Vite 5.0+
- Node.js 18+

## Gerenciamento de dependências

- Gerenciador de pacotes: pnpm
- Não use npm nem yarn

Etapa 3: definir o estilo de código

Em seguida, explique como o código deve ser escrito:

## Padrões de código

### Padrões dos componentes

- Use apenas componentes funcionais; não use componentes de classe
- Use PascalCase nos nomes de componentes
- Use kebab-case nos nomes de arquivos
- Use exports nomeados, não export default

Exemplo:

// ❌ Incorreto
export default function userProfile() { }

// ✅ Correto
export const UserProfile = () => { }

### Padrões de TypeScript

- Todos os componentes devem ter tipos definidos
- Defina Props com interface, não com type
- Não use any; use unknown ou um tipo específico
- Declare explicitamente o tipo de retorno das funções

Exemplo:

// ✅ Definição correta do componente
interface UserCardProps {
  name: string;
  email: string;
  age?: number;
}

export const UserCard = ({ name, email, age }: UserCardProps): JSX.Element => {
  return (
    <div className="p-4 border rounded">
      <h3 className="text-lg font-bold">{name}</h3>
      <p className="text-gray-600">{email}</p>
      {age && <p>Age: {age}</p>}
    </div>
  );
};

### Nomenclatura

- Variáveis e funções: camelCase
- Componentes: PascalCase
- Constantes: UPPER_SNAKE_CASE
- Arquivos: kebab-case
- Classes CSS: classes utilitárias do Tailwind; não escreva CSS personalizado

### Operações assíncronas

- Use async/await em todas as operações assíncronas
- Não use cadeias de .then()
- Use try-catch para tratar erros

Exemplo:

// ✅ Correto
const fetchUserData = async (userId: string): Promise<User> => {
  try {
    const response = await fetch(`/api/users/${userId}`);
    if (!response.ok) throw new Error('Failed to fetch user');
    return await response.json();
  } catch (error) {
    console.error('Error fetching user:', error);
    throw error;
  }
};

Etapa 4: definir a organização dos arquivos

## Organização dos arquivos

### Estrutura de diretórios

src/
├── components/     # Componentes reutilizáveis
├── pages/          # Componentes de página
├── hooks/          # Hooks personalizados
├── utils/          # Funções utilitárias
├── types/          # Tipos TypeScript
├── services/       # Chamadas de API
└── constants/      # Constantes

### Nomes de arquivos

- Arquivo de componente: user-card.tsx
- Arquivo utilitário: format-date.ts
- Arquivo de tipos: user.types.ts
- Arquivo de Hook: use-user-data.ts

### Ordem dos imports

1. React
2. Bibliotecas de terceiros
3. Componentes internos do projeto
4. Funções utilitárias
5. Tipos
6. Estilos

Etapa 5: definir os requisitos de qualidade

## Requisitos de qualidade

### Tratamento de erros

- Chamadas de API devem usar try-catch
- As mensagens de erro devem ser claras para o usuário
- Registre os erros em log

### Desempenho

- Renderizações de listas devem ter o atributo key
- Evite criar objetos ou funções dentro da função de renderização
- Use React.memo para evitar renderizações desnecessárias
- Imagens devem informar width e height

### Qualidade do código

- Cada arquivo deve ter no máximo 300 linhas
- Cada função deve ter no máximo 50 linhas
- Lógicas complexas devem ter comentários
- Funções importantes devem ter comentários JSDoc

Etapa 6: reunir o arquivo completo

Depois de combinar o conteúdo acima, o arquivo .cursor/rules/react-typescript.mdc estará pronto.

Adapte-o às necessidades do seu projeto. Por exemplo:

  • Se você usa Redux, inclua os padrões do Redux
  • Se usa React Query, inclua os padrões de obtenção de dados
  • Se há regras específicas de negócio, acrescente-as

Testar o resultado

Depois da configuração, peça ao Cursor que gere um componente de cartão de usuário:

Seu prompt: “Crie um componente de cartão de usuário que mostre nome, e-mail e avatar”

Antes de configurar as regras, o Cursor poderia gerar:

export default function UserCard(props) {
  return <div>...</div>
}

Depois de configurar as regras, ele tende a gerar:

interface UserCardProps {
  name: string;
  email: string;
  avatarUrl: string;
}

export const UserCard = ({ name, email, avatarUrl }: UserCardProps): JSX.Element => {
  return (
    <div className="p-4 border rounded shadow">
      <img src={avatarUrl} alt={name} className="w-16 h-16 rounded-full" width="64" height="64" />
      <h3 className="text-lg font-bold mt-2">{name}</h3>
      <p className="text-gray-600">{email}</p>
    </div>
  );
};

O resultado segue o padrão:

  • ✅ Componente funcional
  • ✅ Tipos TypeScript
  • ✅ Export nomeado
  • ✅ Estilos Tailwind
  • ✅ Imagem com largura e altura

Tudo certo na primeira tentativa, sem retrabalho.

Técnicas avançadas e problemas comuns

Prioridade das regras: qual prevalece?

Ao configurar regras em vários níveis, você pode encontrar conflitos. A prioridade do Cursor funciona assim:

Regras do projeto > regras globais

Se uma regra global pede aspas simples, mas o projeto exige aspas duplas, a regra do projeto prevalece.

Regras do subdiretório > regras do diretório pai

Imagine esta estrutura:

project/
├── .cursor/rules/general.mdc
└── frontend/
    └── .cursor/rules/react.mdc

Ao trabalhar dentro de frontend/, o arquivo react.mdc tem prioridade.

Chamada manual > ativação automática

Se você mencionar explicitamente uma regra na conversa, ela receberá prioridade, mesmo que seu escopo esteja definido como Manual.

Como dividir vários arquivos de regras

Quando o projeto fica mais complexo, um único arquivo de regras pode não ser suficiente. Esta é a divisão que uso:

.cursor/rules/
├── core.mdc              # Stack principal (Always)
├── frontend.mdc          # Regras de frontend (Auto Attached: *.tsx, *.ts)
├── backend.mdc           # Regras de backend (Auto Attached: *.py, *.go)
├── testing.mdc           # Regras de testes (Auto Attached: *.test.*)
└── performance.mdc       # Otimizações de desempenho (Manual)

Cada arquivo cuida de uma área, o que torna a organização mais clara.

Como depurar regras que não entram em ação

Problema 1: você não sabe se a regra foi ativada

Abra o Composer ou o Chat do Cursor e pergunte: “Quais regras você está vendo?”

O Cursor informará quais arquivos de regras estão carregados. Se a sua regra não aparecer, pode haver um destes problemas:

  • O caminho está incorreto
  • O escopo está incorreto
  • O formato do arquivo tem algum problema

Problema 2: regras em conflito

Quando duas regras se contradizem, o Cursor pode simplesmente deixar de seguir ambas.

Para resolver:

  1. Verifique os arquivos e encontre o conflito
  2. Defina a prioridade e remova a regra de menor prioridade
  3. Ou informe explicitamente na regra de maior prioridade que ela substitui as demais

Problema 3: a IA não segue a regra

Às vezes, a regra está escrita, mas o Cursor continua fazendo o que quer.

As causas podem ser:

  1. Regra vaga: transforme-a em uma instrução específica
  2. Regra longa demais: a IA pode ignorar o final; coloque o mais importante no início
  3. Conflito com o prompt: se você pedir um componente de classe na conversa, mas a regra exigir um componente funcional, a IA dará prioridade ao pedido da conversa

Soluções:

  • Reescreva a regra e inclua exemplos de código
  • Diga explicitamente na conversa: “siga as regras do projeto”
  • Troque o escopo de Auto Attached para Always

Onde encontrar regras prontas

Você não precisa escrever tudo do zero. A comunidade oferece vários recursos.

awesome-cursorrules

É o repositório de Cursor Rules mais popular no GitHub, com mais de 2.000 estrelas. Ele cobre:

  • Frameworks de frontend, como React, Vue e Angular
  • Linguagens de backend, como Python, Go e Java
  • Frameworks full stack, como Next.js, Astro e Nuxt
  • Regras específicas para TypeScript, testes, Docker e outros temas

Copie o arquivo de regras que precisar e ajuste-o ao projeto.

awesome-cursorrules-zh

É uma biblioteca adaptada para desenvolvedores chineses. Um ponto útil são os exemplos de regras combinadas, como React e FastAPI em um projeto full stack.

cursor.directory

Biblioteca on-line com visualização e cópia de regras. Cobre mais de 30 frameworks populares.

dotcursorrules.com

Outro site de recursos, com casos práticos e boas práticas.

Minha sugestão: comece com regras da comunidade, use-as por algum tempo e adapte-as ao projeto. Escrever tudo do zero logo no início costuma desperdiçar tempo.

Colaboração em equipe: transforme as regras em um ativo compartilhado

Em projetos de equipe, vale incluir as regras no controle de versão.

1. Envie as regras para o Git

Adicione o diretório .cursor/rules ao repositório:

git add .cursor/rules
git commit -m "Add Cursor rules for project standards"

Depois de baixar o código, o Cursor carregará as regras do projeto automaticamente para cada pessoa da equipe, mantendo o comportamento da IA consistente.

2. Apresente as regras a novos integrantes

Inclua no README algo parecido com isto:

## Desenvolvimento com Cursor

Este projeto tem Cursor Rules configurado no diretório `.cursor/rules`.

Ao usar o Cursor, a IA seguirá automaticamente estes padrões:
- React 18 + TypeScript
- Componentes funcionais + Hooks
- Estilos com Tailwind CSS
- Tipagem estrita

Converse com a equipe antes de alterar as regras.

3. Faça revisões periódicas

A stack muda, e os padrões também. Recomendo revisar os arquivos de regras a cada trimestre:

  • Alguma regra ficou obsoleta?
  • Há novas boas práticas que deveriam ser incluídas?
  • Quais regras precisam de ajustes segundo o feedback da equipe?

Trate as regras como documentação viva, não como uma configuração descartável.

Conclusão

Depois de todos esses detalhes, a ideia central cabe em uma frase: a IA só consegue trabalhar bem quando você deixa as regras claras.

Lembre do início da sua experiência com o Cursor. Você talvez tenha passado por situações como estas:

  • Pediu um componente e recebeu um código com estilo inconsistente
  • Queria TypeScript, mas a IA inseriu any sem avisar
  • O código parecia artificial e não combinava com o restante do projeto

O problema não é necessariamente o Cursor. Muitas vezes, nós é que não explicamos quais regras deveriam valer.

Agora você já sabe o que fazer:

  1. Crie os arquivos de regras — use .cursor/rules em projetos novos; projetos antigos podem continuar temporariamente com .cursorrules
  2. Descreva a stack com precisão — informe versões, frameworks e ferramentas
  3. Defina os padrões de código — nomenclatura, estilo e tratamento de erros, sempre com exemplos
  4. Controle o tamanho das regras — mantenha cada arquivo abaixo de 500 linhas e divida-o quando necessário
  5. Aprimore continuamente — as regras devem acompanhar a evolução do projeto

Comece agora:

  • Se você ainda não configurou regras, leve cinco minutos para criar o primeiro arquivo
  • Se as regras já existem, confira se estão vagas demais e acrescente exemplos
  • Se o projeto é de equipe, envie as regras para o Git para que todos trabalhem com o mesmo padrão

Depois de um mês, você pode perceber que:

  • O tempo de code review caiu pela metade
  • O estilo do código ficou consistente
  • Novos integrantes passaram a contribuir mais rápido
  • A IA realmente virou uma assistente útil no desenvolvimento

Para terminar, estes recursos evitam que você precise começar do zero:

Processo completo para configurar o Cursor Rules

Passo a passo para configurar o Cursor Rules do zero

⏱️ Estimated time: 30 min

  1. 1

    Step 1: Criar a estrutura dos arquivos de regras

    Método novo (recomendado em 2026):
    • Crie o diretório .cursor/rules na raiz do projeto
    • Crie arquivos .mdc dentro de rules, como react-typescript.mdc
    • Método antigo: crie um arquivo .cursorrules diretamente na raiz; ele será descontinuado

    Exemplo de comandos:
    mkdir -p .cursor/rules
    cd .cursor/rules
    touch react-typescript.mdc

    Escolha do nível das regras:
    • User Rules: regras globais, configuradas em Cursor Settings → Rules → User Rules
    • Project Rules: regras do projeto, configuradas no diretório .cursor/rules
    • Prioridade: regras do projeto > regras globais
  2. 2

    Step 2: Definir a stack e os padrões de arquitetura

    Informe a stack com as versões:
    • Frontend: React 18.2+ e TypeScript 5.3+
    • Estilos: Tailwind CSS 3.4+
    • Build: Vite 5.0+
    • Ambiente de execução: Node.js 18+

    Defina os padrões de arquitetura:
    • Estilo da API (RESTful/GraphQL)
    • Estrutura de pastas (components/, pages/, utils/)
    • Estratégia de separação entre frontend e backend

    Exemplo:
    # Regras do projeto React + TypeScript
    ## Stack
    - React 18.2+
    - TypeScript 5.3+
    - Tailwind CSS 3.4+
  3. 3

    Step 3: Definir padrões de código e requisitos de qualidade

    Três categorias de padrões de código:

    A. Nomenclatura
    • Componentes: PascalCase (UserProfile)
    • Arquivos: kebab-case (user-profile.tsx)
    • Variáveis/funções: camelCase (getUserData)
    • Constantes: UPPER_SNAKE_CASE (MAX_RETRY_COUNT)

    B. Estilo de código
    • Use apenas componentes funcionais; não use componentes de classe
    • Prefira const, depois let; não use var
    • Operações assíncronas devem usar async/await; não use .then()
    • Exija tipos TypeScript; não use any

    C. Qualidade
    • Operações assíncronas devem usar try-catch
    • Renderizações de listas devem ter key
    • Imagens devem informar largura e altura
    • Cada arquivo deve ter no máximo 300 linhas e cada função, 50

    Ponto principal: forneça exemplos de código, não apenas instruções abstratas
  4. 4

    Step 4: Configurar o escopo de aplicação das regras

    Quatro escopos de aplicação (recurso novo de 2026):

    • Always: aplica sempre; use com cautela, pois ocupa contexto
    Indicado para regras centrais, como "não usar var"

    • Auto Attached: ativa automaticamente conforme o tipo de arquivo; recomendado
    Exemplo: arquivos *.tsx aplicam as regras de React
    Indicado para 80% das regras

    • Agent Requested: a IA decide se a regra é necessária
    Indicado para regras auxiliares opcionais

    • Manual: só ativa quando chamada manualmente
    Indicado para casos especiais, como desempenho ou testes

    Sugestão: 80% Auto Attached + 10% Always + 10% Manual/Agent
  5. 5

    Step 5: Testar e aprimorar as regras

    Processo de teste:
    1. Depois de configurar as regras, peça ao Cursor que gere um componente de teste
    2. Verifique se o código gerado segue todos os padrões
    3. Se não seguir, confirme se as regras foram ativadas

    Como depurar:
    • Pergunte ao Cursor: "Quais regras você está vendo?"
    • Confira se o caminho das regras está correto
    • Confira o escopo de aplicação
    • Procure conflitos entre regras

    Como aprimorar:
    • Divida o arquivo se ele ultrapassar 500 linhas
    • Coloque as regras importantes no início, onde a IA tende a prestar mais atenção
    • Prefira exemplos de código a explicações textuais
    • Evite regras contraditórias

    Soluções para problemas comuns:
    • A IA ignora a regra → inclua exemplos e mude o escopo para Always
    • Há regras em conflito → defina a prioridade e remova a regra de menor prioridade
    • A regra é vaga → transforme-a em uma instrução específica e executável
  6. 6

    Step 6: Colaborar em equipe e manter as regras

    Inclua as regras no controle de versão:
    git add .cursor/rules
    git commit -m "Add Cursor rules for project standards"

    Colaboração em equipe:
    • Integração de novos membros: explique no README onde estão as regras e o que elas cobrem
    • Discussão das regras: converse com a equipe antes de alterá-las
    • Revisão periódica: verifique a cada trimestre se alguma regra ficou obsoleta

    Manutenção contínua:
    • Atualize as regras junto com a stack
    • Colete feedback da equipe e refine as regras
    • Adicione novas boas práticas
    • Trate as regras como documentação viva, não como configuração descartável

    Recursos da comunidade:
    • awesome-cursorrules: mais de 2.000 estrelas e mais de 30 frameworks
    • awesome-cursorrules-zh: versão adaptada para desenvolvedores chineses
    • cursorrules.org: biblioteca de regras on-line
    • Comece com uma regra da comunidade e adapte-a ao projeto

FAQ

Qual é a diferença entre .cursorrules e .cursor/rules no Cursor Rules?
.cursorrules é o método antigo, usado antes de 2025: um único arquivo na raiz do projeto reúne todas as regras.

.cursor/rules é o método recomendado em 2026. Ele permite criar vários arquivos .mdc, separar as regras por função, como frontend.mdc e backend.mdc, e configurar escopos como Always e Auto Attached.

A recomendação oficial é migrar para o novo formato, pois o antigo será descontinuado. Em projetos novos, use o formato novo desde o início; em projetos antigos, faça a migração gradualmente.
O que fazer quando o Cursor não segue as regras?
Possíveis causas e soluções:

1. Regra vaga: troque por uma instrução específica, como "use componentes funcionais, não componentes de classe", em vez de "siga as boas práticas"
2. Regra longa demais: limite-a a 500 linhas e coloque as regras importantes no início
3. Falta de exemplos: inclua exemplos corretos de código para facilitar a interpretação pela IA
4. Escopo incorreto: confirme se a regra usa Auto Attached ou Always
5. Conflito com o prompt: diga explicitamente na conversa para seguir as regras do projeto

Para depurar, pergunte ao Cursor "Quais regras você está vendo?" e confirme se elas foram carregadas.
Como escolher entre User Rules e Project Rules?
User Rules (regras globais):
• Caminho: File → Preferences → Cursor Settings → Rules → User Rules
• Uso: preferências pessoais, como "usar TypeScript em todos os projetos" ou "não usar var"
• Aplicam-se a todos os projetos

Project Rules (regras do projeto):
• Caminho: arquivos .mdc no diretório .cursor/rules
• Uso: padrões específicos, como "este projeto usa React 18 e Tailwind"
• Aplicam-se apenas ao projeto atual

Prioridade: regras do projeto > regras globais. Coloque preferências gerais nas regras globais e a stack e os padrões de negócio nas regras do projeto.
O que fazer quando um arquivo de regras ultrapassa 500 linhas?
Separe as regras por função em vários arquivos .mdc:

.cursor/rules/
├── core.mdc (stack principal, Always)
├── frontend.mdc (regras de frontend, Auto Attached: *.tsx)
├── backend.mdc (regras de backend, Auto Attached: *.py)
├── typescript.mdc (regras de TypeScript)
└── testing.mdc (regras de teste, Auto Attached: *.test.*)

Critérios para dividir:
• Separe por área técnica, como frontend, backend e testes
• Configure Auto Attached conforme o tipo de arquivo
• Use Always para regras centrais e ative as demais quando necessário
• Mantenha cada arquivo abaixo de 500 linhas para facilitar a interpretação pela IA
Onde encontrar modelos prontos de Cursor Rules?
Recursos recomendados da comunidade:

1. awesome-cursorrules (mais de 2.000 estrelas no GitHub)
• Cobre mais de 30 frameworks populares, como React, Vue, Python e Go
• Basta copiar e fazer pequenos ajustes
• https://github.com/PatrickJS/awesome-cursorrules

2. awesome-cursorrules-zh (adaptado para desenvolvedores chineses)
• Oferece exemplos que combinam regras, como React + FastAPI em um projeto full stack
• https://github.com/LessUp/awesome-cursorrules-zh

3. cursorrules.org (biblioteca on-line)
• Permite visualizar e copiar regras no navegador
• Cobre mais de 30 frameworks

Sugestão: comece com regras da comunidade, use-as por algum tempo e adapte-as às necessidades do projeto, em vez de escrever tudo do zero.
Como uma equipe pode compartilhar e manter o Cursor Rules?
Boas práticas para equipes:

1. Inclua no controle de versão Git
git add .cursor/rules
git commit -m "Add Cursor rules"
Os membros da equipe carregarão as regras automaticamente depois de baixar o código

2. Documente no README
Registre a localização das regras, o que elas cobrem e o processo de alteração
Apresente as regras durante a integração de novos membros

3. Faça revisões periódicas
A cada trimestre, verifique se existem regras obsoletas, novas práticas necessárias ou feedback da equipe

4. Defina um processo de alteração
Discuta antes de mudar → chegue a um consenso → atualize as regras → avise a equipe

Trate as regras como documentação viva e aprimore-as junto com o projeto.

19 min de leitura · Publicado em: 10 jan 2026 · Atualizado em: 4 set 2026

Comentários

Entre com GitHub para comentar

Easton BlogEaston Blog