Cursor @Codebase, @Docs ou @Files: qual usar? Guia prático de decisão

O sistema de símbolos @ do Cursor parece simples: @Codebase, @Files, @Docs. Você clica e adiciona contexto para a IA. Mas, na prática, muita gente trava em uma pergunta: mesmo sabendo qual código quer encontrar, não sabe qual símbolo deve usar.

Quando você escolhe errado, a IA injeta um monte de conteúdo sem relação ou não encontra o arquivo que realmente importa. Depois de um tempo, o histórico da conversa vira uma sequência de consultas repetidas, os tokens vão embora e o problema continua mal resolvido.

Este artigo não tenta redefinir cada recurso. O foco é uma coisa só: em cenários concretos, como decidir rapidamente qual símbolo @ usar. Depois da leitura, você terá uma linha de decisão clara, sem precisar hesitar a cada tentativa.

1. Comparação central do sistema @: 6 recursos de cara

Primeiro, uma conclusão importante: pelos testes práticos do BetterLink Blog, em 80% do tempo de desenvolvimento você deveria usar @Codebase, em vez de escolher arquivos manualmente. O número parece alto, mas a lógica é simples: a principal vantagem do @Codebase não é pesquisar, e sim deixar a IA descobrir código relacionado que você talvez ignorasse.

Abaixo estão os 6 símbolos, ordenados pela frequência de uso:

@Codebase (60-80%): busca semântica em toda a base de código. Você faz uma pergunta, e a IA procura automaticamente os arquivos, funções e definições de tipos mais relevantes no projeto. Não precisa saber onde o arquivo está nem selecionar nada manualmente. Serve para entender arquitetura, refatorar código e localizar problemas entre arquivos. O consumo de tokens é mais alto, porque o índice cobre a base inteira.

@Docs (10-15%): referência a documentação externa. Dá para chamar a documentação interna de frameworks como React, Vue e Astro, ou adicionar uma fonte personalizada por URL. Serve para bibliotecas recém-lançadas, APIs recentes e integração com bases de conhecimento da equipe.

@Files (5-10%): referência exata ao conteúdo completo de um arquivo. Use quando você sabe claramente o nome do arquivo ou precisa alterar um arquivo de configuração, como vite.config.ts. Se o arquivo tiver mais de 600 linhas, @Files costuma ser mais preciso que @Codebase. O custo é um consumo maior de tokens, porque o arquivo inteiro entra no contexto.

@Code (5-10%): referência a um trecho específico de código. Só entra no contexto a seleção que você marcou, sem carregar o arquivo inteiro. Serve para otimização local, depuração de uma lógica pequena e evitar poluição de contexto no nível do arquivo. É o menor consumo de tokens.

@Folders (abaixo de 5%): referência à estrutura e a um panorama de conteúdo de uma pasta inteira. Serve para refatoração de módulos, geração de novos componentes e checagem de consistência arquitetural. O consumo de tokens é alto, porque envolve vários arquivos.

@Repo (cenários específicos): contexto de repositório. Serve para projetos com múltiplos repositórios, análise de histórico de versões e localização de problemas entre repos. O consumo de tokens é médio.

Esses 6 símbolos não são mutuamente exclusivos. Você pode combiná-los na mesma conversa. Por exemplo: usar @Codebase para obter a visão geral, depois @Files para travar nos arquivos-chave e, por fim, @Docs para completar com a documentação oficial. O ponto é: escolha conforme o tipo de problema, em vez de empilhar contexto às cegas.

2. Árvore de decisão: tipo de problema → símbolo @

A lógica para escolher o símbolo se resume a uma pergunta: você sabe onde está o código?

Se não sabe, use @Codebase. Se sabe, use @Files ou @Code. Se ainda falta documentação, acrescente @Docs.

Em mais detalhes:

Cenário 1: você não sabe onde está o arquivo

Imagine que você está refatorando um projeto Next.js e quer alterar o formato de retorno de uma API, mas não sabe onde fica a definição de tipos. Pode estar em types/, em components/, ou até em algum utils.ts onde alguém definiu algo de passagem.

Nesse caso, use @Codebase. Escreva diretamente no Chat: “me ajude a encontrar a definição do tipo ApiResponse e alterar o formato de retorno”. A IA escaneia a base inteira e encontra todos os pontos que referenciam esse tipo, incluindo aquele utils.ts que você talvez deixasse passar.

Cenário 2: você sabe exatamente o nome do arquivo

Por exemplo, você precisa alterar a configuração de proxy em vite.config.ts ou refatorar uma função em src/utils/auth.ts. O caminho está claro e o conteúdo é relativamente longo, acima de 600 linhas.

