Claude Code no ve los archivos del proyecto: por qué y qué hacer en 2026

Una situación familiar: le pides a Claude Code que corrija un archivo y te responde que no existe. O cambia en silencio algo completamente distinto de lo que querías. Abres la carpeta: el archivo está ahí, justo donde debería. Pero Claude parece no darse cuenta.

Casi siempre hay una sola razón, y no hay nada roto. Claude no ve los archivos de todo el ordenador. Solo puede acceder a la carpeta desde la que lo iniciaste. Iniciar en una carpeta hermana o por debajo de la raíz puede dejar archivos necesarios fuera del árbol de trabajo. Iniciar en un directorio padre, como la carpeta personal, amplía el alcance; no hace inaccesible un proyecto descendiente. Te explicaré paso a paso por qué funciona así y cómo darle a Claude acceso a los archivos que necesita. Cito los comandos y la configuración directamente de la documentación oficial de Claude Code, que consulté a principios de septiembre de 2026.

Encontrarás materiales adicionales sobre cómo configurar herramientas en la documentación de Ailoot.

¿Por qué Claude Code no ve algunos archivos del proyecto?#

De forma predeterminada, Claude Code trabaja con una sola carpeta: aquella en la que escribiste el comando claude e iniciaste la sesión. La documentación lo dice explícitamente.

Esta carpeta es su directorio de trabajo. Dentro de ella, Claude lee cualquier archivo sin hacer preguntas adicionales: editar un prompt, buscar código, leer un archivo específico; todo funciona de inmediato. Pero, de forma predeterminada, todo lo que queda fuera de esta carpeta está fuera de su alcance. Claude no buscará en una carpeta contigua, una carpeta un nivel más arriba o en otra unidad hasta que se lo permitas.

Por eso puede importar una discrepancia de directorio. Si tu proyecto es /Users/you/my-shop e inicias Claude desde /Users/you/other-project, una carpeta hermana, el index.html de my-shop queda fuera de ese árbol de trabajo. Iniciar desde /Users/you es otro caso: my-shop es descendiente y no resulta inaccesible solo por partir de la carpeta personal, aunque el contexto sea más amplio de lo previsto. Tener acceso a una carpeta tampoco significa haber leído ya todos sus archivos.

A continuación, te explicaré cómo comprobarlo y solucionarlo: primero confirmaremos desde qué carpeta se inició Claude y después le daremos acceso a los archivos que necesita de distintas maneras, desde una instrucción puntual hasta un ajuste permanente.

¿Cómo puedes comprobar desde qué carpeta se inició Claude Code?#

Antes de solucionar nada, asegúrate de que el problema realmente está en la carpeta. Es fácil comprobarlo. Pídele a Claude en el chat que muestre el directorio actual: ejecutará pwd, un comando seguro que solo muestra la ruta y no modifica nada.

pwd

La respuesta muestra el directorio de trabajo real. Compáralo con la ruta completa del proyecto: /Users/you/other-project es hermano de /Users/you/my-shop, mientras que /Users/you es su padre. El primer caso deja my-shop fuera del árbol de trabajo; el segundo lo incluye, pero no selecciona ese proyecto concreto como raíz.

La forma más sencilla de corregir esta diferencia es iniciar Claude directamente desde la carpeta del proyecto. Cierra la sesión actual, ve a la carpeta correcta en la terminal e inicia Claude desde allí:

# Sustituye esta ruta ilustrativa por la raíz real de tu proyecto.
cd /Users/you/my-shop
claude

Ahora my-shop será el directorio de trabajo y todos los archivos del proyecto estarán a la vista. La misma regla se aplica en un editor como VS Code: abre la carpeta que contiene el proyecto. No la carpeta que está un nivel más arriba ni todo el disco. La carpeta que abras determina qué considera Claude su directorio de trabajo.

Si reiniciar Claude resulta incómodo —por ejemplo, porque ya le has dado contexto en esta sesión y no quieres perderlo—, puedes añadir o cambiar carpetas sobre la marcha. Eso es lo que explican las dos secciones siguientes.

¿Cómo puedes mostrarle a Claude Code un archivo de una carpeta contigua?#

A veces, un proyecto no se encuentra en una sola carpeta. El código está en un lugar, las imágenes o los textos en una carpeta contigua y los componentes compartidos en otro sitio cercano. Reiniciar Claude en cada carpeta resulta incómodo. Es mejor darle acceso a la carpeta que necesita y mantener la carpeta principal como directorio de trabajo.

