Regras do Cursor: Como escrever ficheiros .cursor/rules que realmente funcionam

Regras do Cursor: Como escrever ficheiros .cursor/rules que realmente funcionam

Todos os utilizadores do Cursor deparam-se com o mesmo obstáculo. A IA gera código que tecnicamente funciona, mas ignora as convenções do seu projeto, utiliza caminhos de importação errados, padrões desatualizados e componentes estruturados de forma totalmente diferente do resto da sua base de código. As regras do Cursor resolvem este problema, fornecendo à IA um contexto persistente sobre como o seu projeto funciona.

O que são as Regras do Cursor e por que são importantes?

As regras do Cursor são ficheiros markdown que atuam como um prompt de sistema permanente, injetado antes de cada interação com a IA, seja chat, autocompletar ou geração de código. Pense nelas como documentos de integração para a IA. Em vez de corrigir os mesmos erros em cada sessão, escreve a instrução uma vez e ela mantém-se.

A abordagem antiga consistia num único ficheiro .cursorrules na raiz do projeto. Isso ainda funciona, mas está obsoleto. O sistema atual utiliza um diretório .cursor/rules/ com ficheiros .mdc (Markdown Cursor) individuais, cada um delimitado a situações específicas. Esta é uma configuração muito melhor, pois não está a amontoar todas as instruções num único ficheiro gigante; divide as regras por responsabilidade e o Cursor carrega apenas as relevantes para o que está a fazer no momento.

Se já trabalhou com engenharia de contexto para ferramentas de IA, o conceito é familiar: um melhor contexto de entrada produz resultados drasticamente melhores. As regras são engenharia de contexto aplicada a todo o seu fluxo de trabalho de desenvolvimento.

Configurar o seu primeiro ficheiro de regras

Crie o diretório .cursor/rules/ na raiz do seu projeto:

mkdir -p .cursor/rules

Cada regra é um ficheiro .mdc com um frontmatter YAML seguido de conteúdo markdown. Eis a estrutura básica:

---
description: "When this rule should apply"
globs: ["src/components/**/*.tsx"]
alwaysApply: false
---

Your instructions go here in plain markdown.

Três campos do frontmatter controlam tudo:

Também pode criar regras através do próprio Cursor: digite /create-rule no chat e descreva o que pretende. No entanto, escrevê-las manualmente dá-lhe mais controlo.

Os quatro tipos de regras explicados

A forma como uma regra é ativada depende da sua configuração no frontmatter. Existem quatro modos e escolher o certo é crucial para o seu orçamento da janela de contexto.

Aplicar Sempre (Always Apply)

---
alwaysApply: true
---

Carregado em cada único pedido à IA. Utilize isto com moderação, para fundamentos abrangentes do projeto, como a declaração da sua stack tecnológica ou convenções críticas que se aplicam em todo o lado. Cada regra sempre ativa consome tokens de cada interação, seja relevante ou não.

Anexação Automática (Baseada em Glob)

---
globs: ["src/api/**/*.ts", "src/routes/**/*.ts"]
alwaysApply: false
---

Ativa-se apenas quando está a editar ficheiros que correspondem aos padrões glob. Este é o tipo de regra mais utilizado. As suas convenções de componentes React são carregadas quando está em ficheiros de componentes, os seus padrões de API são carregados quando está em handlers de rotas e as suas regras de teste são carregadas quando está a escrever testes.

Solicitado pelo Agente (Inteligente)

---
description: "Database migration patterns using Drizzle ORM"
alwaysApply: false
---

Sem globs, sem aplicação sempre ativa, apenas uma descrição. O agente do Cursor lê a descrição e decide se a regra é relevante para a tarefa atual. Se lhe pedir para escrever uma migração, ele incorpora esta regra. Se estiver a estilizar um botão, ignora-a. Isto funciona surpreendentemente bem para regras que não mapeiam claramente para caminhos de ficheiros.

Manual

---
---

Sem campos de frontmatter definidos (ou frontmatter vazio). Estas regras só são ativadas quando as menciona explicitamente com @nome-da-regra no chat. Ideais para instruções importantes, mas raramente utilizadas, como listas de verificação de implementação ou guias de refatorização de que só precisa ocasionalmente.

Padrões Glob que realmente funcionam

Os globs determinam quais os ficheiros que ativam as regras de anexação automática. Se os configurar mal, as suas regras nunca serão acionadas ou serão acionadas em todo o lado. Eis o que funciona:

# All TypeScript files in src
globs: ["src/**/*.ts", "src/**/*.tsx"]

# Only component files
globs: ["**/components/**/*.tsx"]

# Python files, excluding tests
globs: ["**/*.py", "!**/test_*.py"]

# Multiple specific directories
globs: ["src/api/**", "src/services/**"]

