Regras

Controla como o modelo Agent se comporta com instruções reutilizáveis e com escopo.

Regras fornecem instruções em nível de sistema para Agent e Inline Edit. Pensa nelas como contexto persistente, preferências ou fluxos de trabalho pros teus projetos.

O Cursor oferece suporte a quatro tipos de regras:

Regras do Projeto

Armazenadas em .cursor/rules, com controle de versão e com escopo para teu codebase.

Regras do Usuário

Globais no teu ambiente do Cursor. Definidas nas configurações e sempre aplicadas.

AGENTS.md

Instruções do Agent em formato Markdown. Alternativa simples a .cursor/rules.

.cursorrules (Legado)

Ainda compatível, mas obsoleto. Usa Regras do Projeto em vez disso.

Como as regras funcionam

Modelos de linguagem grandes não mantêm memória entre gerações. As regras fornecem contexto persistente e reutilizável no nível do prompt.

Quando aplicadas, o conteúdo das regras é incluído no início do contexto do modelo. Isso dá à IA uma orientação consistente para gerar código, interpretar edições ou ajudar em fluxos de trabalho.

As regras se aplicam ao Chat e ao Inline Edit. As regras ativas aparecem na barra lateral do Agent.

Regras do projeto

As regras do projeto ficam em .cursor/rules. Cada regra é um arquivo com controle de versão. Elas podem ter escopo usando padrões de caminho, ser invocadas manualmente ou incluídas com base na relevância. Subdiretórios podem incluir seu próprio diretório .cursor/rules com escopo para aquela pasta.

Usa regras do projeto para:

• Codificar conhecimento específico do domínio sobre tua base de código
• Automatizar fluxos de trabalho ou templates específicos do projeto
• Padronizar decisões de estilo ou de arquitetura

Anatomia de uma regra

Cada arquivo de regra é escrito em MDC (.mdc), um formato que suporta metadados e conteúdo. Controla como as regras são aplicadas a partir do menu suspenso de tipo, que altera as propriedades description, globs, alwaysApply.

Rule Type	Description
Always	Sempre incluída no contexto do modelo
Auto Attached	Incluída quando arquivos que batem com um padrão glob são referenciados
Agent Requested	Disponível para a IA, que decide se deve incluí-la. Deve fornecer uma descrição
Manual	Só incluída quando mencionada explicitamente usando @ruleName

---
description: RPC Service boilerplate
globs:
alwaysApply: false
---

- Usa nosso padrão interno de RPC ao definir serviços
- Sempre usa snake_case para nomes de serviço.

@service-template.ts

Regras aninhadas

Organiza regras colocando-as em diretórios .cursor/rules ao longo do teu projeto. Regras aninhadas são anexadas automaticamente quando arquivos no diretório delas são referenciados.

project/
  .cursor/rules/        # Regras do projeto inteiro
  backend/
    server/
      .cursor/rules/    # Regras específicas do backend
  frontend/
    .cursor/rules/      # Regras específicas do frontend

Criando uma regra

Cria regras usando o comando New Cursor Rule ou indo em Cursor Settings > Rules. Isso cria um novo arquivo de regra em .cursor/rules. Nas configurações tu vês todas as regras e o status delas.

Gerando regras

Gera regras diretamente em conversas usando o comando /Generate Cursor Rules. Útil quando tu já decidiste sobre o comportamento do agente e quer reutilizar essas decisões.

Melhores práticas

Boas regras são focadas, acionáveis e bem delimitadas.

• Mantém as regras com menos de 500 linhas
• Divide regras grandes em várias regras componíveis
• Fornece exemplos concretos ou arquivos de referência
• Evita orientações vagas. Escreve regras como docs internas claras
• Reutiliza regras ao repetir prompts no chat

Exemplos

Padrões para componentes de frontend e validação de API

Esta regra define padrões para componentes de frontend:

Ao trabalhar no diretório components:

• Sempre usa Tailwind para estilização
• Usa Framer Motion para animações
• Segue as convenções de nomeação de componentes

Esta regra aplica validação para endpoints de API:

No diretório api:

• Usa zod para toda a validação
• Define tipos de retorno com schemas do zod
• Exporta tipos gerados a partir dos schemas

Modelos para serviços Express e componentes React

Esta regra fornece um template para serviços Express:

