Configuração avançada do Cursor Rules: crie seu assistente de programação com IA

No mesmo projeto, o Cursor às vezes gera um código elegante e coerente com seu estilo, mas em outras ocasiões entrega algo completamente diferente do que você costuma escrever. Você colocou várias regras no .cursorrules, mas a IA parece ignorá-las. Ao trocar de projeto, precisa configurar tudo novamente.

Também passei por isso quando comecei a usar o Cursor Rules. Gastei algumas horas escrevendo regras, mas o código gerado pela IA continuava igual. Só depois percebi que o problema não estava nas regras em si, e sim na forma como eu entendia o sistema.

Este artigo trata do uso avançado do Cursor Rules. Não é apenas uma introdução sobre “o que é o .cursorrules”, mas um conjunto de práticas para fazer essa ferramenta funcionar bem em projetos reais.

1. Repensando os conceitos centrais do Cursor Rules

1.1 Do .cursorrules ao .cursor/rules: a evolução do sistema de regras

Se você usa o Cursor há algum tempo, talvez ainda trabalhe com o arquivo único tradicional .cursorrules. Ele funciona, mas suas limitações são bem claras.

Qual é o problema de usar um único arquivo? Primeiro, todas as regras ficam concentradas no mesmo lugar, o que dificulta a manutenção. Segundo, não é possível definir regras diferentes para tipos de arquivo distintos. Por exemplo, se o projeto contém componentes React e scripts Python, você não consegue separar as regras por tecnologia nesse formato.

Em 2026, o Cursor lançou a nova estrutura de diretórios .cursor/rules/. Junto com o formato MDC, ela resolve boa parte desses problemas.

A nova estrutura fica assim:

.cursor/
└── rules/
    ├── base.mdc          # Convenções básicas
    ├── frontend.mdc      # Regras de frontend
    ├── backend.mdc       # Regras de backend
    └── testing.mdc       # Regras de teste

Cada arquivo é um módulo de regras independente, e você pode definir seu alcance com padrões glob. Por exemplo, frontend.mdc pode ser aplicado apenas a arquivos .tsx, enquanto backend.mdc vale somente para arquivos .py.

A migração também não é complicada. O .cursorrules continua funcionando em projetos antigos, enquanto projetos novos podem adotar diretamente o formato atual. Para atualizar um projeto antigo, basta dividir o arquivo único em vários arquivos .mdc. O formato é retrocompatível, então não é preciso se preocupar com problemas durante a transição.

1.2 Quando usar cada um dos três tipos de regra

O sistema do Cursor tem três tipos de regra, e muita gente se confunde sobre a relação entre eles.

As Project Rules (regras do projeto) ficam no diretório .cursor/rules/ e valem apenas para o projeto atual. Elas são adequadas para informações específicas, como uma stack baseada em React 18 e Tailwind. Quando outras pessoas da equipe clonarem o projeto, essas regras estarão disponíveis automaticamente.

As Team Rules (regras da equipe) ficam na nuvem e são compartilhadas pelos integrantes. Elas servem para convenções coletivas, como “todos os componentes usam exportações nomeadas” ou “as respostas de API seguem o mesmo formato”. Esse recurso exige o plano Team do Cursor.

As User Rules (regras do usuário) são configuradas nos ajustes do Cursor e valem para todos os seus projetos. Use-as para preferências pessoais, como indentação com tabulações ou espaços e comentários em português ou inglês.

A prioridade funciona assim: User Rules têm a maior prioridade, seguidas pelas Team Rules e, por último, pelas Project Rules. Portanto, se uma User Rule exigir indentação com espaços e uma Project Rule exigir tabulações, o Cursor seguirá a User Rule.

1.3 Como as regras são aplicadas nos bastidores

Esta parte é um pouco mais técnica, mas entendê-la ajuda bastante na hora de escrever regras.

Ao processar sua solicitação, a IA recebe o conteúdo dos arquivos de regras como parte do contexto. Isso significa que as regras consomem tokens. Portanto, uma regra maior nem sempre é melhor: texto redundante desperdiça tokens e pode até prejudicar o resultado.

A correspondência de padrões de arquivo com globs funciona de forma parecida com o .gitignore. O padrão ["**/*.tsx"] corresponde a todos os arquivos tsx, enquanto ["app/api/**/*"] corresponde a todos os arquivos no diretório app/api.