Algumas armadilhas comuns na utilização real:

• src/* corresponde apenas a um nível de diretório. Quase sempre quererá src/**/* para correspondência recursiva.
• *.js não corresponderá a ficheiros .jsx ou .ts. Seja explícito quanto às extensões.
• Os globs devem ser uma lista YAML. A sintaxe de chaves como {src,lib}/**/*.ts pode falhar silenciosamente; opte por entradas de lista separadas.
• O prefixo ! exclui padrões, o que é útil para ignorar ficheiros gerados ou código legado.

Exemplos práticos de regras

É aqui que a teoria encontra a realidade. Estas são regras que pode integrar num projeto e ver imediatamente uma melhoria nos resultados da IA.

Regra Base do Projeto (Aplicar Sempre)

---
alwaysApply: true
---

# Project: Acme Dashboard

## Tech Stack
- Next.js 15 (App Router only — no Pages Router)
- TypeScript strict mode
- Tailwind CSS v4
- Drizzle ORM with PostgreSQL
- pnpm for package management

## Critical Conventions
- All components are React Server Components by default
- Use "use client" only when the component needs interactivity
- Import paths use @/ alias mapped to src/
- Error handling: wrap async operations in try/catch, never use .catch()
- No default exports except for pages and layouts

Mantenha isto abaixo de 30 linhas. É carregado com cada pedido, por isso cada palavra custa tokens.

Regra de Componente React (Anexação Automática)

---
description: "React component patterns and conventions"
globs: ["src/components/**/*.tsx", "src/app/**/*.tsx"]
alwaysApply: false
---

# React Component Rules

## Structure
Every component file follows this order:
1. Imports
2. Type definitions (Props interface)
3. Component function (named export)
4. Sub-components (if any)

## Patterns

Use named exports, not default:
- YES: `export function Button({ label }: ButtonProps)`
- NO: `export default function Button()`

For data fetching in Server Components:
```tsx
// Fetch diretamente no componente, sem useEffect
export async function UserProfile({ id }: { id: string }) {
  const user = await db.query.users.findFirst({
    where: eq(users.id, id)
  });
  return <div>{user.name}</div>;
}

Anti-Patterns (NEVER do these)

• No useEffect for data fetching in Server Components
• No CSS modules — use Tailwind exclusively
• No barrel exports (index.ts re-exports)
• No prop drilling beyond 2 levels — use context or composition

### Regra de API Python (Anexação Automática)

```yaml
---
description: "FastAPI endpoint conventions and patterns"
globs: ["src/api/**/*.py", "src/routes/**/*.py"]
alwaysApply: false
---

# FastAPI Conventions

## Endpoint Structure
- Use APIRouter for route grouping
- Type all request/response models with Pydantic v2
- Dependency injection for database sessions

## Pattern
```python
from fastapi import APIRouter, Depends, HTTPException
from sqlalchemy.ext.asyncio import AsyncSession

router = APIRouter(prefix="/users", tags=["users"])

@router.get("/{user_id}", response_model=UserResponse)
async def get_user(
    user_id: int,
    db: AsyncSession = Depends(get_db)
) -> UserResponse:
    user = await db.get(User, user_id)
    if not user:
        raise HTTPException(status_code=404, detail="User not found")
    return UserResponse.model_validate(user)

Error Handling

• Always use HTTPException, not raw Response objects
• Log errors with structlog before raising
• Return consistent error shapes: {"detail": "message"}

### Regra de Serviço Go (Anexação Automática)

```yaml
---
description: "Go service patterns and error handling"
globs: ["**/*.go", "!**/*_test.go"]
alwaysApply: false
---

# Go Conventions

## Error Handling
- Always handle errors immediately — no _ for error returns
- Wrap errors with fmt.Errorf("context: %w", err)
- Use sentinel errors for expected failure cases

## Project Layout
- cmd/ for entrypoints
- internal/ for private packages
- pkg/ for public libraries

