Regras de Cursor para produção: Next.js, React TypeScript e FastAPI [Guia 2026]

Os assistentes de código por IA tendem a replicar convenções obsoletas caso não existam limites bem definidos. Em projetos web modernos, o Cursor sugere com frequência métodos ultrapassados do antigo Pages router do Next.js, introduz tipos any nos componentes React ou escreve consultas síncronas bloqueantes no interior de rotas assíncronas em Python FastAPI.

As regras do Cursor fornecem orientações para reduzir estes comportamentos antes de chegarem ao registo de git. Os ficheiros em .cursor/rules/ acrescentam instruções ao contexto do modelo; não garantem o seu cumprimento nem eliminam erros ou alucinações. É necessário rever as alterações e executar as verificações do projeto.

A 22 de outubro de 2026, a documentação de modelos do Cursor inclui Opus 5.5, Sonnet 5.5, Gemini 4 Argon e GPT 5.6 Sol, entre outros. O acesso depende do plano e das definições; as regras não disponibilizam modelos adicionais.

Apresentamos de seguida modelos de regras validados para Next.js, React TypeScript e FastAPI em 2026, bem como um guia prático para estruturar regras modulares.

Ficheiro raiz .cursorrules versus regras modulares .cursor/rules/*.mdc

Resposta direta: O Cursor suporta ficheiros modulares .cursor/rules/*.mdc e continua a suportar o ficheiro antigo .cursorrules. Segundo a documentação das regras, com alwaysApply: false, os padrões glob associam instruções quando um ficheiro correspondente entra no contexto, como src/app/**/*.tsx para Next.js ou backend/**/*.py para FastAPI. Isto ajuda a selecionar instruções pertinentes, mas exige rever os resultados.

Inicialmente o Cursor baseava-se num único ficheiro .cursorrules colocado na raiz do projeto. Embora simples de criar, este método obriga cada prompt a carregar instruções de todo o conjunto de tecnologias, desperdiçando tokens de contexto e gerando diretrizes contraditórias entre o frontend e o backend.

As versões atuais do Cursor suportam regras modulares no formato .cursor/rules/*.mdc. Cada ficheiro .mdc combina um cabeçalho YAML com orientações técnicas em Markdown:

---
description: Resumo conciso do âmbito da regra
globs: padrao/direcionado/a/ficheiros/**
alwaysApply: false
---

# As suas diretrizes técnicas aqui

Opções de YAML essenciais

• globs: um padrão de correspondência de ficheiros (como src/app/**/*.tsx ou backend/**/*.py). Com alwaysApply: false, associa a regra quando um ficheiro correspondente está no contexto.

• alwaysApply: definir como true apenas para regras transversais a todo o repositório (como normas de commit ou licenças). Manter como false para regras específicas de cada framework.

• description: explica a finalidade da regra, permitindo ao Cursor selecioná-la de forma automática em pesquisas com @.

Se pretende comparar a assistência de código no editor do Cursor com um agente autónomo em consola, consulte a nossa análise aprofundada de Claude Code vs Cursor.

1. Melhores regras de Cursor para Next.js (App Router)

Guarde este ficheiro como .cursor/rules/nextjs.mdc. Orienta o modelo sobre as convenções do App Router, a separação dos dados do servidor e o carregamento de dados em Server Components; verifique as alterações antes de as aceitar.

---
description: Normas para Next.js App Router e Server Components
globs: src/app/**/*.{ts,tsx},app/**/*.{ts,tsx}
alwaysApply: false
---

# Regras de arquitetura no Next.js

## Separação entre Server e Client Components
- Utilizar React Server Components (RSC) por defeito. Apenas adicionar "use client" caso o componente exija useState, useEffect, manipuladores de eventos do navegador ou APIs de janela.
- Manter os Client Components nas folhas da árvore de renderização. Passar dados a partir dos Server Components através de propriedades serializáveis.
- Nunca importar bibliotecas exclusivas de servidor (clientes de base de dados, variáveis de ambiente privadas) em Client Components.

## Obtenção de dados e mutações
- Obter dados diretamente nos Server Components com async/await. Evitar o carregamento de dados através de useEffect.
- Recorrer a Server Actions do Next.js para submissões de formulários e alterações de estado. Agrupar as ações no componente ou em `actions.ts` com a diretiva "use server" no topo do ficheiro.
- Validar obrigatoriamente todos os parâmetros das Server Actions com esquemas Zod antes de efetuar consultas à base de dados.
- Revalidar rotas em cache após uma mutação com sucesso através de `revalidatePath()` ou `revalidateTag()`.

## Encaminhamento e navegação
- Utilizar `next/link` para navegação interna; nunca utilizar tags HTML `<a>` para ligações locais.
- Obter parâmetros de pesquisa através de propriedades de página ou `useSearchParams()`. Proteger com limites Suspense os componentes que processem parâmetros de consulta.

2. Melhores regras de Cursor para React e TypeScript

Guarde este ficheiro como .cursor/rules/react-typescript.mdc. Solicita tipos precisos, exportações nomeadas e padrões consistentes de interface; verifique o cumprimento através de revisão e ferramentas de análise.