Vultr - Servidor cloud NVMe de alto desempenho, 32 locais globais, deploy Docker com um clique

Ver preços →Anúncio

E se várias regras forem aplicadas ao mesmo arquivo? O Cursor as carrega em ordem lexicográfica pelo nome do arquivo, e as regras carregadas primeiro têm maior prioridade. Por isso, você pode usar prefixos numéricos para controlar a ordem, como 00-base.mdc e 01-frontend.mdc.

2. Configuração prática: um guia completo do zero

2.1 Configuração básica para um projeto React + TypeScript

Vamos começar por um projeto React simples. A configuração completa abaixo pode ser copiada diretamente para .cursor/rules/react.mdc:

---
description: Regras do projeto React + TypeScript
globs: ["**/*.{ts,tsx}"]
---

# Stack
- React 18+
- TypeScript 5.0+
- Tailwind CSS

# Estilo do código
- Use componentes funcionais declarados com a palavra-chave function
- Defina Props com interfaces do TypeScript
- Organize os arquivos de componentes assim: componente exportado → subcomponentes → funções auxiliares → tipos
- Use exportações nomeadas e evite default export

# Boas práticas de React
- Priorize Server Components ao usar Next.js
- Gerencie o estado com useState e useReducer
- Trate efeitos colaterais com useEffect e sempre escreva a função de limpeza
- Use React.memo em componentes sensíveis a desempenho

# Tratamento de erros
- Priorize o padrão early return
- Use guard clauses para tratar casos-limite
- Mostre mensagens de erro úteis para o usuário em vez de lançar o erro bruto diretamente

A estrutura dessa regra é simples. Primeiro, ela declara a stack para que a IA saiba quais tecnologias o projeto usa. Depois, define o estilo de código esperado. Por fim, apresenta boas práticas e orientações específicas de tratamento de erros.

2.2 Configuração avançada para um projeto full stack com Next.js 14

Projetos Next.js são um pouco mais complexos porque envolvem frontend e backend. A melhor opção é organizar as regras de forma modular:

.cursor/
└── rules/
    ├── base.mdc          # Convenções básicas
    ├── api.mdc           # Regras de rotas de API
    ├── components.mdc    # Regras de componentes
    ├── database.mdc      # Regras de banco de dados
    └── testing.mdc       # Regras de teste

Veja um exemplo de api.mdc:

---
globs: ["app/api/**/*.{ts,tsx}"]
---

# Convenções para rotas de API
- Use Route Handlers (app/api/)
- Use o mesmo tipo APIResponse para todas as respostas
- Valide os parâmetros da solicitação com Zod
- Trate erros com next-safe-action

# Formato da resposta
- Solicitações GET: retorne { success: boolean, data?: T, error?: string }
- Solicitações POST: valide a entrada → processe a lógica → retorne a resposta
- Classifique e trate separadamente erros de validação, erros de negócio e erros do sistema

A vantagem dessa abordagem é que as regras de API só são aplicadas quando você edita arquivos no diretório app/api/. Ao escrever um componente, a IA não apresentará várias sugestões irrelevantes relacionadas à API.

2.3 Configuração avançada para um backend Python com FastAPI

Se o backend é escrito em Python, a configuração das regras muda um pouco:

---
description: Regras do projeto Python FastAPI
globs: ["**/*.py"]
---

# Stack
- Python 3.12+
- FastAPI 0.100+
- SQLAlchemy 2.0
- Pydantic v2

# Estilo do código
- Formate o código com Black
- Organize as importações com isort
- Escreva type hints sem atalhos
- Use snake_case nos nomes de funções

# Boas práticas de FastAPI
- Gerencie conexões com o banco de dados por injeção de dependência
- Valide entradas com modelos Pydantic
- Processe tarefas assíncronas com background tasks
- Implemente um middleware unificado para tratamento de erros

# Banco de dados
- Use a API assíncrona do SQLAlchemy 2.0
- Gerencie migrações do banco de dados com Alembic
- Implemente exclusão lógica e logs de auditoria

Em projetos Python, as regras se concentram nas ferramentas de estilo, como Black e isort, e nas anotações de tipo. A IA passa a seguir essas convenções ao gerar o código.

2.4 Configuração colaborativa para projetos com várias pessoas

Se você é Tech Lead e quer unificar o estilo de código da equipe, pode organizar os arquivos desta forma:

