Cursor parece VS Code com superpoderes, e é — mas para aproveitar de verdade você precisa entender como funciona cada modo de IA e quando usar cada um. Este guia te leva desde a instalação até um fluxo de trabalho produtivo com Composer, Tab, Chat e Rules.
Pré-requisitos
- Baixar Cursor de cursor.com (Mac, Windows, Linux)
- Um projeto existente para praticar
- Se você vem do VS Code: suas extensões e configuração são migradas automaticamente
Passo 1: Instalação e Migração
- Baixe e instale Cursor
- Ao abrir pela primeira vez, Cursor oferece importar sua configuração do VS Code — aceite
- Suas extensões, temas, keybindings e settings são copiados automaticamente
- Abra seu projeto com
File → Open Folder
Se você já tinha VS Code aberto, feche-o. Cursor e VS Code podem coexistir mas compartilham algumas extensões e pode haver conflitos.
Passo 2: Entender os Modos de IA
Cursor tem quatro modos principais de interação com IA. Cada um tem seu caso de uso:
Tab (Autocomplete Inteligente)
- Se ativa automaticamente enquanto você digita
- Vai além do autocomplete típico — prevê sua intenção, não apenas a próxima linha
- Pode sugerir edições em múltiplas linhas simultaneamente
- Aceita com
Tab, rejeita comEsc, aceita parcialmente comCtrl+→
Cmd+K / Ctrl+K (Inline Edit)
- Seleciona código → pressiona
Ctrl+K→ descreve a mudança - Cursor reescreve o código selecionado no lugar
- Ideal para mudanças pontuais: “converte isso para async/await”, “adiciona tratamento de erros”, “otimiza esta query”
Chat (Ctrl+L / Cmd+L)
- Painel lateral conversacional
- Use
@para referenciar arquivos, símbolos, documentação - Ideal para perguntas sobre seu codebase, explicações e explorar abordagens
- Não edita arquivos diretamente — mostra código que você pode aplicar
Composer (Ctrl+I / Cmd+I)
- O modo mais poderoso — agente que planeja e aplica mudanças em múltiplos arquivos
- Descreva uma tarefa completa: “adiciona autenticação JWT às rotas da API”
- Composer analisa seu codebase, planeja as mudanças e as aplica
- Mostra diffs para cada arquivo — você revisa e aceita ou rejeita
Passo 3: Configurar Rules
As Rules são o equivalente do Cursor às custom instructions. Crie uma pasta .cursor/rules/ na raiz do seu projeto:
.cursor/rules/general.mdc
---
description: Regras gerais do projeto
globs: "**/*"
---
# Contexto do Projeto
Este é um projeto de e-commerce construído com:
- Frontend: Next.js 14 com App Router e TypeScript
- Backend: API Routes em Next.js
- Banco de dados: Supabase (PostgreSQL)
- Auth: Supabase Auth
- Styling: Tailwind CSS
- Deploy: Vercel
# Convenções
- Código em inglês, comentários de documentação em português
- Usar Server Components por padrão, Client Components apenas quando necessário
- Sempre lidar com estados de loading e erro
- Validar inputs com Zod no server side
- Usar as convenções de naming do Next.js para arquivos especiais
.cursor/rules/api.mdc
---
description: Regras para API routes
globs: "app/api/**/*"
---
# API Routes
- Sempre validar o body do request com Zod
- Usar try/catch com respostas de erro consistentes
- Formato de erro: { error: string, code: string, details?: object }
- Autenticar com middleware Supabase Auth
- Rate limiting em endpoints públicos
- Logs estruturados com timestamp e request ID
As Rules com globs se ativam automaticamente quando você trabalha em arquivos que correspondem ao padrão. Isso significa que Composer e Chat recebem instruções diferentes dependendo do arquivo em que você está.
Passo 4: Fluxo de Trabalho com Composer
Composer é onde Cursor realmente se diferencia. Aqui está um fluxo prático para implementar uma feature:
Exemplo: Adicionar um sistema de reviews a produtos
- Abra Composer (
Ctrl+I) - Escreva seu prompt com contexto:
Preciso adicionar um sistema de reviews para produtos. Usuários
autenticados podem deixar uma review com rating (1-5 estrelas) e
um comentário opcional.
Preciso de:
1. Schema do Supabase para a tabela reviews (migração SQL)
2. API route POST /api/reviews para criar uma review
3. API route GET /api/reviews/[productId] para obter reviews de um produto
4. Componente ReviewForm para enviar uma review
5. Componente ReviewList para mostrar reviews com rating médio
Use as convenções existentes do projeto. Veja como estão
estruturados os outros API routes e componentes para manter
consistência.
- Composer analisa seu projeto, gera um plano e começa a criar/modificar arquivos
- Revise cada diff cuidadosamente — aceite o que está certo, rejeite o que não está
- Se algo não estiver correto, descreva o ajuste na mesma thread de conversação
Dicas para prompts de Composer efetivos:
- Seja específico sobre o que você quer, mas não sobre como implementar — deixe que Cursor escolha a abordagem baseado em seu codebase existente
- Referencie arquivos existentes: “siga o padrão de
app/api/products/route.ts” - Divida tarefas grandes em passos — é melhor fazer 3 prompts focados que um gigante
Passo 5: Fluxo de Trabalho com @ References
O sistema de @ em Chat e Composer é fundamental:
@file— referencia um arquivo específico@folder— inclui todos os arquivos de uma pasta@codebase— busca em todo seu projeto (usa o índice)@docs— referencia documentação externa (você pode adicionar URLs)@web— busca na web@git— referencia commits, diffs e o histórico de mudanças
Exemplo prático em Chat:
@app/lib/supabase.ts @app/api/products/route.ts
Como posso adicionar paginação ao endpoint de produtos
mantendo o padrão existente de tratamento de erros?
Isso dá a Cursor exatamente o contexto que precisa sem incluir arquivos irrelevantes.
Passo 6: Configurar Docs Externos
Adicione documentação das bibliotecas que você usa para que Cursor as referencie:
- Vá para
Cursor Settings → Features → Docs - Adicione URLs de documentação:
https://nextjs.org/docs— Next.jshttps://supabase.com/docs— Supabasehttps://tailwindcss.com/docs— Tailwind
- Agora em Chat você pode usar
@docs Next.jse Cursor busca diretamente na documentação
Isso é especialmente útil para APIs que mudam frequentemente — Cursor usa a documentação atual em vez de seu conhecimento de treinamento.
Passo 7: Seleção de Modelo
Cursor suporta múltiplos modelos. Recomendações práticas:
- Claude Sonnet — melhor relação qualidade/velocidade para a maioria das tarefas em Composer
- Claude Opus — para tarefas complexas de arquitetura e refactoring grande
- GPT-4o — rápido para edits inline e perguntas simples
- cursor-small — o modelo próprio do Cursor, rápido para Tab autocomplete
Você pode mudar o modelo em cada conversa de Chat ou Composer. Você não está limitado a apenas um.
Erros Comuns
Aceitar todos os diffs de Composer sem revisar. Composer é poderoso mas não infalível. Revise cada mudança como você revisaria um PR — especialmente em lógica de negócio e segurança.
Não usar Rules. Sem Rules, Cursor gera código genérico. Com Rules bem escritas, gera código que segue suas convenções. A diferença é enorme.
Prompts vagos. “Melhora este código” produz resultados mediocres. “Refatore esta função para separar a lógica de validação do processamento, e adicione tipos TypeScript específicos em vez de any” produz resultados excelentes.
Não indexar o projeto. Certifique-se de que o indexing está habilitado em Settings. Sem ele, @codebase e as sugestões de Composer são muito menos precisas.
Resultado
Com esta configuração você tem um fluxo onde:
- Tab lida com o autocomplete inteligente enquanto você digita
- Ctrl+K faz edits pontuais sem sair do arquivo
- Chat responde perguntas com contexto completo do seu projeto
- Composer implementa features completas com revisão de diffs
- Rules garantem que todo código gerado siga suas convenções
A curva de aprendizado é de alguns dias. O impacto na produtividade é imediato.Você já está usando Cursor? Compartilhe suas Rules e fluxos de trabalho favoritos. 