Usa este template ao criar um serviço Express:

• Segue princípios RESTful
• Inclui middleware de tratamento de erros
• Configura logging adequado

@express-service-template.ts

Esta regra define a estrutura de componentes React:

Componentes React devem seguir este layout:

• Interface de Props no topo
• Componente como named export
• Estilos no final

@component-template.tsx

Automatizando fluxos de trabalho de desenvolvimento e geração de documentação

Esta regra automatiza a análise do app:

Quando pedirem para analisar o app:

1. Roda o servidor de dev com npm run dev
2. Busca os logs do console
3. Sugere melhorias de performance

Esta regra ajuda a gerar documentação:

Ajuda a rascunhar documentação:

• Extraindo comentários do código
• Analisando README.md
• Gerando documentação em Markdown

Adicionando uma nova configuração no Cursor

Primeiro cria uma propriedade para alternar em @reactiveStorageTypes.ts.

Adiciona o valor padrão em INIT_APPLICATION_USER_PERSISTENT_STORAGE em @reactiveStorageService.tsx.

Para recursos beta, adiciona o toggle em @settingsBetaTab.tsx, caso contrário, adiciona em @settingsGeneralTab.tsx. Toggles podem ser adicionados como <SettingsSubSection> para checkboxes gerais. Dá uma olhada no restante do arquivo para exemplos.

<SettingsSubSection
				label="Your feature name"
				description="Your feature description"
				value={
					vsContext.reactiveStorageService.applicationUserPersistentStorage
						.myNewProperty ?? false
				}
				onChange={(newVal) => {
					vsContext.reactiveStorageService.setApplicationUserPersistentStorage(
						'myNewProperty',
						newVal
					);
				}}
			/>

Pra usar no app, importa o reactiveStorageService e usa a propriedade:

const flagIsEnabled = vsContext.reactiveStorageService.applicationUserPersistentStorage.myNewProperty

Muitos exemplos estão disponíveis de diversos providers e frameworks. Regras contribuídas pela comunidade podem ser encontradas em coleções e repositórios colaborativos online.

AGENTS.md

AGENTS.md é um arquivo Markdown simples para definir instruções de agentes. Coloca ele na raiz do teu projeto como alternativa a .cursor/rules para casos de uso simples.

Diferente das Regras do Projeto, AGENTS.md é um arquivo Markdown comum, sem metadados nem configurações complexas. É perfeito pra projetos que precisam de instruções simples e legíveis, sem a sobrecarga de regras estruturadas.

# Project Instructions

## Code Style
- Use TypeScript for all new files
- Prefer functional components in React
- Use snake_case for database columns

## Architecture
- Follow the repository pattern
- Keep business logic in service layers

Limitações atuais

• Somente no nível raiz: AGENTS.md deve ficar na raiz do teu projeto (v1.5)
• Sem escopo: As instruções se aplicam globalmente ao teu projeto
• Arquivo único: Diferente de .cursor/rules, tu não pode dividir as instruções em vários arquivos

Suporte a AGENTS.md aninhado em subdiretórios tá planejado pra v1.6.

Regras do usuário

As regras do usuário são preferências globais definidas em Cursor Settings → Rules que se aplicam a todos os projetos. São texto simples e perfeitas para definir o estilo de comunicação preferido ou convenções de código:

Please reply in a concise style. Avoid unnecessary repetition or filler language.

.cursorrules (Legado)

O arquivo .cursorrules na raiz do teu projeto ainda é compatível, mas será descontinuado. Recomendamos migrar para Project Rules para ter mais controle, flexibilidade e visibilidade.

FAQ

Por que minha regra não está sendo aplicada?

Confere o tipo de regra. Para Agent Requested, garante que exista uma descrição definida. Para Auto Attached, garante que o padrão de arquivo corresponda aos arquivos referenciados.

Regras podem referenciar outras regras ou arquivos?

Sim. Usa @filename.ts para incluir arquivos no contexto da tua regra.

Posso criar uma regra a partir do chat?

Sim, gera regras de projeto a partir do chat usando o comando /Generate Cursor Rules. Se Memories estiver ativado, as memórias são geradas automaticamente.

As regras impactam o Cursor Tab ou outros recursos de IA?

Não. As regras se aplicam apenas ao Agent e ao Inline Edit.