## Pattern
```go
func (s *UserService) GetByID(ctx context.Context, id string) (*User, error) {
    user, err := s.repo.Find(ctx, id)
    if err != nil {
        if errors.Is(err, ErrNotFound) {
            return nil, fmt.Errorf("user %s: %w", id, ErrNotFound)
        }
        return nil, fmt.Errorf("fetching user %s: %w", id, err)
    }
    return user, nil
}

## Gerir o custo em tokens

Eis algo que a maioria dos guias do Cursor omite: cada regra que escreve custa tokens. Um projeto com 20 regras sempre ativas pode consumir **mais de 2.000 tokens por pedido** apenas em instruções, antes mesmo de a IA analisar o seu código.

Isto é importante porque o contexto de chat do Cursor é de aproximadamente 20.000 tokens no modo standard. Se as suas regras consumirem 25% disso, perdeu um quarto do "espaço de raciocínio" da IA para a sua pergunta real. Notará uma pior qualidade nos resultados à medida que as regras se acumulam, especialmente em conversas mais longas.

Três princípios mantêm o seu orçamento de tokens saudável:

**1. Utilize agressivamente regras de anexação automática e solicitadas pelo agente.** Apenas a declaração da stack do seu projeto deve estar sempre ativa. Tudo o resto deve ser carregado condicionalmente. Aquela regra de componente React? Não precisa de estar em contexto quando está a escrever migrações SQL.

**2. Escreva de forma densa, não prolixa.** Substitua "É fortemente recomendado que os desenvolvedores usem interfaces TypeScript em vez de aliases de tipo ao definir contratos de API pública" por "Prefira `interface` em vez de `type` para APIs públicas." A IA não precisa de persuasão, precisa de instruções.

**3. Aplique a Regra dos Três.** Só codifique um padrão como regra depois de a IA errar três vezes. Se o Cursor já lidar corretamente com as suas convenções de nomenclatura sem uma regra, ignore a regra. Cada regra desnecessária é contexto desperdiçado.

Pode monitorizar a utilização de tokens na barra de estado na parte inferior do painel de chat do Cursor. Fique atento quando se aproximar dos 100%; esse é o sinal para podar.

## Organizar regras para um projeto real

Um projeto de produção通常需要 5-8 ficheiros de regras. Eis uma estrutura que funciona bem:

```text
.cursor/rules/
  base.mdc            # Tech stack, always-apply (< 30 lines)
  components.mdc      # React/Vue patterns, glob to component dirs
  api.mdc             # Backend conventions, glob to API dirs
  database.mdc        # ORM patterns, glob to models/migrations
  testing.mdc         # Test conventions, glob to test files
  deployment.mdc      # CI/CD patterns, manual trigger
  personal.mdc        # Your preferences (gitignored)

Faça commit de tudo para o controlo de versões, exceto personal.mdc. Desta forma, toda a sua equipa obtém o mesmo comportamento da IA, que é o objetivo principal. Como diz um utilizador do fórum do Cursor, boas regras significam que "aceita mais sugestões tal como estão, com resultados que correspondem às suas convenções à primeira tentativa."

Se estiver a trabalhar com outras ferramentas de codificação com IA além do Cursor, os conceitos transferem-se diretamente. O Claude Code usa CLAUDE.md, o GitHub Copilot tem ficheiros de instruções e o Windsurf tem o seu próprio formato, mas o princípio subjacente é idêntico.

Como funciona a precedência das regras

Quando múltiplas regras se aplicam ao mesmo ficheiro, o Cursor segue uma hierarquia clara:

As regras da equipa estão disponíveis nos planos Team e Enterprise. São definidas no dashboard do Cursor pelos administradores e aplicadas em toda a organização; os programadores individuais não as podem desativar.

Dentro das regras do projeto, se duas regras se aplicarem ao mesmo ficheiro e entrarem em conflito, o comportamento não está estritamente definido. Na prática, as regras carregadas mais tarde tendem a ter precedência. Numerar os seus ficheiros (001-base.mdc, 002-components.mdc) dá-lhe uma ordenação previsível.

Erros comuns e como corrigi-los

Depois de ler dezenas de tópicos da comunidade e testar regras em vários projetos, estes são os erros que mais frequentemente atrapalham as pessoas:

Escrever regras demasiado vagas. "Escreva código limpo" não diz nada à IA. "Use exportações nomeadas, não exportações padrão. Estruture os componentes como: imports, tipos, função, sub-componentes" dá-lhe algo acionável.

Tornar tudo sempre aplicável. O seu primeiro instinto é definir alwaysApply: true em cada regra. Resista a isso. Audite as suas regras trimestralmente; se tiver mais de 2-3 regras sempre ativas, provavelmente está a desperdiçar tokens.

Esquecer-se de testar as regras. Depois de escrever uma regra, abra um ficheiro relevante e peça ao Cursor para gerar algo que deva seguir a regra. Se não o fizer, o seu padrão glob pode estar errado ou a instrução não é suficientemente clara.

Não documentar anti-padrões. Dizer à IA o que fazer é metade do trabalho. Dizer-lhe o que não fazer é a outra metade. Inclua uma secção "NUNCA faça isto" em cada regra com exemplos explícitos da abordagem errada.

Ignorar o salvamento de regras na interface. Um bug conhecido faz com que as edições de regras desapareçam. Se as alterações desaparecerem, feche completamente o Cursor, selecione "Substituir" no pop-up de alterações não guardadas e reabra.

Regras do Cursor vs CLAUDE.md vs AGENTS.md