---
description: Normas para React e TypeScript
globs: **/*.{ts,tsx}
alwaysApply: false
---

# Diretrizes para React e TypeScript

## Rigor de tipificação no TypeScript
- Nunca utilizar o tipo `any`. Recorrer a `unknown` para valores arbitrários e aplicar validações com type guards.
- Preferir `interface` para estruturas de objetos e propriedades de componentes. Usar `type` para uniões e tipos derivados.
- Assegurar tipos de retorno explícitos em todas as funções exportadas para outros módulos.
- Evitar asserções não nulas (`!`). Tratar valores indefinidos ou nulos através de encadeamento opcional (`?.`) ou valores padrão.

## Arquitetura de componentes
- Utilizar exclusivamente exportações nomeadas: `export function UserProfile(...)`. Evitar `export default`.
- Definir a interface de propriedades imediatamente acima do componente com o padrão `<NomeComponente>Props`.
- Desestruturar as propriedades na assinatura: `function Button({ variant = "primary", children }: ButtonProps)`.
- Extrair lógica complexa para hooks personalizados com o prefixo `use`.

## Estilos e acessibilidade
- Aplicar classes utilitárias do Tailwind CSS diretamente no código. Evitar estilos em linha `style={{ ... }}`.
- Unir classes condicionais através de funções utilitárias como `cn()` (clsx + tailwind-merge).
- Garantir a acessibilidade em todos os controlos interativos (`aria-label`, navegação por teclado).

3. Melhores regras de Cursor para Python e FastAPI

Guarde este ficheiro como .cursor/rules/fastapi.mdc. Solicita rotas assíncronas não bloqueantes, modelos Pydantic v2 e injeção de dependências controlada; valide o resultado com testes.

---
description: Normas para Python FastAPI e Pydantic
globs: **/*.py,backend/**/*.py,api/**/*.py
alwaysApply: false
---

# Regras de desenvolvimento em FastAPI

## Manipuladores de rota assíncronos
- Definir obrigatoriamente qualquer ponto de entrada com operações de I/O através de `async def`.
- Nunca utilizar operações síncronas bloqueantes (tais como `requests.get()`, `time.sleep()` ou conectores SQL tradicionais) dentro de rotas assíncronas.
- Utilizar `httpx.AsyncClient` para chamadas HTTP externas e conectores assíncronos para a base de dados.

## Modelos Pydantic v2
- Separar claramente cargas úteis de entrada, respostas e estruturas de base de dados em modelos distintos.
- Atribuir nomes elucidativos: `UserCreateRequest`, `UserUpdatePayload`, `UserResponse`.
- Adicionar sempre `from_attributes = True` na configuração `model_config` ao manipular instâncias de ORM.
- Utilizar `Field()` com restrições explícitas (`min_length`, `gt`, `le`) e descrições com exemplos.

## Injeção de dependências e segurança
- Fornecer sessões de base de dados e dados de autenticação mediante a construção `Depends()` do FastAPI.
- Encapsular as operações de base de dados em gestores de contexto assíncronos para salvaguardar o fecho de ligações em caso de exceção.
- Disparar exceções através de `HTTPException` com códigos HTTP explícitos em vez de devolver dicionários de erro genéricos.

Sincronização de regras do Cursor com agentes de terminal

Se na sua empresa também utilizam o Claude Code para refatorações profundas ou baterias de testes em consola, convém alinhar as orientações do repositório. Enquanto o Cursor lê os ficheiros .cursor/rules/*.mdc, o Claude Code consulta o CLAUDE.md e pacotes modulares de skills.

Descubra como estruturar processos automatizados de teste e revisão no nosso artigo sobre as melhores skills do Claude Code para programadores, ou conheça o repositório completo de skills técnicas verificadas.

Como validar e testar as regras do Cursor

Após guardar os ficheiros na pasta .cursor/rules/, verifique a sua ativação correta:

1. Testar a correspondência dos ficheiros: abra um ficheiro abrangido (como src/app/page.tsx).

2. Abrir o chat do Cursor (Cmd+L): confirme a etiqueta de contexto na barra inferior. O ficheiro nextjs.mdc deve surgir entre as regras ativas do projeto.

3. Impor uma regra manualmente: introduza @ no chat, selecione Rules e escolha o ficheiro pretendido.

4. Verificar no Composer (Cmd+I): solicite ao Cursor a criação de um novo componente e certifique-se de que o diff gerado respeita as convenções estabelecidas (exportações nomeadas e tipagem rigorosa).

Cuidados a ter com regras do Cursor

Para manter o Cursor rápido e com consumo de tokens controlado, evite estes quatro erros habituais:

1. Excesso de instruções: evite transpor todo o guia de estilos da empresa para um só ficheiro. Mantenha cada .mdc abaixo das 80 linhas e com diretrizes operacionais diretas.

2. Âmbito mal configurado: verifique globs e alwaysApply; uma regra sem globs pode ser incluída através de outros modos de seleção ou manualmente.

3. Instruções divergentes: evite incoerências entre o ficheiro .cursorrules central e as regras por módulo para prevenir respostas inconsistentes.

4. Orientações genéricas: troque recomendações subjetivas como "escreve código limpo" por métricas mensuráveis como "limitar funções a 40 linhas".

Resumo e referências

Ao criar ficheiros modulares .cursor/rules/*.mdc, converte o Cursor num parceiro técnico especializado, estritamente ajustado aos padrões de produção da sua organização.