Raiz do projeto/
├── .cursor/
│   └── rules/
│       ├── README.md           # Instruções de uso das regras
│       ├── base.mdc            # Convenções básicas globais
│       ├── frontend.mdc        # Regras de frontend
│       ├── backend.mdc         # Regras de backend
│       └── team-guidelines.mdc # Convenções da equipe
└── .cursorrules                # Retrocompatibilidade (opcional)

Algumas práticas recomendadas:

Adicione as regras ao controle de versão. Assim, cada pessoa que clonar o projeto poderá usá-las sem nenhuma configuração extra.

Inclua comentários explicativos em cada arquivo de regras. Quem entrar na equipe poderá entender as convenções de código apenas consultando esses arquivos.

Revise e atualize as regras periodicamente. O projeto evolui, e as regras precisam acompanhar essa mudança. Vale revisar os resultados a cada iteração.

3. Depuração e otimização para fazer as regras funcionarem de verdade

3.1 Técnicas para depurar regras

Você escreveu as regras, mas a IA não as segue? Esse é o problema mais comum. Use esta lista de diagnóstico:

1. Verifique o local do arquivo

Os arquivos de regras precisam estar no local correto:

• no diretório .cursor/rules/, que é a opção recomendada
• ou no arquivo .cursorrules da raiz do projeto

Se estiverem em outro lugar, a IA não conseguirá acessá-los.

2. Verifique o padrão glob

Se a configuração de globs estiver incorreta, a regra não será aplicada. Abra um arquivo no Cursor e pergunte diretamente à IA: “Quais regras estão carregadas agora?” Ela informará quais arquivos de regras conseguiu identificar.

3. Verifique o formato YAML

O frontmatter no início de um arquivo MDC usa o formato YAML. Erros de indentação ou a ausência de dois-pontos podem impedir a análise do arquivo.

4. Verifique conflitos entre regras

Várias regras podem entrar em conflito. Confira se duas delas definem orientações diferentes sobre o mesmo assunto e, se necessário, consolide-as.

3.2 Estratégias para otimizar as regras

Muita gente acredita que, quanto mais regras, melhor. Não é bem assim. Quando as regras ficam longas demais, a IA tem dificuldade para “digeri-las”.

KiloClaw - OpenClaw gerenciado para empresas: orquestração de agentes IA e roteamento inteligente

Começar →Anúncio

Princípio 1: seja conciso

Coloque as regras mais importantes primeiro. A IA lê o arquivo do início ao fim, e o conteúdo inicial tende a ser lembrado com mais facilidade.

Princípio 2: seja específico

Compare os exemplos:

Forma vaga:

# Estilo do código
- Escreva código conciso
- Use boas práticas
- Considere o desempenho

Forma específica:

# Estilo do código
- Use componentes funcionais e evite componentes de classe
- Use o padrão early return para reduzir o aninhamento
- Use React.memo em componentes sensíveis a desempenho
- Evite funções inline dentro de loops

No segundo formato, a IA sabe exatamente o que fazer. No primeiro, ela só pode tentar adivinhar.

Princípio 3: organize em camadas

Organize o conteúdo na ordem “stack → estilo do código → boas práticas → tratamento de erros”. Uma estrutura lógica também facilita a compreensão pela IA.

Princípio 4: ajuste continuamente

As regras não ficam prontas para sempre depois da primeira versão. Use-as por algum tempo, avalie se a qualidade do código gerado pela IA melhorou e ajuste os pontos problemáticos.

3.3 Como avaliar os resultados das regras

Como saber se as regras estão ajudando? Observe estes indicadores:

• Taxa de aprovação na primeira tentativa: qual porcentagem do código gerado pela IA pode ser usada diretamente?
• Consistência de estilo: o código gerado em momentos diferentes mantém o mesmo padrão?
• Quantidade de bugs: o número de bugs diminuiu depois que as regras passaram a ser aplicadas?
• Produtividade no desenvolvimento: você passou a escrever código mais rápido?

Registre esses indicadores e compare os resultados antes e depois da adoção das regras. Assim, você saberá se elas realmente estão ajudando.

4. Práticas mais recentes de 2026: formato MDC e modularização

4.1 Entendendo o formato MDC em profundidade

MDC é o novo formato de regras lançado pelo Cursor e oferece bem mais flexibilidade do que o .cursorrules tradicional.

A estrutura do arquivo é esta:

