Cursor rules: como manter a IA alinhada com a sua base de código

Você abre um novo chat no Cursor e cola o mesmo bloco de instruções que já colou centenas de vezes. Sua stack, suas convenções de nomenclatura e a estrutura de pastas que a IA insiste em errar. Aí ela gera uma classe de 40 linhas, com três camadas de abstração, quando tudo que você precisava era uma função.

Hora de acordar desse pesadelo. As regras do Cursor são arquivos de projeto que tornam desnecessário ficar colando instruções. Escreva suas convenções uma vez e o resultado da IA passa a seguir sua base de código — em vez de brigar com ela.

Este tutorial monta um conjunto de arquivos de regra .mdc para um projeto web em Python com FastAPI e pytest, cobrindo contexto do projeto, simplicidade de código e formatação de erros de API. Se você é novo no Cursor, recomendo fazer antes nosso curso Software Development with Cursor, depois abrir um projeto e acompanhar.

O que são as regras do Cursor?

As regras do Cursor são arquivos markdown com frontmatter específico do MDC que ficam no seu projeto em .cursor/rules/. Antes do seu prompt chegar ao modelo, o Cursor verifica quais regras correspondem e antepõe o conteúdo delas à janela de contexto. Suas instruções entram primeiro, sempre.

Cada arquivo .mdc tem três campos de frontmatter que controlam a ativação: description, globs e alwaysApply. Uma regra pode valer para todas as conversas ou só quando certos arquivos estão abertos. Uma terceira opção, Aplicar de forma inteligente, deixa o agente ler a descrição e decidir sozinho se a regra é relevante. A próxima seção mostra cada tipo na prática.

O Cursor oferece quatro categorias de regras:

As regras de projeto substituíram o antigo arquivo .cursorrules, um único arquivo na raiz sem escopo nem metadados, dividindo as regras em vários arquivos .mdc com frontmatter.

AGENTS.md é a alternativa mais simples para projetos que não precisam de escopo por glob. É markdown puro, reconhecido por ferramentas de codificação com IA além do Cursor, e arquivos mais profundos em subpastas substituem os dos diretórios pai.

Você pode saber mais sobre como fluxos de trabalho baseados em agentes se conectam ao seu processo de desenvolvimento na nossa trilha de habilidades AI Agent Fundamentals.

Criando e configurando regras de projeto do Cursor

O restante deste tutorial cria arquivos de regra para um projeto FastAPI usando pytest. Os padrões se aplicam a qualquer stack.

Configurando o diretório e os arquivos de regras

Crie um diretório .cursor/rules/ na raiz do seu projeto. Todo arquivo .mdc colocado aqui vira uma regra que o Cursor detecta na hora, sem precisar reiniciar.

O primeiro arquivo de regra, project-context.mdc, dá à IA consciência permanente da sua stack e do layout de pastas:

---
description: ""
alwaysApply: true
globs:
---
 
# Project Context
 
This is a FastAPI web application with pytest for testing.
 
## Tech Stack
- Python 3.12, FastAPI, Pydantic v2, SQLAlchemy 2.0
- pytest with pytest-asyncio for async test support
- Alembic for database migrations
 
## Project Structure
- app/main.py: FastAPI application entry point
- app/routers/: API route handlers
- app/models/: SQLAlchemy models
- app/schemas/: Pydantic request/response schemas
- tests/: pytest test files mirroring app/ structure
 
## Patterns
- All endpoints are async
- Use dependency injection for database sessions
- Response models are always Pydantic schemas, not raw dicts

Digitar /create-rule em um chat do Agent é outro caminho: o Cursor redige uma regra para você em um painel de chat.

O frontmatter alwaysApply: true faz essa regra carregar em toda conversa. Dê nomes aos arquivos em kebab-case por tema (project-context.mdc, simplicity.mdc, error-responses.mdc) e mantenha cada um com menos de 500 linhas. Arquivo de regra inchado consome espaço da janela de contexto que você precisa para o código e os prompts de verdade. Faça commit do diretório .cursor/rules/ no git.

Configurando metadados das regras para correspondência precisa

A regra project-context.mdc acima usa alwaysApply: true, o modo mais simples: toda conversa a carrega, independente dos arquivos em que você está trabalhando. É a escolha certa para contexto de projeto.

