Como configurar o Cursor AI para programar de verdade (e não só autocompletar)

O Cursor virou o editor preferido de muita gente que programa com IA, e por um bom motivo: ele entende o seu projeto inteiro, não só o arquivo aberto. Mas tem um detalhe que quase ninguém conta: instalado no padrão, ele te dá autocomplete turbinado — e só. O salto de produtividade real vem da configuração. Foi isso que aprendi depois de alguns meses usando ele em código de produção.

Este guia é a configuração que eu de fato uso. Nada de "revolucione seu fluxo": são ajustes concretos, com o porquê de cada um e com os erros que eu mesmo cometi pelo caminho.

1. Ensine o Cursor as regras do seu projeto

O maior erro é tratar o Cursor como um chatbot genérico. Ele aceita um arquivo de regras (Cursor Rules) na raiz do projeto onde você descreve as convenções: linguagem, framework, estilo de código, o que nunca fazer. Sem isso, ele sugere código no "estilo médio da internet", que raramente combina com o seu.

Um bom arquivo de regras responde três perguntas: qual a stack, quais os padrões obrigatórios e o que está proibido. Na prática, o meu tem mais ou menos esta cara:

• Stack: "TypeScript estrito, React 19, Tailwind v4. Sem bibliotecas de estado — use os hooks nativos."
• Obrigatório: "Tipos explícitos em toda função exportada. Nada de any, nem as any pra calar o compilador."
• Proibido: "Não instale dependência nova sem justificar em uma frase. Não crie arquivo de configuração novo sem me perguntar."
• Estilo: "Comentário só quando o porquê não é óbvio. Não comente o que o código já diz."

Parece burocracia, mas é o ajuste com maior retorno de todos. Antes das regras, eu passava um bom tempo desfazendo importação de lodash pra coisa que o JavaScript já faz. Depois, isso simplesmente parou de acontecer. A regra é lida a cada requisição — você escreve uma vez e ela trabalha pra sempre.

Uma dica que demorei pra aprender: escreva as regras em forma de proibição, não de recomendação. "Prefira componentes pequenos" é ignorável. "Nenhum componente pode passar de 150 linhas — se passar, divida" é acionável. Modelos respondem muito melhor a limites concretos do que a conselhos.

2. Escolha o modelo certo para cada tarefa

O Cursor deixa você trocar de modelo. A tentação é deixar sempre no mais potente, mas isso é lento e caro. O que funciona:

• Autocomplete e edições pequenas: modelo rápido. Você quer resposta em milissegundos, não perfeição. Se o modelo demora mais do que você levaria pra digitar, ele deixou de ajudar.
• Refatoração e bugs difíceis: o modelo mais capaz. Aqui a qualidade do raciocínio vale a espera de alguns segundos.
• Explicar código legado: qualquer modelo intermediário resolve. Explicar é bem mais fácil que criar.
• Escrever testes: modelo forte, sempre. Teste ruim é pior que teste nenhum, porque dá falsa segurança.

A regra prática: use o modelo forte quando o custo de errar é alto (código que vai pra produção) e o rápido quando você só quer velocidade. E preste atenção no seu próprio comportamento — se você está esperando o modelo terminar pra continuar pensando, trocou produtividade por espera.

3. Domine o "Composer" para mudanças em vários arquivos

O autocomplete edita uma linha. O Composer edita o projeto. É a diferença entre "termina essa função" e "adicione autenticação a essas três rotas e atualize os testes". Quando você precisa de uma mudança que toca vários arquivos, é aí que o Cursor economiza horas de verdade.

O truque é ser específico sobre o escopo: diga quais arquivos ele pode tocar. Deixado solto, ele às vezes reescreve coisas que estavam certas. Comparando dois pedidos para a mesma tarefa:

• ❌ "Adicione validação no formulário." — ele mexe em cinco arquivos, inventa uma lib de validação e muda a estilização de quebra.
• ✅ "Em @ContactForm.tsx, valide e-mail e telefone antes do submit. Mostre o erro abaixo do campo usando a classe .field-error que já existe em @globals.css. Não mexa em nenhum outro arquivo." — ele faz exatamente isso.

Repare que o segundo pedido não é mais longo por capricho: ele carrega o arquivo-alvo, o padrão visual a reusar e a fronteira do que não pode ser tocado. Toda vez que a IA "fez coisa demais", quase sempre é porque essa fronteira não foi dita.

4. Alimente contexto com @ em vez de explicar tudo

