Como o Cursor (IDE com IA) funciona

• Entender o funcionamento interno de ferramentas de codificação com IA como Cursor, Windsurf e Copilot permite aumentar a produtividade e garantir desempenho consistente em codebases complexas
• Muitas pessoas não entendem as limitações de uma IDE com IA e a tratam como uma ferramenta tradicional, acabando por enfrentar problemas de desempenho
• Este artigo explica o funcionamento interno do Cursor, seu prompt de sistema e como otimizar a codificação e as regras do Cursor

De LLM para agente de codificação

Grandes modelos de linguagem (LLM)

• LLMs basicamente funcionam prevendo a próxima palavra
• Ao fornecer um prompt, o LLM gera uma resposta como autocompletar
  • Os primeiros LLMs baseados em decoder, como o GPT-2, exigiam prompts específicos para obter o resultado desejado
  • Prompt engineering é a técnica de “enganar” o modelo para induzi-lo à resposta desejada
• A introdução do Instruction Tuning melhorou a facilidade de uso
  • Comandos como “escreva um PR refatorando o método Foo” passaram a funcionar diretamente
  • Na prática, isso ainda é uma versão expandida do processo de autocompletar
• Foi adicionado o Tool Calling
  • O modelo pode executar tarefas como ler arquivos, escrever arquivos e rodar comandos
  • Ex.: read_file('index.py') → o cliente fornece o conteúdo do arquivo → o modelo continua a tarefa

Codificação baseada em agentes

Uma IDE com IA como o Cursor é construída usando uma estrutura wrapper complexa:

• Fork do VSCode → começa a partir de uma base open source
• Adição de uma UI de chat e escolha de um LLM apropriado (ex.: Sonnet 3.7)
• Implementação de ferramentas para agentes de codificação
  • read_file(full_path: str)
  • write_file(full_path: str, content: str)
  • run_command(command: str)
• Otimização de prompts
  • Inclusão de instruções como “você é um programador especialista”, “não adivinhe, use ferramentas” etc.
    → Implementar apenas essas etapas já faz o sistema funcionar, mas na prática podem surgir problemas de erros de sintaxe, alucinações e falta de consistência

Estratégias e dicas para otimizar a codificação baseada em agentes

• Para criar uma boa IDE com IA, é preciso entender em que tipo de tarefa o LLM é bom e projetar cuidadosamente prompts e ferramentas de acordo com as limitações do LLM.
  • Simplificar a tarefa principal e usar modelos menores para subtarefas é uma abordagem eficaz
  • Distribuir tarefas complexas pode melhorar desempenho e consistência

• Adicionar contexto do usuário (uso de @file)

  • É bem provável que o usuário já saiba quais arquivos ou contexto são adequados
  • Adicionar a sintaxe @file → inclui o conteúdo de um arquivo ou pasta inteira para fornecer contexto
  • Dica: use ativamente @folder/@file → fornecer contexto claro melhora velocidade de resposta e precisão

• Otimização da busca de código

  • A busca de código pode ser complexa, especialmente a busca semântica (por exemplo, “onde fica o código de autenticação”)
  • Indexar a codebase em um Vectorstore → na busca, o LLM filtra e reordena automaticamente
  • Dica: comentários e documentação no código são importantes → fortalecem o desempenho do modelo de embeddings
    • Adicione no topo do arquivo explicações sobre o propósito daquele arquivo, seu significado e quando ele deve ser alterado

• Otimização da escrita de arquivos

  • Escrever código perfeito é difícil e caro
  • Em vez do arquivo inteiro, gerar um Semantic Diff → fornecer apenas os trechos de código modificados
  • Um modelo separado de aplicação usa essa diferença semântica para escrever de fato o arquivo → corrigindo erros de sintaxe
  • Dica: não é possível enviar comandos de prompt diretamente ao modelo de aplicação → fornecer o arquivo inteiro aumenta o controle
  • Dica: o modelo de aplicação pode ficar lento e errar ao editar arquivos grandes → mantenha o tamanho do arquivo abaixo de 500 LoC
  • Dica: feedback do linter é um sinal extremamente importante → é essencial adotar um linter forte
    • Também é possível aproveitar o feedback fornecido por compilação e linguagens tipadas
  • Dica: use nomes de arquivo únicos → em vez de page.js, use nomes específicos como foo-page.js, bar-page.js etc.
    • Forneça o caminho completo do arquivo na documentação → elimina ambiguidades para a ferramenta de edição

