¿Cuál usar en Cursor: @Codebase, @Docs o @Files? Guía de decisión con escenarios reales

El sistema de símbolos @ de Cursor parece sencillo: @Codebase, @Files, @Docs — un clic y la IA recibe contexto. Pero en la práctica muchos se quedan atascados en la misma duda: saben qué código buscan, pero no qué símbolo usar.

Si eliges mal, la IA mete montones de contenido irrelevante o no encuentra el archivo que realmente necesitas. Con el tiempo el historial se llena de consultas repetidas, gastas tokens a mansalva y el problema sigue sin quedar claro.

Este artículo no repite definiciones de funciones. Solo responde a una cosa: en escenarios concretos, ¿cómo decidir rápido qué símbolo @ usar? Al terminar tendrás un criterio claro y no tendrás que dudar cada vez.

1. Comparación central del sistema @: 6 funciones de un vistazo

Primero, una conclusión clave: según estadísticas de BetterLink Blog, el 80% del tiempo de desarrollo debería ir con @Codebase, no eligiendo archivos a mano. Suena exagerado, pero la lógica es simple: la ventaja de @Codebase no es buscar, sino dejar que la IA descubra código relacionado que podrías haber pasado por alto.

Estos 6 símbolos, ordenados de mayor a menor frecuencia de uso:

@Codebase (60-80%): búsqueda semántica en todo el repositorio. Haces una pregunta y la IA encuentra automáticamente los archivos, funciones y tipos más relevantes. No necesitas saber dónde está el archivo ni seleccionarlo manualmente. Encaja en entender la arquitectura, refactorizar y localizar problemas entre archivos. Consume más tokens porque el índice cubre todo el repositorio.

@Docs (10-15%): referencia documentación externa. Puedes usar documentación integrada de frameworks (React, Vue, Astro) o añadir fuentes personalizadas por URL. Encaja al usar bibliotecas recién publicadas, consultar APIs actualizadas o conectar la base de conocimiento del equipo.

@Files (5-10%): referencia el contenido completo de un archivo concreto. Cuando sabes el nombre del archivo o necesitas modificar configuración (como vite.config.ts). Si el archivo supera las 600 líneas, @Files es más preciso que @Codebase. El coste: más tokens, porque entra el archivo entero al contexto.

@Code (5-10%): referencia un fragmento de código exacto. Solo mete el trozo seleccionado, no el archivo completo. Encaja en optimizar lógica local, depurar unas pocas líneas y evitar contaminar el contexto a nivel de archivo. Es la opción que menos tokens consume.

@Folders (menos del 5%): referencia la estructura y una visión general del contenido de un directorio. Encaja en la refactorización de módulos, generar componentes nuevos y revisar coherencia arquitectónica. Consume muchos tokens porque implica varios archivos.

@Repo (escenarios específicos): contexto de repositorio. Encaja en proyectos multi-repo, análisis de historial de versiones y localización de problemas entre repositorios. Consumo de tokens moderado.

Estos 6 símbolos no son excluyentes; puedes combinarlos en la misma conversación. Por ejemplo: @Codebase para visión global, @Files para fijar archivos clave y @Docs para la documentación oficial. La clave: elige según el tipo de problema, no apiles símbolos a ciegas.

2. Árbol de decisión: tipo de problema → símbolo @

La lógica central cabe en una pregunta: ¿sabes dónde está el código?

Si no → @Codebase. Si sí → @Files o @Code. Si además falta documentación → añade @Docs.

En detalle:

Escenario 1: no sabes dónde está el archivo

Por ejemplo, refactorizas un proyecto Next.js y quieres cambiar el formato de respuesta de una API, pero no sabes dónde está la definición de tipos — puede estar en types/, en components/ o definida de paso en algún utils.ts.

Usa @Codebase. En Chat escribe: «Ayúdame a encontrar la definición del tipo ApiResponse y modificar el formato de respuesta.» La IA escaneará todo el repositorio, encontrará todas las referencias a ese tipo, incluido ese utils.ts que podrías haber ignorado.

Escenario 2: conoces el nombre del archivo

Por ejemplo, quieres cambiar la configuración de proxy en vite.config.ts o refactorizar una función en src/utils/auth.ts. La ruta está clara y el archivo es largo (más de 600 líneas).

Usa @Files. Haz clic en @Files, elige el archivo y la IA recibirá el contenido completo. Más preciso que @Codebase y evita montones de archivos «relacionados pero irrelevantes».

Escenario 3: necesitas documentación actualizada

Railway - Plataforma de despliegue moderna, sin ops complejas, en producción en minutos

Empezar ahora →Anuncio

Por ejemplo, usas una biblioteca publicada hace poco (la semana pasada) o consultas la API más reciente de un framework (que puede no estar en los datos de entrenamiento).