Algumas regras se aplicam só a partes específicas da base de código. Defina alwaysApply: false e adicione padrões glob, separados por vírgula, para delimitar o escopo. Uma regra com globs: app/routers/**/*.py dispara apenas quando arquivos correspondentes (aqui: arquivos Python em app/routers/ ou subpastas) entram no contexto, mantendo convenções de API fora de chats sem relação.

Aplicar de forma inteligente ignora padrões de arquivo. Você deixa globs vazio e escreve uma description detalhada; o agente decide se a regra é relevante para a conversa atual. A qualidade da descrição faz diferença: "Error handling rules" é vaga demais para corresponder com confiabilidade, mas "Conventions for FastAPI error responses including HTTP status codes, error body structure, and exception handler patterns" tem sinais claros.

Regras sem globs, sem descrição útil e com alwaysApply: false viram manuais: são carregadas quando você digita @rule-name no chat. Boas para materiais de referência que você puxa sob demanda.

Escrevendo o conteúdo das regras e restrições

Regras escritas com linguagem branda ("tente manter funções pequenas", "prefira endpoints assíncronos") dão margem para a IA ignorá-las. Escreva comandos: "Funções devem ter no máximo 30 linhas. Todos os endpoints devem ser async."

Na introdução, citamos a IA gerando uma classe de 40 linhas com três camadas de abstração. A regra que evita esse comportamento é simplicity.mdc:

---
description: ""
alwaysApply: true
globs:
---
 
# Code Simplicity
 
Write the simplest code that solves the problem. Every abstraction must earn its place.
 
## Constraints
- No base classes with one child class
- No interfaces or abstract classes with one implementation
- No factory or strategy patterns when an if statement works
- No wrapper functions that just call another function
- No configurable parameters that nothing passes
- No "just in case" error handling for impossible conditions
 
## When modifying existing code
- Match the patterns already in the codebase
- Do not refactor surrounding code unless asked
- Do not add type annotations to unchanged code
- Do not add docstrings to unchanged functions
 
## Code size
- Functions under 30 lines
- If a function needs a comment explaining what a block does, extract that block into a named function instead

A diferença é imediata. A IA para de recorrer a classes base abstratas quando só existe uma implementação e usa ifs quando há dois casos.

A terceira regra, error-responses.mdc, tem escopo por glob para disparar apenas ao trabalhar com arquivos de rotas de API:

---
description: "Standard error response format for all API endpoints"
alwaysApply: false
globs: app/routers/**/*.py
---
 
# API Error Responses
 
All error responses must follow this structure:
 
{
  "detail": "Human-readable error message",
  "code": "MACHINE_READABLE_CODE",
  "field": "optional_field_name"
}
 
## Rules
- Never return raw exception messages to clients
- Use HTTPException with a detail dict matching the structure above
- 400 for validation errors, 404 for missing resources, 409 for conflicts
- Log the full traceback server-side before returning the sanitized response

Sempre que possível, aponte para arquivos existentes na sua base de código em vez de copiar código para as regras. Uma linha como "Veja app/routers/users.py para a estrutura canônica deendpoints" se mantém atual conforme o código evolui, enquanto um trecho copiado fica obsoleto assim que alguém refatora o original.

Testando e verificando o anexo das regras

O Cursor não tem um indicador nativo mostrando quais regras estão ativas em uma conversa. Você verifica testando o comportamento.

Abra um novo chat do Agent e escreva um prompt que deveria acionar uma das suas regras. Para error-responses.mdc, tente: "Adicione um endpoint DELETE para remover um usuário por ID em app/routers/users.py." Se o tratamento de erro gerado não lembrar em nada a estrutura JSON da sua regra ou pular o HTTPException com o dict detail, algo na correspondência falhou.

Regras com escopo por glob precisam de um arquivo correspondente referenciado no seu prompt ou aberto no editor. Testar error-responses.mdc sem mencionar nenhum arquivo dentro de app/routers/ significa que a regra nunca vai ativar. 

Regras de "Aplicar de forma inteligente" são baseadas em tópico: tente um prompt relacionado à descrição da regra e outro sem relação, e compare as saídas. O agente deve seguir a regra no primeiro e ignorá-la no segundo.

Mantendo suas regras do Cursor eficazes

Regras que funcionaram no mês passado podem confundir a IA depois de um refactor ou de renomear uma pasta.

Solucionando falhas de correspondência