• Uso de modelos especializados para agentes

  • Recomenda-se usar modelos especializados para agentes, e não modelos genéricos de escrita de código
  • Esse é o motivo de os modelos da Anthropic apresentarem desempenho excelente em IDEs como o Cursor
  • Dica: escolha modelos otimizados para IDEs baseadas em agentes, e não apenas para escrever código
    • É possível verificar o desempenho dos modelos no ranking do WebDev Arena

• Uso de ferramentas de autoajuste (estratégia avançada)

  • apply_and_check_tool → executa um linter caro + coleta logs de console e screenshots em um navegador headless
  • MCP (Model Context Protocol) → reforça a autonomia do agente e o fornecimento de contexto

Análise detalhada do prompt de sistema do Cursor

• O prompt mais recente do Cursor (março de 2025) foi extraído por meio de uma técnica de injeção de prompt baseada em MCP
  • Os engenheiros de prompt do Cursor têm grande habilidade na escrita de prompts, mesmo em comparação com outras IDEs com IA.
  • Analisar a estrutura do prompt pode melhorar o desempenho de geração de código e a capacidade de projetar arquiteturas de agentes

• Principais elementos do prompt e seu significado

  • Uso de tags como "<communication>", "<tool_calling>"
    • Mistura de Markdown e tags XML → fácil para humanos lerem e para o LLM processar
  • "powered by Claude 3.5 Sonnet"
    • Reforça a consistência do modelo → evita que o LLM forneça informações incorretas sobre qual modelo está em execução
  • "the world's best IDE"
    • Evita que o LLM recomende outros produtos quando ocorrer um erro
  • "we may automatically attach some information…follow the USER's instructions…by the <user_query> tag."
    • O prompt do usuário não é passado diretamente, mas encapsulado em uma tag especial para evitar confusão
  • "Refrain from apologizing"
    • Evita pedidos de desculpa desnecessários (compensando uma característica do modelo Sonnet)
  • "NEVER refer to tool names when speaking"
    • Adiciona a instrução de não mencionar nomes de ferramentas → mas na prática o modelo às vezes ignora isso
  • "Before calling each tool, first explain"
    • Explicar o estado antes de chamar uma ferramenta → melhora a experiência do usuário
  • "partially satiate the USER's query, but you're not confident, gather more information"
    • Evita respostas prematuras por excesso de confiança → induz a buscar mais informações
  • "NEVER output code to the USER"
    • Proíbe exibir código diretamente → permite gerar código apenas via ferramentas
  • "If you're building a web app from scratch, give it a beautiful and modern UI"
    • Com um único prompt, incentiva a criação de um web app bonito e moderno (para fins de demonstração)
  • "you MUST read the the contents or section of what you're editing before editing it"
    • Obriga a ler o contexto antes de editar código → reforça a compreensão contextual
  • "DO NOT loop more than 3 times on fixing linter errors"
    • Limita o loop de correções → evita loops infinitos
  • "Address the root cause instead of the symptoms."
    • Incentiva corrigir a causa raiz, e não apenas os sintomas
  • "DO NOT hardcode an API key"
    • Instrução para reforçar a segurança → evita hardcoding
  • "codebase_search", "read_file", "grep_search", "file_search", "web_search"
    • Diversas ferramentas de busca para garantir o contexto correto antes de escrever código
  • Exigência de "One sentence explanation…why this command needs to be run…"
    • Reforça a lógica ao processar argumentos de ferramentas → técnica aplicada de melhoria de prompt
  • A ferramenta "reapply" é descrita como "Calls a smarter model to apply the last edit"
    • Reaplica a última alteração com um modelo mais avançado → melhora a qualidade da edição
  • A ferramenta "edit_file" é descrita como "represent all unchanged code using the comment of the language you're editing"
    • Representa o código não alterado com comentários → reforça a precisão do modelo de edição
• Uso de prompt caching
  • O prompt de sistema e as descrições das ferramentas permanecem em um estado estático
  • Não há personalização por codebase ou por usuário → o prompt caching pode melhorar custo e velocidade de processamento

Como escrever e usar regras do Cursor com eficácia