---
description: Descrição da regra (opcional)
globs: ["padrão de correspondência de arquivo"]
alwaysApply: false (opcional; o padrão é false)
---

# Conteúdo da regra
Escreva aqui o conteúdo específico da regra...

description é um texto voltado para pessoas e facilita a compreensão do objetivo da regra.

globs é o padrão de correspondência de arquivos que determina onde a regra é aplicada:

• ["**/*.tsx"] — corresponde a todos os arquivos tsx
• ["app/api/**/*"] — corresponde a todos os arquivos do diretório app/api
• ["*.test.{ts,tsx}"] — corresponde apenas a arquivos de teste

Quando alwaysApply é definido como true, a regra é aplicada o tempo todo, sem considerar o padrão de arquivo. Em geral, não é recomendável usar essa opção porque ela desperdiça tokens.

4.2 Arquitetura modular de regras

Para projetos grandes, prefira uma estrutura modular com granularidade maior:

.cursor/
└── rules/
    ├── 00-base.mdc           # Convenções básicas
    ├── 01-tech-stack.mdc     # Declaração da stack
    ├── 02-code-style.mdc     # Estilo do código
    ├── 10-frontend/          # Regras de frontend (subdiretório)
    │   ├── react.mdc
    │   └── tailwind.mdc
    ├── 20-backend/           # Regras de backend (subdiretório)
    │   ├── api.mdc
    │   └── database.mdc
    └── README.md             # Documentação das regras

Os prefixos numéricos controlam a ordem de carregamento. Arquivos iniciados por 00- são carregados antes dos que começam com 10-. Isso garante que as convenções básicas sejam aplicadas primeiro.

Os subdiretórios permitem um gerenciamento mais detalhado. As regras de frontend ficam em 10-frontend/, e as de backend em 20-backend/, o que facilita encontrá-las.

4.3 Ferramentas recomendadas para gerar regras

Não quer escrever tudo do zero? Algumas ferramentas da comunidade podem ajudar:

Alibaba Cloud - Escolha dos desenvolvedores, 15% de desconto exclusivo em Lighthouse

Ganhar 15% off →Anúncio

cursor.directory — biblioteca de regras online com modelos para vários frameworks, prontos para copiar.

cursorrules.org — gerador interativo de regras que cria um arquivo automaticamente depois que você responde a algumas perguntas.

awesome-cursorrules — coleção selecionada no GitHub com mais de 100 modelos para mais de 20 frameworks.

Ainda assim, recomendo começar por um modelo e adaptá-lo ao seu projeto. Não copie sem avaliar: entender o raciocínio por trás das regras é o que permite criar uma configuração realmente adequada ao seu contexto.

5. Resumo e próximos passos

5.1 Lista rápida para começar

Se quiser começar agora, siga estas etapas:

Primeira etapa: identifique o tipo de projeto. React, Next.js, Python ou outra tecnologia?

Segunda etapa: escolha um modelo parecido entre os recursos da comunidade. O cursor.directory e o awesome-cursorrules têm várias opções.

Terceira etapa: adapte o modelo às características do projeto. Atualize as versões da stack e acrescente suas próprias preferências.

Quarta etapa: teste o resultado. Escreva alguns trechos de código e observe se o código gerado pela IA corresponde melhor ao que você espera.

Quinta etapa: compartilhe com a equipe. Se o resultado for bom, adicione as regras ao controle de versão para que todos possam usá-las.

5.2 Armadilhas que você deve evitar

Estas são algumas armadilhas que encontrei:

Regras vagas demais — a IA não sabe o que você espera. Escreva orientações específicas.

Arquivos de regras muito longos — tente ficar abaixo de 200 linhas. Se o arquivo for grande demais, a IA não conseguirá processar tudo.

Uso sem testes — faça uma validação em pequena escala antes de adotar as regras em todo o projeto.

Ausência de atualizações — o projeto muda, e as regras também precisam evoluir. Revise-as periodicamente.

5.3 Recursos para continuar aprendendo

Se quiser se aprofundar, consulte estes recursos:

• Documentação oficial do Cursor — a referência mais confiável
• awesome-cursorrules — regras selecionadas pela comunidade
• Fórum da comunidade do Cursor — discussões e experiências compartilhadas

Abra seu projeto e configure agora a primeira regra no Cursor Rules. Comece com algo simples e melhore aos poucos. Você vai se surpreender com o quanto a IA pode passar a “entender” melhor suas preferências.