La forma más sencilla es hacerlo directamente en la sesión activa con el comando:

/add-dir ../assets

Escribe /add-dir y la ruta de la carpeta; Claude tendrá acceso inmediato a sus archivos en las mismas condiciones que a los de la carpeta principal. No volverá a pedir permiso: la carpeta añadida sigue las mismas reglas que el directorio de trabajo.

Si sabes de antemano que vas a trabajar con varias carpetas, concede acceso en cuanto se inicie Claude, usando la misma ruta, pero con una opción:

claude --add-dir ../assets

Y si siempre necesitas la misma carpeta contigua en un proyecto, no hace falta añadirla manualmente cada vez. El archivo de configuración settings.json tiene una clave llamada additionalDirectories. Enumera allí las rutas y se abrirán automáticamente cada vez que inicies Claude:

{
  "permissions": {
    "additionalDirectories": ["../assets", "../shared"]
  }
}

Una salvedad para Windows: no puedes añadir una carpeta de red con una ruta como \\server\shared; Claude no acepta ese tipo de rutas. Móntala como una unidad independiente con una letra de unidad y luego pasa esa letra con --add-dir. Las carpetas locales normales no tienen este problema.

¿Y si añadir una carpeta contigua no es suficiente y necesitas cambiarte a otra carpeta por completo? Para eso hay un comando independiente que veremos a continuación.

¿Cómo puedes cambiar Claude Code a otra carpeta durante una sesión?#

A veces, añadir una carpeta contigua no basta: necesitas cambiar la carpeta principal y pasar a otro proyecto sin perder el contexto que has acumulado. Usa el comando /cd:

/cd ../another-project

A partir de entonces, Claude tratará la nueva carpeta como su directorio de trabajo. Conservarás todo el historial de la conversación, pero cambiará la ubicación que Claude usa como referencia para los archivos. Claude también cargará el archivo de instrucciones CLAUDE.md de la nueva carpeta, si lo hay; es decir, se adaptará a las reglas del nuevo proyecto.

Hay algo que debes saber sobre la confianza: si todavía no has trabajado en esa carpeta, Claude te preguntará si confías en ella cuando te traslades allí. Es una medida de protección: un archivo de instrucciones de una carpeta desconocida podría contener cualquier cosa, así que Claude primero comprueba que sea tu proyecto. Confírmalo y continúa.

La diferencia entre los dos comandos es sencilla. /add-dir mantiene la carpeta principal como directorio de trabajo y abre además una carpeta contigua; resulta útil cuando las partes de un proyecto están repartidas. /cd traslada todo el directorio de trabajo a otra ubicación; resulta útil cuando cambias a otro proyecto. El comando /cd se introdujo en la versión 2.1.169, así que, si no aparece, actualiza Claude Code. Tengo una guía independiente sobre cómo actualizar Claude Code.

Que Claude Code vea los archivos es solo la base. El acceso a los archivos por sí solo no produce resultados estables. Estos dependen del contenido de esos archivos y de cómo construyas el contexto del proyecto.

¿Por qué Claude Code no ve un archivo en una subcarpeta?#

Es importante no confundir dos situaciones distintas. Una carpeta contigua (fuera del proyecto) es completamente inaccesible hasta que la añades. Una subcarpeta dentro del proyecto es diferente: Claude puede acceder a ella, pero no tiene presente su contenido desde el principio.

Así es como funciona. Cuando se inicia, Claude carga lo que hay en los niveles superiores del proyecto. Carga los archivos de las subcarpetas según los necesita, cuando va allí a leer algo. La documentación describe este comportamiento para los archivos de instrucciones, y la misma lógica se aplica al contexto en general.

Dicho de forma sencilla: el archivo de una subcarpeta muy anidada no ha desaparecido y es totalmente accesible. Claude simplemente aún no lo ha recordado porque no ha mirado allí. Por eso puede parecer que Claude «no ve» un archivo aunque esté ahí y sea accesible.

Puedes solucionarlo en una sola línea. Dale a Claude directamente la ruta del archivo, por ejemplo, src/components/header.jsx, o simplemente pídele que primero lo lea. En cuanto lo consulte, el archivo se incorporará al contexto y podrás trabajar con él como de costumbre. No hace falta cambiar ningún ajuste.

¿Dónde desaparecen los archivos del menú @ y qué tiene que ver .gitignore?#