Usa @Docs. Escribe @Docs, elige documentación integrada o pega una URL. Importante: en el prompt enfatiza que use la sintaxis más reciente del documento, si no la IA puede recurrir a APIs de versiones antiguas de su memoria.

Escenario 4: solo te importa un fragmento de código

Por ejemplo, depuras la lógica de una función y solo quieres optimizar unas líneas, sin meter el archivo entero en el contexto.

Usa @Code. Selecciona el código, pulsa Cmd+K para edición inline o referencia con @Code en Chat. Menos tokens y contexto más limpio.

Escenario 5: refactorización de módulo o generación de componente nuevo

Por ejemplo, refactorizas todo components/ o generas un módulo nuevo en features/ manteniendo coherencia arquitectónica.

Usa @Folders. Obtiene la estructura del directorio y contenido clave; la IA entiende cómo está organizado el módulo y genera código alineado con el estilo existente.

Escenario 6: multi-repo o análisis de historial de versiones

Por ejemplo, el proyecto depende de varios repositorios Git o necesitas analizar el alcance de un commit.

Usa @Repo. Proporciona contexto de repositorio: historial de versiones y dependencias entre repos.

En resumen, el árbol de decisión se resume en: si no estás seguro de la ubicación, @Codebase; si la conoces, @Files/@Code; si falta documentación, @Docs. @Folders y @Repo son complementos para escenarios específicos.

3. @Codebase vs @Files: diferencias clave y casos reales

Estos dos símbolos confunden más a menudo. La diferencia es una sola: ¿la IA busca por ti o se lo indicas tú?

El valor de @Codebase no es «buscar», sino «descubrir». Haces una pregunta y la IA hace coincidencia semántica en todo el repositorio, devolviendo archivos, funciones y tipos relevantes. Lo clave: puede devolver archivos que no habías pensado. Por ejemplo, si preguntas «¿cómo modificar el formato de respuesta de la API?», la IA puede devolver:

• El handler de la API (lo esperado)
• El archivo de definición de tipos (quizá lo conocías)
• Un alias de tipo definido de paso en algún utils.ts (fácil de ignorar)
• Datos mock en un archivo de tests (puede que no lo hayas visto)

Esa es la ventaja central de @Codebase: la IA descubre código relacionado que podrías haber pasado por alto.

@Files aporta precisión: indicas el archivo y la IA recibe el contenido completo sin ambigüedad. El coste: debes saber dónde está y asumir más tokens (entra el archivo entero).

Caso real 1: modificar formato de respuesta de API (@Codebase encaja mejor)

Escenario: tienes una API en Next.js que devuelve:

// 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 });
}

Quieres cambiar el formato a { users, count }, pero no sabes dónde están las definiciones de tipos.

Con @Files tendrías que buscar manualmente route.ts, un posible types.ts y el componente frontend que llama a la API. Fácil omitir archivos.

Con @Codebase, en Chat escribe:

@Codebase
Ayúdame a modificar el formato de respuesta de la API de usuarios, de { data, total } a { users, count }.
Hay que actualizar todas las definiciones de tipos y las llamadas frontend relacionadas.

La IA puede devolver:

Archivos relacionados encontrados:
1. src/app/api/users/route.ts - handler de la API
2. src/types/api.ts - definición del tipo ApiResponse
3. src/components/UserList.tsx - componente frontend (llama a la API)
4. src/utils/mock.ts - datos mock de tests (también usa este formato)

De un vistazo ves que mock.ts también usa ese formato — un archivo que antes no habías notado.

Caso real 2: optimizar vite.config.ts (@Files encaja mejor)

Escenario: quieres modificar la configuración de proxy de Vite. La ruta está clara: vite.config.ts.

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

Quieres soportar varios entornos (desarrollo, pruebas, producción).

Aquí @Files encaja mejor porque:

1. La ubicación del archivo es clara
2. El contenido no es largo (suele ser 50-200 líneas)
3. No hace falta buscar entre archivos

En Chat escribe:

@Files vite.config.ts
Ayúdame a modificar la configuración de proxy para soportar varios entornos (desarrollo, pruebas, producción).
La configuración de entorno se lee de .env.development, .env.test y .env.production.

La IA recibirá vite.config.ts completo y propondrá algo como:

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

Resumen: si no conoces la ubicación o necesitas descubrir relaciones ocultas, @Codebase; si la conoces o el archivo es largo y necesitas entenderlo entero, @Files.

4. @Docs: bibliotecas nuevas e integración de documentación

@Docs resuelve un problema: los datos de entrenamiento de la IA no siguen el ritmo de la documentación.

Por ejemplo, usas una biblioteca publicada la semana pasada, o un framework cambió la API (nuevos hooks de React 19, Turbopack por defecto en Next.js 15). Los datos de entrenamiento pueden quedarse meses atrás y la IA genera código con APIs antiguas.

