Guia de prompts para o Cursor AI

Quando uma IA pode inspecionar um repositório, um prompt melhor geralmente é mais restrito — não mais amplo. Dê ao Cursor os arquivos, limites, restrições e validações que importam e peça que ele analise a área relevante antes de editar.

Ferramentas que conhecem o repositório podem revelar contexto útil, mas também podem fazer uma alteração parecer mais certa do que realmente é. O objetivo é transformar o acesso ao repositório em evidência, não em permissão para alterar todos os arquivos relacionados.

A documentação atual do Cursor descreve referências de contexto para material do repositório, como arquivos, pastas, alterações do git e erros do linter. Use os controles de contexto disponíveis na sua versão para apontar o assistente ao menor conjunto útil de evidências.

Por exemplo, em vez disto:

Corrija o dashboard lento.

escreva:

Investigue o atraso no carregamento do dashboard para usuários autenticados.

Escopo: Comece pela rota do dashboard, seu hook de carregamento de dados e o
único cartão que mostra um esqueleto de carregamento por tempo demais. Use como
contexto o provedor de perfil atual e a instrumentação de desempenho existente.

Resultado: Identifique se o atraso é tempo de busca, renderização desnecessária
ou uma transição de estado. Proponha a menor melhoria mensurável.

Restrições: Preserve o comportamento de autorização, a interface localizada e
o feedback de carregamento existente. Não adicione um cache nem uma nova biblioteca
de estado sem evidências.

Antes de editar, resuma o caminho de execução e indique o que você mediria.

O prompt dá ao assistente uma entrada no repositório sem tratar cada arquivo do dashboard como passível de alteração.

O contexto do repositório é mais valioso no início de uma tarefa. Peça ao Cursor que:

1. rastreie o fluxo de dados ou de controle relevante;
2. identifique o código responsável pelo comportamento;
3. diferencie fatos confirmados de pressupostos;
4. liste os menores arquivos que provavelmente precisarão mudar;
5. explique qual teste ou observação comprovará a correção.

Isso é especialmente importante quando a solicitação envolve um provedor compartilhado, um componente global, autenticação, pagamentos ou navegação. Essas áreas costumam ter pontos de chamada que uma alteração local não pode ignorar com segurança.

“Atualize a funcionalidade de notificações” ainda é amplo se ela abranger interface, persistência, workers e configurações. Adicione uma restrição de arquivo ou limite:

Altere apenas o formulário de preferências de notificação. O escritor cliente é
a fonte de verdade para atualizações de preferências; não adicione outro escritor
nem altere o agendador nesta tarefa.

Inspecione o formulário, o escritor cliente tipado e seus testes diretos. Se o
bug relatado exigir uma alteração de backend, pare e explique as evidências em
vez de expandir o escopo.

Isso não impede o assistente de encontrar um problema real que atravesse limites. Apenas torna a expansão explícita e revisável.

O contexto repetido do projeto deve ficar nas instruções ou regras do repositório, não em cada prompt de chat. Use orientações duráveis do projeto para invariantes como:

• limites de exportação estática ou de implantação;
• requisitos de localidade;
• comandos de teste e estilo de código;
• regras de responsabilidade pelo estado compartilhado;
• caminhos que exigem revisão especial.

Mantenha o prompt da tarefa focado no problema específico e nos critérios de aceitação. Se as instruções do projeto e o prompt divergirem, resolva o conflito na solicitação em vez de esperar que o assistente adivinhe qual deles importa.

Solicitações grandes são difíceis de validar porque um diff amplo esconde causa e efeito. Divida o trabalho em pontos de verificação:

Primeiro, inspecione e explique o caminho atual de envio do formulário. Não edite
arquivos.

Depois da análise, implemente apenas a correção do estado de validação e adicione
seu teste focado. Ainda não refatore componentes de formulário vizinhos.

Execute o teste relevante e resuma o diff. Se ele passar, proponha um
acompanhamento separado para a limpeza compartilhada.

Esse padrão torna o trabalho do assistente mais fácil de revisar e torna uma reversão prática se a hipótese estiver errada.

Um assistente de programação com IA não deve escolher “parece correto” como regra de conclusão:

Critérios de aceitação:
- o comportamento existente ainda funciona para um envio bem-sucedido;
- o estado inválido relatado passa a poder ser alcançado e fica visível;
- o feedback para teclado e leitor de tela permanece intacto;
- o teste direcionado passa e uma falha teria capturado o bug anterior.

Validação: execute a suíte de testes focada, a verificação de tipos e descreva
qualquer etapa manual no navegador que cubra um comportamento que o teste não
consegue observar.

Peça que ele identifique um teste ausente em vez de inventar confiança a partir de um resultado de compilação verde.

Tarefa: [Objetivo de engenharia em uma frase.]

Contexto do repositório: [Arquivos, pasta, diff, erro ou regra existente relevantes.]
Problema: [Comportamento observado e quem ele afeta.]
Escopo: [Arquivos ou limite a inspecionar primeiro.]
Resultado desejado: [Resultado observável para o usuário ou o sistema.]
Restrições: [Comportamento, compatibilidade, arquitetura e itens fora do escopo.]
Critérios de aceitação: [Resultados exigidos.]
Validação: [Testes focados, verificação de tipos, checagem manual, medição.]

Analise primeiro. Indique o responsável atual pelo comportamento, questione
qualquer pressuposto fraco e proponha a menor alteração segura antes de editar.

Use a estrutura de raciocínio mais ampla em como escrever prompts melhores para IA e consulte engenharia de prompts para desenvolvedores para padrões por tipo de tarefa. Para uma alteração que seja principalmente estrutural, use estes modelos de prompt para refatorar código.

Se uma tarefa no repositório envolver scripts ou saída de terminal, confirme o comportamento real do comando antes de alterá-lo. Pratique fluxos de trabalho de linha de comando no navegador para transformar uma saída presumida em um caso de teste observável.