Otra razón frecuente para pensar que Claude ha «perdido» un archivo es el selector de archivos. Cuando escribes @, aparece una lista que permite elegir un archivo cómodamente, sin tener que escribir su ruta completa. Pero la lista no muestra todo.

De forma predeterminada, el menú @ oculta los archivos incluidos en .gitignore. Ese archivo especifica qué no se debe añadir al repositorio compartido: carpetas de servicio, archivos que contienen contraseñas y ajustes de entorno, y resultados de compilación completados. El razonamiento está claro: normalmente no necesitas trabajar con estos archivos manualmente, así que solo llenarían la lista. Pero a veces sí necesitas uno de ellos y no aparece en el menú.

El ajuste respectGitignore controla esto. Está activado de forma predeterminada, así que los archivos de .gitignore no aparecen en el menú. Si quieres verlos, cámbialo a false:

{
  "respectGitignore": false
}

Puedes hacer lo mismo sin editar el archivo, usando el comando /config dentro de Claude Code. La opción se llama «Respect .gitignore in file picker». Desmárcala y los archivos ocultos volverán a aparecer en el menú.

Una salvedad importante: respectGitignore solo se aplica al menú @ y no tiene nada que ver con el acceso a los archivos. Aunque un archivo esté oculto en la lista, siempre puedes escribir manualmente su ruta y Claude lo leerá. El menú es una función práctica; no determina los límites de acceso.

¿Qué debes hacer si Claude Code no puede leer un archivo específico?#

Si la carpeta es definitivamente la correcta y el acceso está permitido, pero Claude sigue sin querer leer un archivo concreto, lo más probable es que esté restringido. Las restricciones se encuentran en el archivo de configuración settings.json y son de dos tipos.

El primer tipo consiste en una restricción específica para ciertos archivos. En la configuración, son las reglas deny, que suelen aplicarse al archivo .env, donde se guardan las claves y las contraseñas:

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)"
    ]
  }
}

Una regla así impide que Claude lea los archivos especificados, y es intencional. Las claves y las contraseñas no deberían acabar en una conversación con el modelo; por eso .env está protegido de forma predeterminada. Si Claude no quiere leer .env o un archivo similar que contiene secretos, es por diseño. No deberías quitar esta restricción sin una razón de peso.

El segundo tipo es una restricción general sobre todo lo que queda fuera de las carpetas de trabajo. El ajuste blockReadsOutsideWorkingDirectories la controla. Cuando está activado, Claude se niega a leer cualquier archivo fuera del directorio de trabajo, incluso si intentas abrirlo directamente. Si está configurado como true y necesitas un archivo externo, añade su carpeta con /add-dir o desactiva la restricción:

{
  "permissions": {
    "blockReadsOutsideWorkingDirectories": false
  }
}

Este ajuste se introdujo en la versión 2.1.257. Si ya lo has probado todo y el archivo sigue fuera de tu alcance, comprueba tanto deny como blockReadsOutsideWorkingDirectories.

¿Por dónde empezar si Claude Code no ve los archivos?#

Aquí tienes un plan breve que puedes seguir de principio a fin.

1. Comprueba la carpeta de trabajo: pídele a Claude que muestre el directorio actual con pwd y compáralo con la ubicación del proyecto.
2. Si las carpetas no coinciden, vuelve a iniciar Claude desde la correcta (cd project y luego claude) o desplázate allí con el comando /cd.
3. ¿Necesitas archivos de una carpeta contigua? Añádela con /add-dir o con la opción --add-dir al iniciar Claude.
4. ¿Un archivo de una subcarpeta no está en el contexto? Dale directamente su ruta a Claude o pídele que lea el archivo.
5. ¿Falta un archivo en el menú @? Se debe a .gitignore. Cambia respectGitignore a false o desmarca la casilla en /config.
6. ¿Hay un archivo específico bloqueado? Comprueba las reglas deny y blockReadsOutsideWorkingDirectories en settings.json.

En nueve de cada diez casos, el primer paso lo resuelve todo: Claude se inició desde la carpeta equivocada. El acceso a los archivos es la base, pero no construirá el proyecto por ti. En mi guía sobre el Second Brain en Claude Code explico en detalle cómo crear contexto para Claude, de modo que tenga presente todo el proyecto y no pierda el hilo.

Encontrarás materiales adicionales sobre cómo trabajar con herramientas en la documentación de Ailoot.