Use @Files. Clique em @Files, selecione o arquivo alvo, e a IA receberá o conteúdo completo. Isso é mais preciso que @Codebase e evita que a IA retorne uma pilha de arquivos “relacionados, mas sem importância”.

Cenário 3: você precisa consultar a documentação mais recente

Por exemplo, você está usando uma biblioteca lançada na semana passada, ou precisa verificar o uso mais recente de uma API de framework que talvez não esteja nos dados de treinamento.

Railway - Plataforma de deploy moderna, sem ops complexas, no ar em minutos

Começar agora →Anúncio

Use @Docs. Digite @Docs, escolha a documentação interna do framework ou cole uma URL para adicionar uma nova fonte. O detalhe importante é: no prompt, diga “use a versão mais recente da documentação”. Caso contrário, a IA pode voltar ao padrão antigo que ela já conhece.

Cenário 4: você só se importa com um trecho de código

Por exemplo, você está depurando a lógica de uma função e só quer otimizar algumas linhas, sem jogar o arquivo inteiro no contexto.

Use @Code. Selecione o trecho, pressione Cmd+K para abrir a edição inline, ou referencie a seleção com @Code no Chat. O consumo de tokens é o menor possível e o contexto fica mais limpo.

Cenário 5: refatoração de módulo ou geração de novo componente

Por exemplo, você quer refatorar todo o diretório components/ ou gerar um novo módulo em features/, mantendo consistência de arquitetura.

Use @Folders. Ele pega uma visão geral da estrutura da pasta e dos arquivos-chave. Assim a IA entende como o módulo está organizado e gera código compatível com o estilo existente.

Cenário 6: análise de múltiplos repositórios ou histórico de versões

Por exemplo, seu projeto depende de vários repositórios Git, ou você precisa analisar o impacto de um commit.

Use @Repo. Ele fornece repository context, incluindo histórico de versões e relações de dependência entre repositórios.

Resumindo, a árvore de decisão cabe em uma frase: se não sabe a localização, use @Codebase; se sabe, use @Files/@Code; se falta documentação, use @Docs. Os outros dois símbolos, @Folders e @Repo, complementam cenários específicos.

3. @Codebase vs @Files: diferença central e casos práticos

Esses dois símbolos são os mais fáceis de confundir. A diferença é uma só: a IA procura para você, ou você aponta o arquivo.

O valor do @Codebase não é “pesquisar”, e sim “descobrir”. Você faz uma pergunta, a IA executa correspondência semântica na base inteira e retorna os arquivos, funções e definições de tipos mais relevantes. O ponto principal é que ela pode retornar arquivos que você não tinha imaginado. Se você perguntar “como alterar o formato de retorno da API”, a IA pode trazer:

• o arquivo do API handler, que você esperava;
• o arquivo de definição de tipos, que talvez você já conhecesse;
• um alias de tipo definido de passagem em algum utils.ts, que você talvez ignorasse;
• dados mock em um arquivo de teste, que talvez você nem tivesse notado.

Essa é a vantagem central do @Codebase: a IA encontra código relacionado que você poderia deixar passar.

O valor do @Files é “precisão”. Você indica explicitamente o arquivo, a IA recebe o conteúdo completo e não há ambiguidade. O custo é que você precisa saber onde o arquivo está e aceitar um consumo maior de tokens, já que o conteúdo inteiro entra no contexto.

Caso prático 1: alterar o formato de retorno de uma API (@Codebase é melhor)

Cenário: você tem uma API em Next.js com o seguinte formato de retorno:

// src/app/api/users/route.ts
export async function GET(request: Request) {
  const users = await db.query('SELECT * FROM users');
  return Response.json({ data: users, total: users.length });
}

Você quer trocar o retorno para { users, count }, mas não sabe onde estão as definições de tipo.

Se usar @Files, terá de procurar manualmente todos os arquivos relacionados: route.ts, algum possível types.ts, e os componentes frontend que chamam essa API. É fácil deixar arquivo para trás.

Com @Codebase, escreva diretamente no Chat:

@Codebase
Me ajude a alterar o formato de retorno da API de usuários, de { data, total } para { users, count }.
Também preciso atualizar todas as definições de tipo e chamadas frontend relacionadas.

A IA pode retornar:

Encontrei os seguintes arquivos relacionados:
1. src/app/api/users/route.ts - API handler
2. src/types/api.ts - definição do tipo ApiResponse
3. src/components/UserList.tsx - componente frontend que chama a API
4. src/utils/mock.ts - dados mock de teste que também usam esse formato