Em vez de colar código no chat, use as referências com @: @arquivo, @pasta, a documentação da lib. Assim o modelo lê a fonte real, não a sua descrição da fonte — que sempre perde detalhe. Quanto mais o contexto vem de arquivos reais, menos ele inventa.

Isso resolve um problema específico e muito comum: a alucinação de API. O modelo foi treinado com a versão 4 da biblioteca, seu projeto usa a 6, e ele chama um método que não existe mais. Referenciar a documentação atual ou o próprio arquivo de tipos corta esse erro pela raiz. É a diferença entre o modelo lembrar e o modelo ler.

Cuidado com o excesso, porém. Jogar a pasta inteira como contexto piora o resultado: o modelo se distrai com o que não importa e a resposta fica mais genérica. Contexto é tempero, não ingrediente principal — três arquivos certos batem trinta arquivos aleatórios.

5. Revise sempre. Sem exceção.

Esta é a parte que separa quem acelera de quem se enrola. A IA escreve código plausível, não código correto. Ela erra com confiança: importa algo que não existe, assume uma versão de biblioteca, "conserta" um teste apagando a asserção.

Trate cada sugestão como um pull request de um colega júnior talentoso e apressado: leia antes de aceitar.

Aceitar em bloco sem ler é como você acumula bug silencioso. Dois minutos de revisão economizam duas horas de debug depois. E existe um tipo de erro particularmente traiçoeiro: o código que funciona, passa nos testes, mas resolve um problema ligeiramente diferente do que você pediu. Esse não aparece no CI — aparece em produção, três semanas depois, quando ninguém lembra mais do contexto.

Meu checklist de revisão, em ordem de quanto já me custou:

1. Os imports existem? É o erro mais frequente e o mais fácil de pegar.
2. O tratamento de erro é real ou é um catch vazio? Modelos adoram engolir exceção pra fazer o código "passar".
3. Os testes testam alguma coisa? Se a asserção virou expect(true).toBe(true), o teste foi "consertado" do jeito errado.
4. Isso duplica algo que já existe no projeto? A IA não sabe o que você já escreveu se você não contar.

6. Ajustes de conforto que fazem diferença

• Atalho de aceitar/rejeitar sugestão: decore. Aceitar por reflexo é o inimigo; ter o atalho na mão te faz revisar antes.
• Privacidade: se você trabalha com código sensível, ative o modo de privacidade para que trechos não sejam retidos. Vale checar isso antes de apontar o Cursor para um repositório de cliente — depois não tem desfazer.
• Terminal com IA: deixe o Cursor sugerir comandos, mas nunca rode comando destrutivo sem ler. "Limpar node_modules" e "apagar o banco" moram perto no espaço de sugestões.
• Commits pequenos: com IA você produz mudança muito mais rápido, e a tentação é acumular tudo num commit gigante. Faça o contrário — commit pequeno é o que te deixa reverter só a parte errada.

7. O que não vale a pena delegar

Depois de um tempo, você aprende onde a IA custa mais do que rende. Na minha lista: decisão de arquitetura (ela sugere o padrão mais popular, não o mais adequado ao seu contexto), nomeação de domínio (os nomes que ela dá são genéricos e você vai conviver com eles por anos) e debugging de bug intermitente — nesse caso ela chuta hipóteses plausíveis indefinidamente, enquanto um console.log bem colocado resolveria em cinco minutos.

Existe um sinal claro de que você passou do ponto: se você já está na terceira tentativa de explicar a mesma coisa pro modelo, pare e escreva você mesmo. O tempo de explicar já passou o tempo de fazer.

O ganho real é honesto: não é "3x", é "sem o trabalho chato"

Prometeram pra você que a IA te faz programar 3x mais rápido. A verdade que eu vivo é mais útil: ela não me faz pensar 3x mais rápido — pensar continua sendo o gargalo. O que ela faz é tirar o trabalho mecânico: boilerplate, testes repetitivos, aquela função de parse chata, traduzir um erro obscuro. Sobra mais tempo pra decisão de arquitetura, que é onde você agrega valor.

Tem um efeito colateral que ninguém menciona e que eu considero o maior ganho: a IA reduz o atrito de começar. Aquela tarefa que você empurrava com a barriga porque dava preguiça (escrever os testes, migrar a configuração antiga, documentar o módulo) fica bem mais fácil de encarar quando o rascunho aparece em segundos. Não é velocidade de digitação — é vencer a inércia.

Configure o Cursor com regras claras, escolha o modelo certo, use o Composer para mudanças grandes, referencie arquivos reais em vez de descrever e revise tudo. Faça isso e ele deixa de ser "autocomplete caro" e vira, de fato, um parceiro de programação.