@Docs recupera en tiempo real la documentación que indicas, la parsea y la mete en el contexto. Al generar código, la IA prioriza la especificación más reciente del documento.

Cómo usarlo

1. En Chat escribe @Docs
2. Elige documentación integrada (React, Vue, Astro, Tailwind, Next.js, etc.)
3. O pega una URL para añadir una fuente personalizada

Las fuentes personalizadas son muy útiles. Si tu equipo tiene una base interna (Feishu, GitHub Wiki), añade la URL y la IA puede seguir las normas del equipo.

Caso real: nuevos hooks de React 19

Supón que quieres usar useOptimistic de React 19 pero no estás seguro de la sintaxis actual.

Alibaba Cloud - Opción preferida para desarrolladores, 15 % de descuento exclusivo en Lighthouse

Obtener 15% dto. →Anuncio

En Chat escribe:

@Docs React
Ayúdame a implementar una actualización optimista con el hook useOptimistic de React 19.
Escenario: botón de like; al hacer clic muestra +1 al instante y espera confirmación del servidor.

La IA consultará la documentación oficial de React, obtendrá la API actual de useOptimistic y generará código acorde:

import { useOptimistic } from 'react';

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

  async function handleClick() {
    addOptimisticLike(1); // muestra +1 al instante
    await onSubmit();     // espera confirmación del servidor
  }

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

Atención: los datos de entrenamiento pueden eclipsar @Docs

Hay un truco: la IA puede mezclar datos de entrenamiento y @Docs. Si la sintaxis antigua «pesa» más, puede mezclar APIs viejas y nuevas y generar código raro.

Solución: en el prompt enfatiza que use la sintaxis más reciente del documento.

Por ejemplo:

@Docs React
Usa la sintaxis más reciente del documento (React 19), no las APIs antiguas de los datos de entrenamiento.

Así la IA priorizará @Docs y reducirá el impacto de versiones antiguas.

¿Cuándo usar @Docs?

Regla simple: si la biblioteca o framework se publicó después de la fecha de corte de entrenamiento de la IA, o la API cambió mucho, usa @Docs.

Por ejemplo:

• React 19 (final de 2024, cambios importantes de API)
• Next.js 15 (final de 2024, Turbopack por defecto)
• Funciones recientes de Supabase (documentación en actualización continua)
• Normas internas del equipo (imposibles en datos de entrenamiento)

Si la biblioteca es estable (React 18, Vue 3, Tailwind 3) y los datos de entrenamiento la cubren bien, @Docs importa menos.

5. Buenas prácticas de gestión del contexto

Usar bien los símbolos @ es el primer paso; el segundo es gestionar el contexto. Muchos han caído en la trampa: cuanto más largo el historial, más se desvía la IA y el código generado ya no encaja con lo que querías.

Principio central: conversaciones cortas, funciones separadas

Tras completar una función, reinicia la conversación. No mezcles «refactorización de API», «corregir bug» y «añadir función nueva» en el mismo hilo.

¿Por qué? Cada función necesita contexto distinto. Al refactorizar una API la IA necesita tipos, handlers y llamadas frontend; al corregir un bug, logs, fragmentos de código y tests. Mezclado, el contexto se ensucia y la comprensión se difumina.

Operación simple: en la esquina superior derecha del panel Chat, «Clear Chat», o abre una conversación nueva con el atajo.

Edición pequeña vs tarea compleja

Edición pequeña (una línea, un parámetro): edición inline (Cmd+K). Selecciona el código, Cmd+K, escribe la instrucción. El archivo actual y la selección entran solos al contexto; no hace falta configurar nada más.

Tarea compleja (refactorización de módulo, componente nuevo): Chat + @-mentions. Primero @Codebase para visión global, luego @Files para archivos clave y una descripción clara de la tarea. Contexto más completo y respuestas más acertadas.

Optimizar el índice: .cursorignore para excluir ruido

El índice de @Codebase cubre todo el repositorio, pero no todos los archivos deben verse.

Por ejemplo:

• node_modules/ (dependencias, la IA no las necesita)
• dist/, build/ (artefactos compilados)
• .env, .env.local (configuración sensible)
• Recursos estáticos grandes (imágenes, vídeo)

Exclúyelos con .cursorignore. Mantenlo aparte de .gitignore. La pregunta es: ¿la IA necesita ver este archivo?

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

Así el índice de @Codebase es más preciso, las consultas son más rápidas (de 5-10 segundos a 2-3) y los resultados más relevantes.

Actualizar README.md con regularidad

Un hábito fácil de olvidar: documentar en README.md el estado y la estructura del proyecto.

¿Por qué? README.md es uno de los archivos clave del índice de @Codebase. Al entender la arquitectura, la IA lo consulta primero. Si el README explica bien:

• Estructura del proyecto (directorios)
• Módulos centrales (qué archivo hace qué)
• Cambios recientes (funciones nuevas, planes de refactor)

En tareas complejas la IA entiende antes el panorama global y repite menos consultas.

Ventaja Pro: índice más amplio

Cursor Pro puede indexar semánticamente todo el repositorio; en Free hay límites. Con más de 500 archivos, @Codebase en Pro suele ir notablemente mejor.

Eso no significa que Free sea inútil. Lo decisivo sigue siendo: gestionar el contexto, elegir bien los símbolos y excluir ruido. Pro es un extra, no una necesidad.

6. Preguntas frecuentes y soluciones

Problema 1: @Codebase no coincide con el repositorio

Síntoma: acabas de cambiar un archivo pero @Codebase devuelve contenido viejo. O un archivo que existe no aparece.

Causa: el índice no se actualizó.

Solución:

1. Cursor Settings → «Reindex Codebase» (reindexación forzada)
2. O quita la carpeta del proyecto y vuelve a añadirla (más drástico)

Espera 1-2 minutos; al terminar la indexación el problema desaparece.

Problema 2: @Codebase devuelve coincidencias incorrectas

Síntoma: preguntas «cómo modificar UserService» y la IA devuelve utils/user.ts en lugar de services/UserService.ts.

Causa: ambigüedad en la coincidencia semántica.

KiloClaw - OpenClaw gestionado para empresas: orquestación de agentes IA y enrutamiento inteligente

Empezar →Anuncio

Solución:

1. Usa @Files para indicar el archivo correcto
2. O especifica la ruta en el prompt: «modificar src/services/UserService.ts»

@Codebase descubre automáticamente, pero con margen de error. En tareas precisas, @Files.

Problema 3: la IA usa APIs antiguas aunque añadiste @Docs

Síntoma: añades @Docs React y el código sigue siendo estilo React 18.

Causa: la impronta de los datos de entrenamiento eclipsa @Docs.

Solución: enfatiza en el prompt:

@Docs React
Usa la sintaxis más reciente del documento (React 19), no las APIs antiguas de los datos de entrenamiento.

Con esa frase la IA priorizará @Docs.

Problema 4: @Codebase muy lento (5-10 segundos)

Síntoma: cada consulta tarda mucho.

Causa: índice demasiado grande (incluye node_modules, dist, etc.).

Solución: revisa .cursorignore y excluye lo innecesario:

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

Al reducir el alcance, la consulta baja a 2-3 segundos.

Problema 5: historial largo y la IA se desvía

Síntoma: ya habéis hablado de tres o cuatro funciones y las respuestas se alejan de lo que quieres.

Causa: contaminación del contexto — contextos de funciones distintas mezclados.

Solución: reinicia la conversación. Clear Chat en la esquina superior derecha del panel Chat. Una función por conversación; contexto más limpio.

Problema 6: consumo de tokens demasiado alto

Síntoma: cada conversación gasta muchos tokens y la cuota Pro se agota pronto.

Causa: elección incorrecta de símbolos; demasiado contenido irrelevante en el contexto.

Solución:

1. Ediciones pequeñas con Cmd+K (inline), sin @-mentions
2. Tareas precisas con @Files/@Code; evita que @Codebase devuelva montones de archivos «relacionados pero irrelevantes»
3. .cursorignore para excluir archivos grandes (node_modules, dist)

Principio del consumo de tokens: referencias precisas, evita búsquedas en todo el repositorio.

Resumen

El sistema @ de Cursor se resume en: si no estás seguro de la ubicación, @Codebase; si la conoces, @Files/@Code; si falta documentación, @Docs.

El 80% del tiempo de desarrollo debería ir con @Codebase. No es exageración: el valor real de @Codebase es descubrir — la IA encuentra código relacionado que podrías ignorar, como un alias de tipo en utils.ts o datos mock en un test.

Pero @Codebase no lo hace todo. Con archivos de más de 600 líneas o cuando conoces la ubicación, @Files es más preciso. Para depurar un fragmento pequeño, @Code consume menos tokens. Con bibliotecas nuevas o APIs recientes, añade @Docs.

La gestión del contexto importa igual. Conversaciones cortas, funciones separadas. Reinicia tras cada tarea; no dejes que el historial se vuelva un caos. Usa .cursorignore, actualiza README.md y la IA entenderá mejor el proyecto.

La próxima vez que desarrolles, pregúntate: ¿sé dónde está el archivo o necesito que la IA encuentre código relacionado? Si no estás seguro, empieza con @Codebase — te mostrará relaciones ocultas. Si estás seguro, referencia con precisión y evita contaminar el contexto.

Dominando estos símbolos, Cursor deja de ser una herramienta que devuelve montones de contenido y se convierte en un compañero de programación de verdad.