O Cursor não é a única ferramenta que utiliza ficheiros de instruções. Eis como os formatos se comparam para quem trabalha com múltiplos assistentes de codificação com IA:

A vantagem do Cursor é a granularidade. CLAUDE.md e AGENTS.md são mais simples, carregam tudo sempre. O Cursor permite-lhe carregar as regras certas no momento certo, o que é importante quando o seu conjunto de instruções cresce para além de algumas centenas de linhas.

Para uma análise mais profunda de como o contexto molda os resultados da IA nestas ferramentas, o nosso guia de engenharia de contexto detalha os princípios que se aplicam independentemente do editor que utilizar.

Perguntas Frequentes

O .cursorrules está obsoleto?

Sim. O único ficheiro .cursorrules na raiz do seu projeto ainda funciona, mas o Cursor recomenda a migração para ficheiros .cursor/rules/*.mdc. O novo formato suporta padrões glob, carregamento condicional e melhor organização. Migre dividindo o seu ficheiro monolítico em regras focadas.

Que extensão de ficheiro devo usar, .mdc ou .md?

Use .mdc para ficheiros que incluem frontmatter YAML (description, globs, alwaysApply). Ficheiros .md simples também funcionam no diretório de regras, mas não suportam os metadados do frontmatter que permitem o carregamento condicional.

Quantas regras deve ter um projeto?

Cinco a oito é o número ideal para a maioria dos projetos. Uma regra base sempre ativa, três a quatro regras de anexação automática delimitadas por tipo de ficheiro e uma ou duas regras manuais para tarefas especiais. Mais de 10 regras geralmente significa que algumas podem ser consolidadas ou removidas.

As regras do Cursor afetam o autocompletar e a conclusão com Tab?

As regras aplicam-se ao chat e às interações com o agente. As Regras do Utilizador não se aplicam a edições inline (Cmd/Ctrl+K) e as regras geralmente não impactam as sugestões de autocompletar do Cursor Tab. São mais eficazes em sessões de chat e Composer.

Posso partilhar regras entre vários projetos?

Sim, através da funcionalidade Remote Rules do Cursor. Vá a Cursor Settings > Rules, Commands, selecione "Remote Rule (GitHub)" e cole o URL de um repositório. As regras sincronizam automaticamente quando o repositório de origem é atualizado. Alternativamente, mantenha um repositório de regras partilhado e crie links simbólicos para cada projeto.

Qual é o comprimento máximo recomendado para uma regra?

A documentação do Cursor sugere manter as regras individuais abaixo de 500 linhas. Na prática, procure manter menos de 100 linhas por regra. Regras mais curtas são mais fáceis de manter e custam menos tokens. Se uma regra exceder 150 linhas, divida-a em duas regras focadas.

As regras funcionam com todos os modelos de IA no Cursor?

As regras funcionam com todos os modelos suportados pelo Cursor, Claude, GPT-4o, Gemini e outros. As regras são injetadas como contexto a nível do sistema, independentemente do modelo selecionado. O comportamento do modelo pode variar, mas as regras em si são agnósticas ao modelo.

Como depurar uma regra que não está a funcionar?

Primeiro, verifique se o padrão glob corresponde ao seu ficheiro; abra o ficheiro e verifique se a regra aparece no painel de contexto. Segundo, teste com uma pergunta direta que deva acionar a regra. Terceiro, tente definir temporariamente alwaysApply: true para confirmar que o conteúdo da regra funciona. Se funcionar, o problema está no seu padrão glob.

Devo fazer commit de .cursor/rules para o git?

Absolutamente. O objetivo principal das regras do projeto é a consistência em toda a equipa. Faça commit de tudo em .cursor/rules/ exceto ficheiros de preferências pessoais. Adicione um personal.mdc ao .gitignore para definições individuais que não se devem aplicar a todos.

Posso usar regras do Cursor juntamente com servidores MCP?

Sim, e complementam-se bem. As regras definem como a IA deve escrever código, enquanto os servidores MCP dão à IA acesso a ferramentas e dados externos. Uma regra pode dizer "use sempre o nosso cliente de API interno", enquanto um servidor MCP permite à IA consultar realmente essa API durante o desenvolvimento.

Se as funcionalidades de IA estão no seu roteiro, essa é a nossa especialidade: a equipa de integração de IA da Techsy leva sistemas LLM do protótipo à produção. Quer uma segunda opinião sobre a sua stack? Obtenha uma consulta gratuita.

Fontes

• Documentação das Regras do Cursor
• Trigger.dev, Como escrever ótimas regras do Cursor
• Fórum do Cursor, Melhores práticas e resolução de problemas de regras MDC
• Peakvance, Guia das Regras do Cursor: Custo em Tokens
• awesome-cursor-rules-mdc no GitHub