Context Referencing (@file, @folder, @codebase)
A precise context management mechanism in modern AI editors (Cursor, Windsurf). It allows you to quickly attach specific files (@file), entire folders (@folder), documentation (@docs), or the whole project (@codebase) to your prompt using the @ symbol.
1. Visão geral do conceito e propósito
Ao trabalhar em um projeto grande com 100 arquivos, se você escrever no chat: «Conserte o botão de login», a modelo fica confusa. Em qual dos 10 arquivos está esse botão? Qual estilo ele usa? Onde as senhas são armazenadas?
Mentions de contexto (símbolo @) — são a ferramenta cirúrgica no vibe coding. Assim como você marca amigos no Telegram ou Instagram usando o sinal @, nos editores Cursor e Windsurf você pode marcar recursos do seu projeto.
Ao pressionar @, você abre uma lista de sugestões e diz claramente à modelo: «Olhe para @Header.tsx e use as cores de @theme.ts».
Analogia prática: a habilidade principal que evita alucinações e reduz o tempo de espera pela resposta em três vezes.
2. Lista completa de mentions e seus propósitos
┌─────────────────────────────────────────────────────────────┐
│ MENU DE REFERÊNCIAS EM EDITORES DE CÓDIGO │
├─────────────────────────────────────────────────────────────┤
│ 📄 @Files: │
│ Anexa um arquivo específico: por exemplo, `@Button.tsx` │
│ (Maior precisão, mínimo de tokens desnecessários) │
├─────────────────────────────────────────────────────────────┤
│ 📁 @Folders: │
│ Anexa uma pasta inteira: por exemplo, `@src/components` │
│ (Quando é necessário visualizar todos os componentes │
│ relacionados juntos) │
├─────────────────────────────────────────────────────────────┤
│ 🌐 @Codebase: │
│ Escaneia todo o projeto via busca vetorial │
│ (Ideal para perguntas como: "Onde a API é tratada no │
│ projeto?") │
├─────────────────────────────────────────────────────────────┤
│ 📚 @Docs: │
│ Conecta a documentação oficial e atualizada dos │
│ frameworks │
├─────────────────────────────────────────────────────────────┤
│ 💻 @Terminal: │
│ Envia para o chat o texto do último erro do console │
└─────────────────────────────────────────────────────────────┘
3. Como usar corretamente as mentions (Exemplos)
01. Corrigir um componente específico
Não escreva frases genéricas. Escreva:
«Analise
@LoginForm.tsx. Faça com que apareça um aviso vermelho abaixo do campo de entrada quando a senha estiver incorreta».
02. Criar novo código baseado em um existente
Se você quiser criar uma nova página com o mesmo estilo da antiga:
«Crie uma nova página
@src/app/about/page.tsxseguindo exatamente a mesma estrutura e estilos usados em@src/app/contact/page.tsx».
03. Analisar erros do terminal
Se aparecer texto vermelho de falha no console, escreva no chat:
«Aqui está o erro do
@Terminal. Explique em qual arquivo ocorreu a falha e como corrigi-la».
4. Por que o contexto pontual é melhor que o @codebase completo
Quanto menos arquivos desnecessários você envia para a modelo, mais focada é sua atenção. Se a tarefa envolve apenas um botão, especificar o @Button.tsx gera resultados 10 vezes melhores do que buscar em todo o repositório de código.
FAQ: Context Referencing (@file, @folder, @codebase)
Termos relacionados
Curadoria de Contexto e Higiene de Regras
Prática de engenharia para projetar, auditar regularmente e limpar arquivos de configuração de comportamento do agente (.cursorrules, .clinerules, AGENTS.md) para prevenir a degradação da atenção do modelo.
Cursor Composer (Edição Agêntica Multiarquivo)
Modo agêntico principal do editor de código Cursor (Ctrl+I / Cmd+I). Permite que a inteligência artificial crie, modifique e conecte dezenas de arquivos do projeto simultaneamente, execute comandos no terminal e verifique erros.
Tamanho da Janela de Contexto (Memória da Conversa Atual)
Volume máximo de texto (em tokens) que um modelo de linguagem consegue manter simultaneamente na memória durante uma conversa atual. Define o comprimento dos documentos que podem ser carregados de uma só vez sem perda de conteúdo.