De cara você percebe que mock.ts também usa esse formato. Esse talvez fosse justamente o arquivo que você não tinha visto.

Caso prático 2: otimizar vite.config.ts (@Files é melhor)

Cenário: você quer alterar a configuração de proxy do Vite, e o caminho do arquivo está claro: vite.config.ts.

// vite.config.ts
export default defineConfig({
  server: {
    proxy: {
      '/api': 'http://localhost:3000'
    }
  }
})

O objetivo é fazer o proxy suportar vários ambientes: desenvolvimento, teste e produção.

Aqui, @Files é mais adequado. Motivos:

1. A localização do arquivo é clara.
2. O conteúdo não é longo, geralmente entre 50 e 200 linhas.
3. Não há necessidade de busca entre arquivos.

No Chat, escreva:

@Files vite.config.ts
Me ajude a alterar a configuração de proxy para suportar vários ambientes: desenvolvimento, teste e produção.
Leia a configuração de ambiente a partir de .env.development, .env.test e .env.production.

A IA recebe o vite.config.ts completo e pode propor a alteração diretamente:

// vite.config.ts
export default defineConfig(({ mode }) => {
  const env = loadEnv(mode, process.cwd(), '');
  return {
    server: {
      proxy: {
        '/api': env.API_URL || 'http://localhost:3000'
      }
    }
  }
})

Resumo: se você não sabe a localização ou precisa descobrir relações ocultas, use @Codebase; se sabe a localização ou precisa entender um arquivo longo por completo, use @Files.

4. @Docs: uso de bibliotecas novas e integração com documentação

@Docs resolve um problema específico: os dados de treinamento da IA não acompanham todas as atualizações de documentação.

Imagine uma biblioteca lançada na semana passada, ou um framework que acabou de mudar a forma de usar uma API, como novos hooks do React 19 ou Turbopack no Next.js 15. Os dados de treinamento da IA podem estar alguns meses atrasados, e ela pode gerar código com uma API antiga.

O princípio do @Docs é este: ele recupera em tempo real a documentação que você indicou, interpreta o conteúdo e coloca esse material no contexto. Ao gerar código, a IA tende a priorizar a especificação mais recente da documentação.

Como usar

O fluxo é simples:

1. Digite @Docs no Chat.
2. Escolha a documentação interna de um framework, como React, Vue, Astro, Tailwind ou Next.js.
3. Ou cole uma URL para adicionar uma fonte de documentação personalizada.

Fontes personalizadas são bastante úteis. Se sua equipe tem uma base interna de conhecimento, como documentos no Feishu ou uma GitHub Wiki, você pode adicionar a URL, e a IA passa a gerar código considerando as convenções da equipe.

Caso prático: novos hooks do React 19

Suponha que você queira usar o hook useOptimistic do React 19, mas não tenha certeza da API mais recente.

Alibaba Cloud - Escolha dos desenvolvedores, 15% de desconto exclusivo em Lighthouse

Ganhar 15% off →Anúncio

Escreva diretamente no Chat:

@Docs React
Me ajude a implementar uma funcionalidade de optimistic update usando o hook useOptimistic do React 19.
Cenário: botão de curtida; depois do clique, mostrar +1 imediatamente e aguardar a confirmação do servidor.

A IA primeiro consulta a documentação oficial do React, pega a descrição mais recente da API useOptimistic e então gera um código compatível:

import { useOptimistic } from 'react';

function LikeButton({ initialLikes, onSubmit }) {
  const [optimisticLikes, addOptimisticLike] = useOptimistic(
    initialLikes,
    (state, newLike) => state + newLike
  );

  async function handleClick() {
    addOptimisticLike(1); // Mostra +1 imediatamente
    await onSubmit();     // Aguarda a confirmação do servidor
  }

  return <button onClick={handleClick}>{optimisticLikes} Likes</button>;
}

Atenção: os dados de treinamento podem sobrepor @Docs

Há uma armadilha aqui: a IA pode considerar ao mesmo tempo os dados de treinamento e o @Docs. Se a API antiga estiver muito “marcada” nos dados de treinamento, ela pode misturar APIs novas e antigas e gerar um código estranho.

A solução é: no prompt, enfatize “use a versão mais recente da documentação”.

Por exemplo:

@Docs React
Use a versão mais recente da documentação (React 19) e não use a API antiga dos dados de treinamento.

Assim a IA tende a priorizar o conteúdo do @Docs e reduzir a influência da versão antiga.

Quando usar @Docs?

A regra simples: se a biblioteca ou o framework foi lançado depois da data limite de treinamento da IA, ou se a API teve uma mudança importante, use @Docs.

