Melhores Práticas e Solução de Problemas de Regras MDC no Cursor

As regras MDC (Markdown Configuration) são a forma poderosa do Cursor de impor padrões de codificação, convenções de projeto e diretrizes de comportamento de IA. Quando configuradas corretamente, melhoram drasticamente a qualidade e consistência do código. Este guia aborda as melhores práticas para criar, organizar e solucionar problemas de regras MDC.

O que são Regras MDC?

As regras MDC são arquivos Markdown com front matter YAML que dizem ao Cursor como se comportar ao trabalhar com arquivos específicos ou em contextos específicos. Elas podem:

• Impor padrões de codificação
• Definir padrões de arquitetura de projeto
• Especificar requisitos de documentação
• Controlar o comportamento da IA para tipos de arquivo específicos

Requisitos de Formato de Arquivo

As regras MDC devem seguir exatamente este formato:

---
description: 'Descrição da regra aqui'
globs: ['src/**/*.ts', 'tests/**/*.ts']
alwaysApply: false
---

# Título da Regra

Seu conteúdo da regra aqui...

## Diretrizes Específicas

- Diretriz 1
- Diretriz 2

Requisitos Críticos

Requisito	Detalhes
Extensão	Deve ser .mdc (não .md)
Front matter	Deve usar formato YAML entre delimitadores ---
Localização	Deve estar no diretório .cursor/rules/
globs	Array de padrões de arquivo aos quais esta regra se aplica
alwaysApply	Booleano - se aplica sem correspondência de arquivo

Convenção de Nomenclatura

Use um sistema de prefixo numerado para organização:

.cursor/rules/
  001-core-coding-standards.mdc
  002-typescript-conventions.mdc
  003-react-patterns.mdc
  100-api-design.mdc
  101-database-models.mdc
  200-testing-requirements.mdc
  201-documentation-rules.mdc

Sistema de Numeração

Intervalo	Categoria	Exemplo
001-099	Regras principais (aplicam-se a todos os arquivos)	Padrões de codificação, formatação
100-199	Regras de integração (domínios específicos)	API, banco de dados, autenticação
200-299	Regras de padrão/função	Testes, documentação
300-399	Específicas de tecnologia	React, Vue, Angular

Escrevendo Regras Eficazes

Seja Específico e Acionável

Ruim:

Escreva bom código.

Bom:

## Tratamento de Erros

Todas as funções assíncronas devem usar blocos try/catch:

```typescript
async function fetchUser(id: string): Promise<User> {
  try {
    const response = await api.get(`/users/${id}`);
    return response.data;
  } catch (error) {
    logger.error(`Failed to fetch user ${id}`, error);
    throw new UserNotFoundError(id);
  }
}

### Inclua Exemplos

Sempre mostre exemplos corretos e incorretos:

```markdown
## Gerenciamento de Estado

✅ FAÇA: Use React Query para estado do servidor
```typescript
const { data, isLoading } = useQuery({
  queryKey: ['user', userId],
  queryFn: () => fetchUser(userId)
});

❌ NÃO FAÇA: Use useEffect para busca de dados

// Evite este padrão
useEffect(() => {
  fetchUser(userId).then(setUser);
}, [userId]);

### Use Padrões Glob Efetivamente

```yaml
# Aplicar a todos os arquivos TypeScript
globs: ['**/*.ts', '**/*.tsx']

# Aplicar apenas ao código backend
globs: ['src/server/**/*.ts', 'src/api/**/*.ts']

# Aplicar a arquivos de teste específicos
globs: ['**/*.test.ts', '**/*.spec.ts']

# Excluir certos arquivos
globs: ['src/**/*.ts', '!src/generated/**']

Categorias Comuns de Regras

1. Regras de Estilo de Código

---
description: 'Impor estilo de código consistente'
globs: ['src/**/*.ts', 'src/**/*.tsx']
alwaysApply: true
---

# Padrões de Estilo de Código

## Importações
- Agrupar importações: React, libs externas, módulos internos, tipos
- Usar importações absolutas para módulos src/
- Ordenar alfabeticamente dentro dos grupos

## Nomenclatura
- Componentes: PascalCase (UserProfile)
- Hooks: camelCase começando com 'use' (useAuth)
- Constantes: UPPER_SNAKE_CASE
- Arquivos: kebab-case (user-profile.tsx)

2. Regras de Arquitetura

---
description: 'Impor padrões de arquitetura limpa'
globs: ['src/**/*.ts']
alwaysApply: false
---

# Diretrizes de Arquitetura

## Dependências de Camada
- Camada de domínio: Sem dependências externas
- Camada de aplicação: Depende apenas do domínio
- Camada de infraestrutura: Depende da aplicação

## Organização de Arquivos

