Trabalhando com Contexto

Como trabalhar com contexto no Cursor

Primeiro, o que é uma janela de contexto? E como isso se relaciona a programar de forma eficaz com o Cursor?

Pra ampliar um pouco, um large language model (LLM) é um modelo de inteligência artificial treinado pra prever e gerar texto aprendendo padrões a partir de conjuntos de dados massivos. Ele alimenta ferramentas como o Cursor ao entender tua entrada e sugerir código ou texto com base no que já viu antes.

Tokens são as entradas e saídas desses modelos. Eles são pedaços de texto, muitas vezes um fragmento de palavra, que um LLM processa um por um. Os modelos não leem frases inteiras de uma vez; eles preveem o próximo token com base nos que vieram antes.

Pra ver como um texto é tokenizado, tu pode usar um tokenizer como este aqui.

O que é contexto?

Quando a gente gera uma sugestão de código no Cursor, “contexto” é a informação fornecida ao modelo (na forma de tokens de entrada) que ele usa para prever a informação subsequente (na forma de tokens de saída).

Existem dois tipos de contexto:

1. Contexto de intenção define o que a pessoa usuária quer obter do modelo. Por exemplo, um system prompt geralmente serve como instruções de alto nível sobre como se quer que o modelo se comporte. A maior parte do prompting feito no Cursor é contexto de intenção. “Muda aquele botão de azul para verde” é um exemplo de intenção declarada; é prescritivo.
2. Contexto de estado descreve o estado do mundo atual. Fornecer ao Cursor mensagens de erro, logs do console, imagens e trechos de código são exemplos de contexto relacionado ao estado. É descritivo, não prescritivo.

Juntos, esses dois tipos de contexto trabalham em harmonia, descrevendo o estado atual e o estado futuro desejado, permitindo que o Cursor faça sugestões de código úteis.

Fornecendo contexto no Cursor

Quanto mais contexto relevante você passar para um modelo, mais útil ele vai ser. Se o Cursor não receber contexto suficiente, o modelo vai tentar resolver sem as informações necessárias. Isso normalmente resulta em:

1. Alucinações em que o modelo tenta fazer pattern matching (quando não há padrão), causando resultados inesperados. Isso pode acontecer com frequência em modelos como o claude-3.5-sonnet quando não recebem contexto suficiente.
2. O Agent tentando reunir contexto por conta própria, pesquisando o codebase, lendo arquivos e chamando ferramentas. Um modelo com raciocínio forte (como o claude-3.7-sonnet) pode ir bem longe com essa estratégia, e fornecer o contexto inicial certo vai determinar a trajetória.

A boa notícia é que o Cursor foi construído com consciência contextual no seu núcleo e foi projetado para exigir intervenção mínima do usuário. O Cursor puxa automaticamente as partes do seu codebase que o modelo estima serem relevantes, como o arquivo atual, padrões semanticamente semelhantes em outros arquivos e outras informações da sua sessão.

No entanto, há muito contexto que pode ser aproveitado, então especificar manualmente o contexto que você sabe que é relevante para a tarefa é uma maneira útil de guiar os modelos na direção certa.

Símbolo @

A maneira mais fácil de fornecer contexto explícito é com o símbolo @. Ele é ótimo quando você sabe exatamente qual arquivo, pasta, site ou outro tipo de contexto quer incluir. Quanto mais específico você for, melhor. Aqui vai um panorama de como ser mais cirúrgico com o contexto:

Símbolo	Exemplo	Caso de uso	Desvantagem
@code	@LRUCachedFunction	Você sabe qual função, constante ou símbolo é relevante para o resultado que está gerando	Requer muito conhecimento da base de código
@file	cache.ts	Você sabe qual arquivo deve ser lido ou editado, mas não exatamente onde no arquivo	Pode incluir muito contexto irrelevante para a tarefa em questão, dependendo do tamanho
@folder	utils/	Tudo ou a maioria dos arquivos em uma pasta é relevante	Pode incluir muito contexto irrelevante para a tarefa em questão

Regras

Pensa nas regras como uma memória de longo prazo à qual tu ou outras pessoas do teu time vão querer ter acesso. Capturar contexto específico do domínio, incluindo fluxos de trabalho, formatação e outras convenções, é um ótimo ponto de partida pra escrever regras.

As regras também podem ser geradas a partir de conversas existentes usando /Generate Cursor Rules. Se tu teve uma conversa longa, com idas e vindas e muitos prompts, provavelmente tem diretrizes úteis ou regras gerais que tu vai querer reutilizar depois.

MCP

O Model Context Protocol é uma camada de extensibilidade que permite dar ao Cursor capacidades para executar ações e incorporar contexto externo.

Dependendo do teu ambiente de desenvolvimento, tu pode querer usar diferentes tipos de servidores, mas duas categorias que a gente viu serem particularmente úteis são:

• Documentação interna: por exemplo, Notion, Confluence, Google Docs
• Gerenciamento de projetos: por exemplo, Linear, Jira

Se tu já tem ferramentas para acessar contexto e executar ações via API, dá pra criar um servidor MCP pra isso. Aqui vai um guia rápido de como construir servidores MCP.

Coleta de contexto pelo próprio Agent

Um padrão poderoso que muita gente tá adotando é deixar o Agent escrever ferramentas temporárias que ele pode rodar pra coletar mais contexto. Isso é especialmente eficaz em fluxos com human-in-the-loop, onde você revisa o código antes de ele ser executado.

Por exemplo, adicionar logs de depuração no seu código, rodar, e deixar o modelo inspecionar a saída dá acesso a um contexto dinâmico que ele não conseguiria inferir estaticamente.

Em Python, você pode fazer isso pedindo pro Agent:

1. Adicionar print(“debugging: …”) nas partes relevantes do código
2. Rodar o código ou os testes usando o terminal

O Agent vai ler a saída do terminal e decidir o que fazer em seguida. A ideia central é dar pro Agent acesso ao comportamento real em tempo de execução, não só ao código estático.

Principais pontos

• Contexto é a base da programação com IA, composto por intenção (o que tu queres) e estado (o que já existe). Fornecer ambos ajuda o Cursor a fazer previsões precisas.
• Usa contexto cirúrgico com símbolos @ (@code, @file, @folder) para guiar o Cursor com precisão, em vez de depender só da coleta automática de contexto.
• Captura conhecimento repetível em regras para reutilização pela equipe toda e amplia as capacidades do Cursor com o Model Context Protocol para conectar sistemas externos.
• Contexto insuficiente leva a alucinações ou ineficiência, enquanto contexto demais e irrelevante dilui o sinal. Encontra o equilíbrio certo para ter resultados ideais.