Pular para o conteúdo principal

Uso Efetivo das Regras do Cursor: Melhores Práticas e Erros Comuns

À medida que o Cursor evolui, entender como implementar e gerenciar corretamente as regras torna-se cada vez mais importante. Este guia ajudará você a evitar erros comuns e otimizar a configuração das regras para uma melhor assistência de IA.

Pontos-Chave​

  • Usar regras .mdc no diretório .cursor/rules para implementação moderna
  • Manter regras simples e focadas
  • Criar regras específicas para erros recorrentes de IA
  • Implementar regras de visibilidade para melhor monitoramento
  • Seguir convenções específicas do projeto

Implementação Moderna de Regras​

Migração de .cursorrules para .mdc​

O formato .cursorrules está sendo descontinuado em favor das regras .mdc. Aqui está como migrar:

  1. Identificar Regras Existentes
# Listar todos os arquivos .cursorrules
find . -name ".cursorrules"
  1. Converter Regras
# Formato antigo .cursorrules
USE_TYPESCRIPT=true
FOLLOW_STYLE_GUIDE=true

# Novo formato .mdc
rule "typescript_usage" {
  description = "Forçar o uso de TypeScript"
  when = "criando novos arquivos"
  then = "Usar TypeScript para todos os novos arquivos"
}

rule "style_guide" {
  description = "Seguir o guia de estilo do projeto"
  when = "escrevendo ou modificando código"
  then = "Aderir às diretrizes de estilo do projeto"
}
  1. Validar Migração
# Verificar se as regras .mdc estão sendo aplicadas
/rules status

Uso de Regras .mdc​

A abordagem atualmente recomendada é usar regras .mdc no diretório .cursor/rules. Embora os arquivos .cursorrules ainda funcionem, são considerados legados, e o formato moderno .mdc fornece melhor integração com as capacidades de IA do Cursor.

.cursor/
  rules/
    code-style.mdc
    documentation.mdc
    testing.mdc

Melhores Práticas para Estrutura de Regras​

  1. Manter Regras Simples e Focadas

    • Criar arquivos de regras separados para diferentes preocupações
    • Evitar combinar regras não relacionadas em um único arquivo
    • Usar nomes claros e descritivos para arquivos de regras

  2. Desenvolvimento Iterativo de Regras

    • Monitorar respostas de IA e identificar padrões
    • Criar novas regras quando erros repetidos forem notados
    • Refinar regras existentes com base no uso real

  3. Regras Específicas do Projeto

    • Alinhar regras com os padrões de codificação do projeto
    • Considerar requisitos específicos do framework
    • Documentar propósitos e expectativas das regras

Erros Comuns a Evitar​

  1. Complicar Demais as Regras

    • Não tentar lidar com muitos casos em uma única regra
    • Evitar lógica condicional complexa difícil de manter
    • Manter definições de regras claras e diretas

  2. Ignorar a Visibilidade das Regras

    • Habilitar regras de visibilidade para rastrear o que está sendo aplicado
    • Monitorar a eficácia das regras
    • Ajustar regras com base em padrões de uso reais

  3. Não Atualizar as Regras

    • Revisar e atualizar regras regularmente
    • Remover regras obsoletas ou desnecessárias
    • Manter regras alinhadas com a evolução do projeto

Melhores Práticas para Gestão de Regras​

  1. Organização

    .cursor/rules/
      style/
        formatting.mdc
        naming.mdc
      testing/
        unit-tests.mdc
        integration-tests.mdc
      documentation/
        comments.mdc
        api-docs.mdc

  2. Controle de Versão

    • Incluir regras no controle de versão
    • Documentar alterações de regras em mensagens de commit
    • Revisar alterações de regras durante code reviews

  3. Colaboração em Equipe

    • Compartilhar regras eficazes com membros da equipe
    • Estabelecer convenções de regras para toda a equipe
    • Documentar uso e expectativas das regras

Exemplos de Regras​

Regra de Estilo de Código​

# style/formatting.mdc
rule "consistent-formatting" {
  description = "Forçar formatação consistente de código"
  when = "formatando código"
  then = "Seguir guia de estilo do projeto:
    - Usar 2 espaços para indentação
    - Colocar chave de abertura na mesma linha
    - Adicionar espaços ao redor de operadores"
}

Regra de Documentação​

# documentation/comments.mdc
rule "function-documentation" {
  description = "Garantir documentação adequada de funções"
  when = "escrevendo ou modificando funções"
  then = "Incluir:
    - Propósito da função
    - Descrição dos parâmetros
    - Descrição do valor de retorno
    - Exemplos de uso quando complexo"
}

Regra de Testes​

# testing/unit-tests.mdc
rule "test-coverage" {
  description = "Manter padrões de cobertura de testes"
  when = "implementando novos recursos"
  then = "Criar testes unitários que:
    - Cubram todos os caminhos de código
    - Incluam casos limite
    - Sigam o padrão AAA
    - Usem nomes de teste significativos"
}

Regra de Tratamento de Erros​

# error-handling/exceptions.mdc
rule "error-handling" {
  description = "Padronizar tratamento de erros"
  when = "implementando tratamento de erros"
  then = "Seguir diretrizes de tratamento de erros:
    - Usar classes de erro personalizadas
    - Incluir contexto do erro
    - Registrar detalhes apropriados
    - Manter cadeia de erros"
}

Depuração e Validação de Regras​

1. Teste de Regras​

# Testar regra específica
/rules test style/formatting.mdc

# Testar todas as regras
/rules test-all

2. Validação de Regras​

# Validar sintaxe da regra
/rules validate style/formatting.mdc

# Verificar conflitos de regras
/rules check-conflicts

3. Monitoramento de Regras​

# Monitorar aplicação de regras
/rules monitor

# Ver estatísticas de regras
/rules stats

Resolução de Problemas​

Se você encontrar problemas com a aplicação de regras:

  1. Verificar sintaxe e formato das regras
  2. Verificar localização e nome do arquivo de regras
  3. Garantir que o Cursor está carregando as regras
  4. Monitorar respostas de IA para aplicação de regras
  5. Usar ferramentas de depuração de regras
  6. Examinar logs de aplicação de regras

Problemas Comuns com Regras​

  1. Regra Não Aplicada

    • Verificar permissões do arquivo de regras
    • Revisar sintaxe das regras
    • Confirmar localização das regras
    • Revisar condições das regras

  2. Conflitos de Regras

    • Identificar regras em conflito
    • Estabelecer prioridades de regras
    • Resolver conflitos
    • Documentar resoluções

  3. Impacto no Desempenho

    • Monitorar tempo de processamento de regras
    • Otimizar regras complexas
    • Remover regras desnecessárias
    • Usar cache de regras

Conclusão​

O gerenciamento efetivo de regras é crucial para maximizar as capacidades de IA do Cursor. Seguindo estas melhores práticas e evitando erros comuns, você pode criar um ambiente de desenvolvimento mais eficiente e consistente.

Lembretes:

  • Manter regras simples e focadas
  • Monitorar e iterar sobre as regras
  • Manter boa organização
  • Compartilhar conhecimento com a equipe
  • Validar e depurar regras regularmente
  • Manter-se atualizado com as melhores práticas

Recursos Adicionais​