src/ domain/ # Lógica de negócios, entidades application/ # Casos de uso, DTOs infrastructure/ # DB, API, serviços externos presentation/ # Componentes de UI

3. Regras de Teste

---
description: 'Requisitos e padrões de teste'
globs: ['**/*.test.ts', '**/*.test.tsx']
alwaysApply: true
---

# Padrões de Teste

## Testes Obrigatórios
- Testes unitários para todas as funções utilitárias
- Testes de componente para todos os componentes React
- Testes de integração para endpoints de API
- Testes E2E para fluxos críticos do usuário

## Estrutura de Teste
Siga o padrão AAA:
1. Arrange: Configure dados de teste e mocks
2. Act: Execute a função sendo testada
3. Assert: Verifique os resultados

Solução de Problemas Comuns

Problema 1: Alterações Não Sendo Salvas

Sintoma: Você edita um arquivo .mdc, salva, mas o Cursor não aplica as alterações.

Solução:

1. Feche completamente o Cursor (não apenas a janela - saia da aplicação)
2. Reabra o Cursor
3. As alterações devem ser aplicadas agora

Por que isso acontece: As regras MDC são armazenadas em cache quando o Cursor inicia. Elas não recarregam dinamicamente.

Problema 2: Regras Não Sendo Aplicadas

Sintoma: O Cursor ignora suas regras ao editar arquivos.

Lista de Verificação:

• A extensão do arquivo é .mdc (não .md)
• O arquivo está no diretório .cursor/rules/
• O front matter tem sintaxe YAML válida
• O padrão globs corresponde aos seus arquivos alvo
• Sem erros de sintaxe no conteúdo Markdown

Comando de depuração:

# Verificar se o Cursor reconhece suas regras
ls -la .cursor/rules/
# Verificar extensões de arquivo
file .cursor/rules/*

Problema 3: Regras Conflitantes

Sintoma: Múltiplas regras dão instruções contraditórias.

Ordem de Resolução:

1. Regras com padrões glob mais específicos têm precedência
2. Regras com alwaysApply: true são avaliadas primeiro
3. Regras posteriores em ordem alfabética sobrescrevem as anteriores

Melhor prática: Use o campo priority (se suportado):

---
description: 'Regra de alta prioridade'
globs: ['src/**/*.ts']
priority: 100
---

Problema 4: Regras Muito Longas

Sintoma: O Cursor não segue todas as instruções em uma regra longa.

Solução: Divida em múltiplas regras focadas:

.cursor/rules/
  001-general-style.mdc       # Diretrizes curtas e gerais
  002-error-handling.mdc      # Específico para tratamento de erros
  003-performance.mdc         # Otimizações de desempenho

Técnicas Avançadas

Regras Condicionais

Use globs para aplicar diferentes regras a diferentes partes da sua base de código:

# Regras de frontend
globs: ['src/components/**/*.tsx', 'src/pages/**/*.tsx']
---
Use o padrão React hooks. Prefira componentes funcionais.

# Regras de backend
globs: ['src/server/**/*.ts', 'src/api/**/*.ts']
---
Use injeção de dependência. Siga os princípios SOLID.

Herança de Regras

Crie uma regra base e estenda-a:

---
description: 'Padrões TypeScript base'
globs: ['**/*.ts', '**/*.tsx']
alwaysApply: true
---

# Regras TypeScript Base

- Use configuração TypeScript estrita
- Sem tipos `any` sem comentário justificativo
- Prefira `interface` em vez de `type` para formas de objetos

---
description: 'Extensões específicas de React'
globs: ['src/**/*.tsx']
alwaysApply: false
---

# Regras React

Além das regras TypeScript base:
- Use componentes funcionais com hooks
- Interfaces de props devem ser exportadas
- Use React.FC com moderação (prefira tipagem explícita de props)

Regras Dinâmicas com Variáveis

Algumas configurações avançadas suportam variáveis de modelo:

---
description: 'Convenções específicas do projeto'
globs: ['**/*.ts']
---

# Convenções do Projeto

## URL Base da API
Use: {{API_BASE_URL}}

## Autenticação
Cabeçalho de token: {{AUTH_HEADER_NAME}}

Referência Rápida: Modelo de Regra MDC

---
description: ''
globs: ['']
alwaysApply: false
---

# Título

## Seção 1
- Diretriz 1
- Diretriz 2

## Seção 2
```typescript
// Exemplo de código

Referências

• Link para documentação

## Recursos Relacionados

- [Usando Regras do Cursor Efetivamente](using-cursor-rules-effectively.mdx)
- [Melhores Práticas para Regras do Cursor](best-practices-for-cursor-rules.mdx)
- [Guia de Configuração do CursorRules](cursorrules-setup-guide.mdx)