Referenciando Arquivos Específicos com @menções em Seus Prompts
As @menções permitem que você aponte um prompt do Claude Code para um arquivo exato, como @src/utils/foo.ts, em vez de descrever o que você quer em prosa e torcer para que o agente encontre o correto.
Resumo
Descrever um arquivo em palavras deixa margem para o Claude Code procurar, adivinhar ou escolher o candidato errado quando vários arquivos têm nomes ou propósitos semelhantes.
As @menções removem essa ambiguidade nomeando o arquivo diretamente, para que o agente comece com o conteúdo exato que você deseja.
Elas são um hábito de prompt, não um recurso especial para configurar - você simplesmente digita @ seguido por um caminho enquanto escreve um prompt.
Usadas corretamente, elas tornam as solicitações mais rápidas e precisas; usadas descuidadamente, elas podem puxar mais conteúdo para o contexto do que uma tarefa realmente precisa.
Receita
Cartão de receita de referência rápida - pronto para copiar e colar.
# reference a single file directly
Fix the bug in @src/utils/formatDate.ts where timezones aren't applied.
# reference two related files in the same prompt
Compare @src/api/userController.ts with @src/api/orderController.ts
and make the error handling consistent between them.
# reference a config file alongside a source file
Update @src/config/rateLimits.ts to match what @docs/rate-limiting.md describes.Quando usar isso:
- Você já sabe qual arquivo (ou punhado de arquivos) a tarefa envolve.
- Você quer evitar que o Claude Code gaste um turno procurando no codebase para encontrar o arquivo certo.
- Dois arquivos compartilham um nome ou propósito semelhante e você precisa ser inequívoco sobre qual deles.
- Você está referenciando um arquivo não-código, como um arquivo de configuração ou um documento markdown, que a prosa sozinha pode não trazer à tona.
Exemplo de Trabalho
Um prompt realista de correção de bugs que combina um arquivo de origem e um arquivo de teste com @menções:
The date formatter in @src/utils/formatDate.ts returns the wrong day
when the input timestamp is near midnight UTC. The existing test in
@__tests__/formatDate.test.ts doesn't cover this case yet.
Fix the bug and add a test case for a timestamp within one minute of
UTC midnight.O que isso demonstra:
- Nomear tanto o arquivo de origem quanto seu arquivo de teste antecipadamente significa que o Claude Code não precisa procurar por nenhum deles.
- O prompt ainda explica o problema em prosa - as
@mençõessubstituem a localização de arquivos, não a descrição do que está errado. - Referenciar o arquivo de teste existente sinaliza onde o novo caso de teste deve residir, em vez de deixar o Claude Code adivinhar as convenções de teste do projeto.
- Este padrão escala para baixo de forma limpa: mesmo uma única
@mençãoem um prompt de uma linha economiza uma etapa de busca.
Mergulho Profundo
Como Funciona
- Digitar
@seguido por um caminho insere uma referência direta a esse arquivo no prompt. - O Claude Code resolve a referência e inclui o conteúdo do arquivo como contexto para aquele turno, em vez de precisar localizá-lo primeiro.
- Isso se aplica a qualquer arquivo no projeto, não apenas código-fonte - arquivos de configuração, documentos markdown e arquivos de dados podem ser mencionados da mesma forma.
- O mecanismo é aditivo: você pode combinar várias
@mençõescom prosa comum no mesmo prompt. - Como o conteúdo completo de um arquivo mencionado é adicionado ao contexto, mencionar um arquivo muito grande tem o mesmo custo de contexto como se o Claude Code tivesse lido esse arquivo por completo através de uma chamada de ferramenta.
Quando a Prosa Supera as @menções
| Situação | Abordagem melhor |
|---|---|
| Você conhece os 1-3 arquivos exatos envolvidos | @mencione-os diretamente |
| A tarefa abrange "onde quer que a lógica de autenticação esteja" e você não tem certeza de onde ela está | Descreva o objetivo em prosa e deixe o Claude Code procurar |
| Você precisa referenciar um inteiro de arquivos de uma pasta | Descreva a pasta/padrão em prosa em vez de mencionar cada arquivo individualmente |
| O arquivo é muito grande e apenas uma função nele importa | Prosa apontando para o nome da função, ou uma descrição direcionada, geralmente custa menos contexto do que mencionar o arquivo inteiro |
Encadeando Múltiplas Menções
# a task that genuinely spans a few files benefits from naming all of them
Refactor @src/services/payment.ts, @src/services/refund.ts, and
@src/types/transaction.ts to share the new `TransactionResult` shape
instead of each defining their own return type.Cada menção adicional adiciona o conteúdo completo desse arquivo ao contexto, então este padrão funciona melhor quando o número de arquivos permanece pequeno e cada arquivo nomeado é realmente relevante para a tarefa.
Armadilhas
- Mencionar um arquivo muito grande para uma tarefa pequena. Uma única
@mençãoem um arquivo de mil linhas puxa tudo para o contexto, mesmo que apenas uma função importe. Correção: descreva a função ou seção específica em prosa em vez disso, ou peça ao Claude Code para olhar apenas essa parte. - Encadear muitas menções em um único prompt. Cada menção adiciona seu conteúdo completo ao contexto, então cinco ou seis menções em um prompt podem consumir uma grande parte da janela de contexto antes mesmo que a tarefa real comece. Correção: mantenha as menções aos arquivos que são verdadeiramente centrais para a tarefa; descreva o restante.
- Mencionar um arquivo para "apenas por segurança". Adicionar uma menção por cautela em vez de necessidade é uma fonte comum de inchaço desnecessário de contexto. Correção: mencione um arquivo apenas se o prompt realmente precisar de seu conteúdo, não como um reflexo.
- Assumir que uma menção procura no codebase por arquivos relacionados. Uma
@mençãoapenas puxa o arquivo exato nomeado - ela não puxa automaticamente arquivos que o importam ou dependem dele. Correção: mencione explicitamente cada arquivo genuinamente relevante, ou descreva a relação em prosa. - Usar um caminho desatualizado ou incorreto. Uma menção apontando para um caminho que não existe mais (após uma renomeação ou movimentação) não será resolvida para o que você pretendia. Correção: verifique novamente se o caminho está atualizado, especialmente após uma refatoração.
Alternativas
| Alternativa | Use Quando | Não Use Quando |
|---|---|---|
| Descrição em prosa da tarefa | Os arquivos relevantes não são conhecidos com antecedência, ou a tarefa abrange uma área ampla e mal definida | Você já conhece o arquivo exato e quer pular a etapa de busca |
@mencione um conjunto pequeno e direcionado de arquivos | Você sabe exatamente quais 1-4 arquivos importam | A tarefa requer genuinamente explorar uma pasta inteira ou território desconhecido |
| Deixar o Claude Code procurar no codebase | Tarefas genuinamente exploratórias ou de "encontrar onde X acontece" | Você já sabe exatamente onde o código está - procurar apenas desperdiçaria um turno |
FAQs
O que digitar @ seguido por um caminho realmente faz?
Insere uma referência direta a esse arquivo em seu prompt, para que o Claude Code tenha o conteúdo do arquivo disponível imediatamente em vez de precisar procurá-lo ou lê-lo primeiro.
Posso mencionar mais de um arquivo em um único prompt?
Sim. Encadene quantas @menções a tarefa genuinamente precisar, lembrando que cada uma adiciona seu conteúdo completo ao contexto.
Mencionar um arquivo custa mais contexto do que descrevê-lo em palavras?
Sim, tipicamente. Uma menção puxa o conteúdo real do arquivo, enquanto uma descrição em prosa custa apenas as palavras que você escreveu - embora a prosa corra o risco de o Claude Code escolher o arquivo errado ou gastar um turno procurando.
Posso @mencionar um arquivo que não é código, como um documento markdown ou arquivo de configuração?
Sim. As @menções funcionam para qualquer arquivo no projeto, não apenas código-fonte.
O que acontece se eu mencionar um arquivo que não existe mais?
Ele não será resolvido para o conteúdo que você pretendia - um caminho desatualizado ou incorreto após uma renomeação ou movimentação é um erro comum. Verifique novamente se o caminho está atualizado antes de enviar o prompt.
Existe um limite para quantos arquivos posso mencionar?
Não há uma regra rígida, mas cada menção adiciona o conteúdo completo do seu arquivo à janela de contexto, portanto, mencionar muitos arquivos grandes de uma vez pode consumir uma grande parte do seu contexto disponível.
Devo mencionar uma pasta inteira?
As @menções visam arquivos individuais. Para uma tarefa que abrange uma pasta inteira, descrever a pasta e o padrão em prosa geralmente é mais barato em contexto do que mencionar cada arquivo nela.
As @menções substituem a explicação do que quero que seja feito?
Não. Uma menção apenas aponta para o arquivo - você ainda precisa descrever o problema, objetivo ou mudança que deseja em prosa ao lado dele.
Quando devo preferir prosa a uma @menção?
Quando você ainda não sabe qual arquivo é relevante, ou quando apenas uma pequena parte de um arquivo muito grande importa - em ambos os casos, deixar o Claude Code procurar ou descrever apenas a parte relevante custa menos do que mencionar o arquivo inteiro.
As @menções interagem com CLAUDE.md?
Elas são independentes, mas complementares. CLAUDE.md fornece contexto de projeto permanente a cada sessão; as @menções restringem um prompt específico a arquivos exatos para a tarefa em questão.
Menções excessivas podem contribuir para a necessidade de /compact ou /clear?
Sim. Menções grandes repetidas ao longo de uma longa sessão são uma das fontes comuns de inchaço da janela de contexto, juntamente com arquivos grandes lidos na íntegra e saídas de ferramentas verbosas.
Existe diferença entre mencionar um arquivo uma vez no início de uma conversa e mencioná-lo novamente mais tarde?
Cada menção puxa independentemente o conteúdo desse arquivo para o contexto no ponto em que é usado. Se o arquivo não mudou e ainda está fresco na conversa, mencioná-lo novamente mais tarde adiciona seu conteúdo novamente em vez de reutilizar a cópia anterior.
Relacionados
- O Que CLAUDE.md Realmente Faz - memória de projeto permanente versus referências de arquivo por prompt.
- Noções Básicas de Gerenciamento de Contexto - onde as @menções se encaixam entre as ferramentas principais da seção.
- Auditoria do Que Está Consumindo Sua Janela de Contexto do Claude Code - identificando quando as menções estão contribuindo para o inchaço.
- Por Que /compact e /clear Existem - recuperando espaço de contexto após uma sessão com muitas menções.
Versões do Stack: Escrito contra a linha de modelos Claude atual em ~junho de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (o padrão) e Claude Haiku 4.5. Nomes de modelos, preços e recursos do produto mudam rapidamente - verifique as especificações atuais em platform.claude.com/docs antes de confiar nelas.