Referenciar Archivos Específicos con @menciones en Tus Prompts
Las @menciones te permiten apuntar un prompt de Claude Code a un archivo exacto, como @src/utils/foo.ts, en lugar de describir lo que quieres en prosa y esperar que el agente encuentre el correcto.
Resumen
Describir un archivo con palabras deja espacio para que Claude Code busque, adivine o elija el candidato incorrecto cuando varios archivos tienen nombres o propósitos similares.
Las @menciones eliminan esa ambigüedad nombrando el archivo directamente, para que el agente comience con el contenido exacto que deseas.
Son un hábito de prompting, no una característica especial que configurar: simplemente escribes @ seguido de una ruta mientras redactas un prompt.
Usadas correctamente, hacen que las solicitudes sean más rápidas y precisas; usadas descuidadamente, pueden introducir más contenido en el contexto del que una tarea realmente necesita.
Receta
Tarjeta de receta de referencia rápida, lista para copiar y pegar.
# Referenciar un solo archivo directamente
Corrige el error en @src/utils/formatDate.ts donde no se aplican las zonas horarias.
# Referenciar dos archivos relacionados en el mismo prompt
Compara @src/api/userController.ts con @src/api/orderController.ts
y haz que el manejo de errores sea consistente entre ellos.
# Referenciar un archivo de configuración junto a un archivo de código fuente
Actualiza @src/config/rateLimits.ts para que coincida con lo que describe @docs/rate-limiting.md.Cuándo usar esto:
- Ya sabes en qué archivo (o un pequeño grupo de archivos) involucra la tarea.
- Quieres evitar que Claude Code pase un turno buscando en el código base para encontrar el archivo correcto.
- Dos archivos comparten un nombre o propósito similar y necesitas ser inequívoco sobre cuál.
- Estás referenciando un archivo que no es de código, como una configuración o un documento markdown, que la prosa sola podría no encontrar.
Ejemplo de Trabajo
Un prompt realista de corrección de errores que combina un archivo de código fuente y un archivo de prueba con @menciones:
El formateador de fechas en @src/utils/formatDate.ts devuelve el día incorrecto
cuando la marca de tiempo de entrada está cerca de la medianoche UTC. La prueba existente en
@__tests__/formatDate.test.ts aún no cubre este caso.
Corrige el error y agrega un caso de prueba para una marca de tiempo dentro de un minuto
de la medianoche UTC.Lo que esto demuestra:
- Nombrar tanto el archivo de código fuente como su archivo de prueba desde el principio significa que Claude Code no tiene que buscarlos.
- El prompt aún explica el problema en prosa: las
@mencionesreemplazan la búsqueda de archivos, no la descripción de lo que está mal. - Referenciar el archivo de prueba existente indica dónde debe residir el nuevo caso de prueba, en lugar de dejar que Claude Code adivine las convenciones de prueba del proyecto.
- Este patrón escala limpiamente: incluso una sola
@menciónen un prompt de una línea ahorra un paso de búsqueda.
Análisis Profundo
Cómo Funciona
- Escribir
@seguido de una ruta inserta una referencia directa a ese archivo en el prompt. - Claude Code resuelve la referencia e incluye el contenido real del archivo como contexto para ese turno, en lugar de necesitar localizarlo primero.
- Esto se aplica a cualquier archivo en el proyecto, no solo al código fuente: los archivos de configuración, documentos markdown y archivos de datos se pueden mencionar de la misma manera.
- El mecanismo es aditivo: puedes combinar varias
@mencionescon prosa ordinaria en el mismo prompt. - Dado que el contenido completo de un archivo mencionado se agrega al contexto, mencionar un archivo muy grande tiene el mismo costo de contexto que si Claude Code hubiera leído ese archivo en su totalidad a través de una llamada a una herramienta.
Cuándo la Prosa Supera a las @menciones
| Situación | Mejor enfoque |
|---|---|
| Conoces los 1-3 archivos exactos involucrados | Menciona @los directamente |
| La tarea abarca "dondequiera que viva la lógica de autenticación" y no estás seguro de dónde está | Describe el objetivo en prosa y deja que Claude Code busque |
| Necesitas referenciar el contenido de una carpeta entera de archivos | Describe la carpeta/patrón en prosa en lugar de mencionar cada archivo individualmente |
| El archivo es muy grande y solo una función en él es relevante | La prosa que apunta al nombre de la función, o una descripción dirigida, a menudo cuesta menos contexto que mencionar el archivo completo |
Encadenando Múltiples Menciones
# una tarea que realmente abarca algunos archivos se beneficia de nombrarlos a todos
Refactoriza @src/services/payment.ts, @src/services/refund.ts y
@src/types/transaction.ts para compartir la nueva forma `TransactionResult`
en lugar de que cada uno defina su propio tipo de retorno.Cada mención adicional agrega el contenido completo de ese archivo al contexto, por lo que este patrón funciona mejor cuando el número de archivos se mantiene pequeño y cada archivo nombrado es realmente relevante para la tarea.
Advertencias
- Mencionar un archivo muy grande para una tarea pequeña. Una sola
@menciónen un archivo de mil líneas introduce todo el contenido, incluso si solo una función es relevante. Solución: describe la función o sección específica en prosa, o pide a Claude Code que mire solo esa parte. - Encadenar demasiadas menciones en un solo prompt. Cada mención agrega su contenido completo al contexto, por lo que cinco o seis menciones en un solo prompt pueden consumir una gran parte de la ventana de contexto antes de que comience la tarea real. Solución: limita las menciones a los archivos que son verdaderamente centrales para la tarea; describe el resto.
- Mencionar un archivo "por si acaso". Agregar una mención por precaución en lugar de necesidad es una fuente común de hinchazón innecesaria del contexto. Solución: solo menciona un archivo si el prompt realmente necesita su contenido, no como un reflejo.
- Asumir que una mención busca en el código base archivos relacionados. Una
@menciónsolo introduce el archivo exacto nombrado; no introduce automáticamente archivos que lo importan o dependen de él. Solución: menciona explícitamente cada archivo genuinamente relevante, o describe la relación en prosa. - Usar una ruta obsoleta o incorrecta. Una mención que apunta a una ruta que ya no existe (después de un cambio de nombre o movimiento) no se resolverá a lo que pretendías. Solución: verifica que la ruta esté actualizada, especialmente después de una refactorización.
Alternativas
| Alternativa | Usar Cuando | No Usar Cuando |
|---|---|---|
| Descripción en prosa de la tarea | Los archivos relevantes no se conocen de antemano, o la tarea abarca un área amplia y poco definida | Ya conoces el archivo exacto y quieres omitir el paso de búsqueda |
@mencionar un conjunto pequeño y específico de archivos | Sabes exactamente qué 1-4 archivos son importantes | La tarea requiere genuinamente explorar un directorio completo o un territorio desconocido |
| Dejar que Claude Code busque en el código base | Tareas genuinas de exploración o de "encontrar dónde ocurre X" | Ya sabes exactamente dónde vive el código; buscar solo desperdiciaría un turno |
Preguntas Frecuentes
¿Qué hace realmente escribir @ seguido de una ruta?
Inserta una referencia directa a ese archivo en tu prompt, para que Claude Code tenga el contenido del archivo disponible de inmediato en lugar de necesitar buscarlo o leerlo primero.
¿Puedo mencionar más de un archivo en un solo prompt?
Sí. Encadena tantas @menciones como la tarea necesite genuinamente, teniendo en cuenta que cada una agrega su contenido completo al contexto.
¿Mencionar un archivo cuesta más contexto que describirlo con palabras?
Sí, típicamente. Una mención introduce el contenido real del archivo, mientras que una descripción en prosa solo cuesta las palabras que escribiste; sin embargo, la prosa corre el riesgo de que Claude Code elija el archivo incorrecto o pase un turno buscando.
¿Puedo @mencionar un archivo que no es de código, como un documento markdown o un archivo de configuración?
Sí. Las @menciones funcionan para cualquier archivo en el proyecto, no solo para el código fuente.
¿Qué sucede si menciono un archivo que ya no existe?
No se resolverá al contenido que pretendías; una ruta obsoleta o incorrecta después de un cambio de nombre o movimiento es un error común. Verifica que la ruta esté actualizada antes de enviar el prompt.
¿Hay un límite en la cantidad de archivos que puedo mencionar?
No hay una regla estricta, pero cada mención agrega el contenido completo de su archivo a la ventana de contexto, por lo que mencionar muchos archivos grandes a la vez puede consumir una gran parte de tu contexto disponible.
¿Debo mencionar una carpeta entera?
Las @menciones se dirigen a archivos individuales. Para una tarea que abarca una carpeta completa, describir la carpeta y el patrón en prosa suele ser más económico en contexto que mencionar cada archivo dentro de ella.
¿Las @menciones reemplazan la explicación de lo que quiero hacer?
No. Una mención solo apunta al archivo; todavía necesitas describir el problema, el objetivo o el cambio que deseas en prosa junto con él.
¿Cuándo debería preferir la prosa a una @mención?
Cuando aún no sabes qué archivo es relevante, o cuando solo una pequeña parte de un archivo muy grande es importante; en ambos casos, dejar que Claude Code busque o describir solo la parte relevante cuesta menos que mencionar el archivo completo.
¿Las @menciones interactúan con CLAUDE.md?
Son independientes pero complementarias. CLAUDE.md proporciona memoria persistente del proyecto cada sesión; las @menciones acotan un prompt específico a archivos exactos para la tarea en cuestión.
¿Pueden las @menciones excesivas contribuir a la necesidad de /compact o /clear?
Sí. Menciones grandes repetidas a lo largo de una sesión larga son una de las fuentes comunes de hinchazón de la ventana de contexto, junto con archivos grandes leídos en su totalidad y resultados de herramientas verbosos.
¿Hay alguna diferencia entre mencionar un archivo una vez al principio de una conversación y mencionarlo de nuevo más tarde?
Cada mención introduce de forma independiente el contenido de ese archivo en el contexto en el punto en que se utiliza. Si el archivo no ha cambiado y todavía está fresco en la conversación, volver a mencionarlo más tarde agrega su contenido nuevamente en lugar de reutilizar la copia anterior.
Relacionados
- Qué Hace Realmente CLAUDE.md - memoria persistente del proyecto frente a referencias de archivos por prompt.
- Conceptos Básicos de Gestión de Contexto - dónde encajan las @menciones entre las herramientas principales de la sección.
- Auditar Qué Está Consumiendo Tu Ventana de Contexto de Claude Code - detectar cuándo las menciones contribuyen a la hinchazón.
- Por Qué Existen /compact y /clear - recuperar espacio de contexto después de una sesión con muchas menciones.
Versiones de Stack: Escrito contra la línea de modelos de Claude actual a partir de ~junio de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (el predeterminado) y Claude Haiku 4.5. Los nombres de los modelos, los precios y las características del producto cambian rápidamente; verifica los detalles actuales en platform.claude.com/docs antes de confiar en ellos.