O motivo mais comum para uma regra não disparar é a extensão do arquivo: as regras devem usar .mdc; arquivos .md simples em .cursor/rules/ são ignorados silenciosamente.

Além disso:

• Globs amplos demais, como **/*.py, anexam a regra a todo arquivo Python do projeto. Restrinja para app/routers/**/*.py ou tests/**/*.py, para a regra disparar só onde faz sentido.

• Você vai perceber regras de "Aplicar de forma inteligente" ficando de fora quando a descrição é genérica demais. Valem aqui os exemplos de boas/más descrições da seção de metadados.

• Regras conflitantes são mais difíceis de notar. Quando duas regras dão instruções contraditórias para os mesmos arquivos, a IA escolhe uma (geralmente a carregada por último). Corrija estreitando o escopo dos globs para que não haja sobreposição, ou consolide orientações relacionadas em um único arquivo.

Um detalhe importante: alterações em arquivos .mdc às vezes somem sem salvar. Se os edits não estiverem persistindo, feche completamente o Cursor, selecione "Override" no pop-up de alterações não salvas e reabra.

Fazendo as regras valerem no meio da conversa

Uma regra pode disparar corretamente no início da conversa e ainda assim ser ignorada cinco mensagens depois. O culpado é o viés de recência da janela de contexto: conforme a conversa cresce, o modelo prioriza as mensagens mais recentes sobre as instruções injetadas no topo. Esse é o problema mais comum na comunidade do Cursor, e não há uma configuração que resolva.

O contorno é o reforço. Quando a saída começar a se afastar das suas regras, adicione algo como "siga as regras do projeto para respostas de erro" no próximo prompt. Isso traz a instrução de volta para o contexto recente do modelo. 

Para regras que importam em toda resposta (formatação, nomenclatura), frases mais curtas e diretas resistem melhor em conversas longas do que parágrafos detalhados.

Regras com exemplos de código também resistem melhor ao desvio do que instruções só em texto. Em vez de escrever "use retornos antecipados no tratamento de erros", inclua um pequeno bloco antes/depois mostrando o padrão desejado. O modelo ancora com mais confiabilidade em código real do que em descrições em prosa, especialmente conforme o contexto aumenta.

Mantendo e podando regras

Revise as regras após qualquer refactor grande, atualização de dependências ou reestruturação de pastas. Uma regra que referencia APIs obsoletas ou arquivos removidos vai passar instruções erradas para a IA. Globs desatualizados são ainda mais silenciosos ao falhar: se você renomear app/api/ para app/routers/, uma regra com escopo no caminho antigo simplesmente para de disparar sem aviso.

Podar também vale ao contrário. Conforme os modelos evoluem, eles passam a seguir convenções comuns sem serem instruídos. Se a IA já está seguindo a orientação de uma regra sem precisar dela, apague a regra e recupere os tokens. Um conjunto saudável de regras tende a encolher com o tempo, não só crescer.

Escalando regras para times

Trate as regras como código da aplicação. Mudanças passam por pull requests, e o time combina o padrão antes de entrar em .cursor/rules/.

Para organizações nos planos Business ou Enterprise, as Team Rules permitem que admins imponham regras para todos os membros via dashboard do Cursor. "Enable immediately" ativa a regra por padrão e ainda permite que usuários a desativem. "Enforce this rule" remove a possibilidade de opt-out, cobrindo convenções inegociáveis como práticas de segurança e requisitos de compliance.

Conclusão

Comece com uma ou duas regras para os padrões que você corrige com mais frequência. Se você vive editando o mesmo tipo de saída da IA a cada sessão (formato de erro errado, abstrações desnecessárias), isso é uma regra pedindo para ser escrita. Adicione mais conforme identificar erros recorrentes e elimine as que deixarem de fazer diferença.

Os arquivos .mdc deste tutorial servem para um projeto FastAPI. Os seus vão ser diferentes em um frontend Next.js ou uma CLI em Rust — e essa é a ideia: eles codificam as convenções do seu time, não "melhores práticas" genéricas. 

Se quiser se aprofundar no Cursor, confira nosso guia do Cursor 2.0. Para comparar com outros assistentes de codificação com IA, recomendo ler nossas análises comparativas:

• Cursor vs GitHub Copilot
• Claude Code vs Cursor
• Cline vs Cursor
• Cursor vs. Windsurf