Exemplos:

• React 19, lançado no fim de 2024, com mudanças importantes de API;
• Next.js 15, no fim de 2024, com Turbopack habilitado por padrão;
• recursos recentes do Supabase, documentados em tempo real;
• convenções internas da equipe, que não existem nos dados de treinamento da IA.

Se a biblioteca for estável, como React 18, Vue 3 ou Tailwind 3, e os dados de treinamento cobrirem bem o uso, @Docs deixa de ser tão necessário.

5. Boas práticas de gestão de contexto

Usar bem os símbolos @ é só o primeiro passo. O segundo é gerenciar bem o contexto. Muita gente já caiu nessa armadilha: quanto mais longa a conversa, mais a IA se desvia; no fim, o código gerado fica completamente distante da intenção inicial.

Princípio central: conversas curtas, funcionalidades separadas

Depois de concluir uma funcionalidade, reinicie a conversa. Não misture “refatorar API”, “corrigir bug” e “adicionar nova funcionalidade” no mesmo chat.

Por quê? Porque cada funcionalidade precisa de um contexto diferente. Ao refatorar uma API, a IA precisa de definições de tipos, API handler e código frontend que chama a API. Ao corrigir um bug, ela precisa de logs de erro, trechos de código relacionados e casos de teste. Quando tudo entra na mesma conversa, o contexto fica cada vez mais sujo e a IA entende cada vez menos.

A operação é simples: clique em “Clear Chat” no canto superior direito do painel Chat, ou use um atalho para abrir uma nova conversa.

Pequenas edições vs tarefas complexas

Use caminhos diferentes para cenários diferentes:

Pequenas edições, como alterar uma linha de código ou ajustar um parâmetro: use edição inline com Cmd+K. Selecione o código alvo, pressione Cmd+K e descreva a alteração. O arquivo atual e a seleção entram automaticamente no contexto, sem configuração extra.

Tarefas complexas, como refatorar um módulo ou gerar um novo componente: use Chat + @-mentions. Comece com @Codebase para obter a visão geral, use @Files para travar nos arquivos-chave e, por fim, descreva a tarefa com clareza. Assim o contexto fica mais completo e a IA entende melhor.

Otimização de índice: use .cursorignore para excluir ruído

O índice do @Codebase cobre a base inteira, mas nem todo arquivo precisa ser visto pela IA.

Exemplos:

• node_modules/, dependências que a IA não precisa ler;
• dist/ e build/, artefatos de compilação;
• .env e .env.local, configurações sensíveis;
• recursos estáticos grandes, como imagens e vídeos.

Use um arquivo .cursorignore para excluir esses diretórios e arquivos. Mantenha-o separado do .gitignore. A pergunta guia é: a IA precisa ver este arquivo?

# .cursorignore
node_modules/
dist/
build/
.env
.env.local
*.log
*.png
*.jpg

Com isso, o escopo do índice do @Codebase fica mais preciso, a consulta acelera, de 5-10 segundos para 2-3 segundos, e os resultados também ficam mais relevantes.

Atualize o README.md regularmente

Um hábito fácil de ignorar: registre o estado e a estrutura do projeto no README.md.

Por quê? Porque o README.md é um dos arquivos-chave no índice do @Codebase. Quando a IA tenta entender a arquitetura do projeto, ela tende a consultar o README primeiro. Se o README explica bem:

• a estrutura do projeto, com descrição dos diretórios;
• os módulos centrais e quais arquivos cuidam de cada função;
• mudanças recentes, como novas funcionalidades e planos de refatoração;

a IA entende a visão geral mais rápido em tarefas complexas e reduz consultas repetidas.

Vantagem para usuários Pro: escopo de índice mais amplo

Usuários do Cursor Pro conseguem indexar semanticamente a base de código inteira. Usuários Free têm limite de escopo de índice. Se o projeto passa de 500 arquivos, o @Codebase da versão Pro costuma funcionar visivelmente melhor.

Mas isso não significa que usuários Free não consigam usar bem a ferramenta. O ponto principal continua sendo: gerencie bem o contexto, escolha o símbolo certo e exclua arquivos que geram ruído. O Pro é um bônus, não uma necessidade.

6. FAQ: problemas comuns e soluções

Pergunta 1: @Codebase retorna resultados que não batem com a base de código

Sintoma: você acabou de alterar um arquivo, mas @Codebase ainda retorna o conteúdo antigo. Ou um arquivo que claramente existe não aparece no @Codebase.

Causa: o índice não foi sincronizado.

Solução:

1. Cursor Settings → “Reindex Codebase”, para forçar a reindexação.
2. Ou remova a pasta do projeto e adicione novamente, o que é mais completo.