• Não existe uma resposta única para escrever regras do Cursor, pois isso pode variar conforme a situação, mas com base na experiência de escrita de prompts e na compreensão da estrutura interna do Cursor, aqui vão algumas dicas úteis
• É importante escrever regras não como comandos simples, mas como diretrizes em estilo enciclopédico.

• Conceitos centrais ao escrever regras

  • O LLM chama fetch_rules(…) com base no nome e na descrição da lista de regras
  • As regras não são adicionadas ao prompt de sistema; elas são consultadas apenas quando necessário
  • Por isso, uma descrição enciclopédica funciona melhor do que instruções diretas

• O que evitar ao escrever regras

  • Proibir definir identidade (identity)
    • Não use descrições como “você é um especialista em TypeScript”
    • O LLM já conhece sua identidade por meio do prompt embutido → há risco de conflito
  • Não tentar sobrescrever o prompt de sistema
    • Comandos como “não adicione comentários”, “faça perguntas antes de escrever código” etc. → geram confusão no uso das ferramentas internas
  • Evitar comandos negativos
    • Comandos positivos como “faça” funcionam melhor para LLMs do que “não faça”
    • Exemplo de comando positivo: “ao modificar um arquivo, verifique todo o contexto antes de editar”

• Recomendações ao escrever regras

  • Escreva nomes e descrições de regras claros e intuitivos
    • Deve ser possível aplicar a regra mesmo com informações mínimas sobre a codebase
    • Regras duplicadas podem existir → isso melhora a precisão da busca
  • Escreva as regras em estilo enciclopédico
    • Em vez de comandos específicos, forneça explicações sobre a situação e o objetivo
    • Se necessário, é possível vincular arquivos de código para reforçar o contexto
  • Use o Cursor para criar rascunhos de regras
    • LLMs são bons em escrever contexto para outros LLMs
    • Ex.: “@folder/ crie um arquivo Markdown sobre caminhos de código frequentemente modificados e suas definições”
  • Evite escrever regras demais
    • Regras em excesso são ineficientes e podem indicar uma codebase pouco intuitiva
    • Em uma codebase ideal, o agente consegue trabalhar com o mínimo possível de regras

• Exemplos de regras eficazes

  • ✅ Comandos de regra:
    • “leia todo o contexto antes de modificar um arquivo”
    • “ao modificar código do servidor, verifique a lógica de autenticação”
    • “quando ocorrer um erro, corrija primeiro a causa”
  • ❌ Comandos de regra (devem ser evitados):
    • “não apague comentários”
    • “faça perguntas antes de me responder”
    • “não modifique código desnecessariamente”

• Estratégia central para escrever regras

  • As regras devem ser escritas não como comandos, mas como descrições de situação
  • Use nomes e descrições intuitivos → obtenha o máximo de desempenho com o mínimo de regras
  • Em vez de comandos específicos, fortaleça a descrição da situação e a ligação com o código

Conclusão

• É impressionante que o Cursor, que começou como um fork do VSCode e usa prompts baseados em open source e APIs públicas de modelos, tenha alcançado uma avaliação próxima de US$ 10 bilhões (cerca de R$ 55 bilhões)
  • Atualmente, o Cursor é avaliado em 6 vezes com base no critério de wrapper multiple
• O Cursor oferece desempenho poderoso graças a prompts otimizados e a um forte sistema de tool calling
• É pouco provável que o Cursor desenvolva seu próprio modelo de agente
  • Em vez disso, é mais provável que a Anthropic lance um produto concorrente baseado em Claude Code e Sonnet

• Principais insights

  • Configurar corretamente a codebase, a documentação e as regras continuará sendo uma habilidade importante
  • Entender as estratégias de otimização de ferramentas de codificação com IA pode aumentar produtividade e precisão
  • Se o Cursor não estiver funcionando direito, o problema provavelmente está na forma de uso

"Se o Cursor não está funcionando, você precisa revisar como está usando a ferramenta."

[bluekai17]

Acho que vou testar.

[ohyecloudy]

Rascunho das regras escrito usando o Cursor
LLMs são bons em escrever contexto para outros LLMs

Interessante. Será porque, no fim das contas, bebem da mesma fonte?

[linker]

Há muita percepção aqui. Obrigado.

[nicewook]

• Análise detalhada do prompt de sistema do Cursor — impressionante.
• Só de pensar que a Anthropic pode lançar uma AI IDE, já fico animado.