Essa operação leva 1 a 2 minutos. Depois que o índice termina, o problema desaparece.

Pergunta 2: @Codebase retorna uma correspondência errada

Sintoma: você pergunta “como alterar UserService”, mas a IA retorna utils/user.ts, não o services/UserService.ts esperado.

KiloClaw - OpenClaw gerenciado para empresas: orquestração de agentes IA e roteamento inteligente

Começar →Anúncio

Causa: a correspondência semântica é ambígua, e a IA pode julgar a relevância de forma incorreta.

Solução:

1. Use @Files para indicar explicitamente o arquivo correto.
2. Ou informe o caminho no prompt: “altere src/services/UserService.ts”.

A vantagem do @Codebase é a descoberta automática, mas o custo é alguma margem de erro. Para tarefas precisas, use @Files.

Pergunta 3: a IA usa uma API antiga mesmo com @Docs

Sintoma: você adicionou @Docs React, mas o código gerado ainda usa o estilo do React 18.

Causa: a “memória” dos dados de treinamento é forte demais e sobrepõe o conteúdo do @Docs.

Solução: enfatize no prompt:

@Docs React
Use a versão mais recente da documentação (React 19) e não use a API antiga dos dados de treinamento.

Depois disso, a IA tende a priorizar @Docs.

Pergunta 4: @Codebase está lento, levando 5 a 10 segundos

Sintoma: toda consulta com @Codebase demora demais.

Causa: o escopo do índice é grande demais, incluindo node_modules, dist e afins.

Solução: verifique o .cursorignore e exclua arquivos desnecessários:

# .cursorignore
node_modules/
dist/
build/
*.log
*.png

Depois da exclusão, o escopo do índice diminui e a consulta costuma cair para 2-3 segundos.

Pergunta 5: o histórico de conversa ficou longo e a IA saiu do trilho

Sintoma: a conversa já passou por três ou quatro funcionalidades, e as respostas da IA estão cada vez mais distantes da sua intenção original.

Causa: poluição de contexto. Os contextos de várias funcionalidades se misturaram.

Solução: reinicie a conversa. No canto superior direito do painel Chat, clique em “Clear Chat” e abra uma conversa nova. Trate cada funcionalidade separadamente; o contexto fica mais limpo.

Pergunta 6: o consumo de tokens está alto demais e passa do orçamento

Sintoma: cada conversa consome muitos tokens, e a cota Pro acaba rápido.

Causa: escolha inadequada de símbolos, com excesso de conteúdo irrelevante no contexto.

Solução:

1. Para pequenas edições, use Cmd+K em modo inline, sem acionar @-mentions.
2. Para tarefas precisas, use @Files/@Code e evite que @Codebase retorne uma pilha de arquivos “relacionados, mas irrelevantes”.
3. Use .cursorignore para excluir arquivos grandes, como node_modules e dist.

O princípio central para consumo de tokens é: referência precisa, sem buscar a base inteira quando não precisa.

Conclusão

O sistema de símbolos @ do Cursor se resume a uma lógica: se não sabe a localização, use @Codebase; se sabe, use @Files/@Code; se falta documentação, use @Docs.

Em 80% do tempo de desenvolvimento, você deveria usar @Codebase. Isso não é exagero: o verdadeiro valor do @Codebase está em “descobrir”. A IA pode encontrar código relacionado que você ignoraria, como um alias de tipo definido sem muito alarde em utils.ts ou dados mock em algum arquivo de teste.

Mas @Codebase não resolve tudo. Se o arquivo passa de 600 linhas, ou se você sabe exatamente onde está o problema, @Files é mais preciso. Para depurar um trecho pequeno, @Code economiza mais tokens. Para bibliotecas novas ou APIs recentes, @Docs ajuda a manter a implementação alinhada à documentação.

Gestão de contexto é igualmente importante. Mantenha conversas curtas e funcionalidades separadas. Depois de concluir uma tarefa, reinicie o chat para não deixar o histórico crescer e se misturar. Use .cursorignore para excluir ruído e atualize o README.md regularmente; a IA entenderá o projeto com mais precisão.

Na próxima vez que for programar, comece se perguntando: eu sei onde está o arquivo ou preciso que a IA encontre código relacionado? Se não tiver certeza, comece com @Codebase; a IA pode revelar relações ocultas. Se tiver certeza, cite com precisão e evite poluir o contexto.

Quando você usa bem esse conjunto de símbolos, o Cursor se torna de fato um parceiro de programação, não apenas uma ferramenta de busca que despeja uma pilha de conteúdo.