Claude Code en un monorepo o código grande: mantenerlo enfocado

Claude Code funciona con cualquier tamaño, pero en un repositorio con muchos paquetes los valores por defecto, pensados para proyectos pequeños, pueden llenar la ventana de contexto con instrucciones y lecturas de archivos que no tienen nada que ver con la tarea. Eso cuesta tokens y puede empeorar las respuestas. La solución es acotar a Claude a la parte del código que tocas. Estos son los ajustes que lo hacen, en el orden en que la mayoría los necesita.

1. Elige desde dónde arrancar Claude

Desde dónde ejecutas claude decide qué puede leer y editar sin un permiso extra, qué archivos CLAUDE.md se cargan al arrancar y qué ajustes de proyecto se aplican.

• Desde la raíz del repositorio: se alcanzan todos los archivos, al arrancar solo se carga el CLAUDE.md de la raíz y los de los subdirectorios se cargan a demanda. Bien cuando una tarea cruza paquetes.
• Desde un subdirectorio: solo se alcanza ese subárbol hasta que des más acceso, y se cargan el CLAUDE.md de ese directorio y los de todos sus padres. Bien cuando el trabajo vive en un paquete.

Una trampa, según la documentación tal como la leemos: .claude/settings.json no se hereda de los directorios padre como sí ocurre con los CLAUDE.md. Si arrancas desde packages/api/, cuenta el .claude/ propio de ese paquete. Mira qué archivo de ajustes manda.

2. Pon los CLAUDE.md por capas, por directorio

Un solo archivo gigante en la raíz o crece hasta cubrir todos los subsistemas, malgastando contexto en cosas ajenas a la tarea de hoy, o se queda tan vago que no sirve. Pártelo en dos niveles:

• CLAUDE.md de la raíz: reglas que valen en todas partes, como normas de código y convenciones de commits.
• Un CLAUDE.md en cada paquete o subsistema: las convenciones de ese stack, por ejemplo «copia .env.example a .env antes de ejecutar nada» o «nunca edites una migración después de fusionarla».

Arranca Claude en packages/api/ y carga ese archivo más el de la raíz, sin nada de packages/web/. Para comprobar qué se cargó de verdad, ejecuta /context y mira la lista de archivos de memoria. Sube estos archivos al repositorio para que los hereden tus compañeros y deja que el responsable de cada directorio mantenga el suyo.

La alternativa son las reglas por ruta en una carpeta central .claude/rules/, que se cargan cuando Claude toca un archivo que encaja con un patrón paths:. Los archivos por directorio dejan las convenciones junto al código; las reglas lo tienen todo en un sitio. Más sobre cómo elegir en CLAUDE.md, skill o hook y en memoria.

3. Excluye los CLAUDE.md que nunca necesitas

Si arrancas desde la raíz, Claude puede cargar a demanda el CLAUDE.md de cualquier subdirectorio. El ajuste claudeMdExcludes se salta archivos por patrón para que no se carguen nunca, lo que va bien con paquetes de otros equipos, código heredado y árboles de terceros. Los patrones se comparan con rutas absolutas, así que empieza con **/ los que parezcan relativos:

{
  "claudeMdExcludes": [
    "**/packages/web/**"
  ]
}

Ponlo en .claude/settings.local.json si es solo para ti. La lista es estática, no un interruptor por tarea: para centrarte mañana en otro paquete, arranca Claude desde ese paquete en vez de editar las exclusiones.

4. Que no lea código generado ni de terceros

Las búsquedas de contenido respetan .gitignore, así que node_modules/, dist/ y build/ ya quedan fuera si están ignorados. Lo que sí está en el repositorio, como un SDK de terceros o código generado que se sube, necesita reglas de denegación Read:

{
  "permissions": {
    "deny": [
      "Read(./**/dist/**/*)",
      "Read(./**/*.generated.*)",
      "Read(./**/vendor/**/*)"
    ]
  }
}

• Los patrones de directorio acaban en /**/* para bloquear el contenido pero dejar que Claude aún pueda listar o entrar en el directorio.
• Sube las reglas a .claude/settings.json para todo el equipo, o usa .claude/settings.local.json para ti. Los patrones relativos se anclan al directorio desde el que arrancas, así que si arrancas desde subdirectorios, escribe las reglas personales como rutas absolutas con //.
• Las reglas de denegación cubren las herramientas de archivos de Claude y los comandos de archivos que reconoce en Bash, como cat y grep con una ruta denegada como argumento. No cubren subprocesos que abren archivos por su cuenta, y un grep -r amplio sobre un directorio aún puede sacar archivos denegados. Tómalas como una barandilla fuerte, no como una caja fuerte. Para la sintaxis, mira la guía de permisos.

5. Que un servidor de lenguaje encuentre las definiciones

En un árbol grande, encontrar dónde se define o se usa un símbolo puede costar muchas lecturas de archivos. Los plugins de inteligencia de código conectan a Claude con un servidor de lenguaje para que salte a definiciones y referencias y vea los errores de tipos directamente. El marketplace oficial tiene plugins para TypeScript, Python, Go, Rust y otros, y cada uno necesita el binario del servidor de ese lenguaje en tu equipo. Cómo se instalan los plugins está en instalar plugins. Para activar uno a todo el equipo, añádelo al ajuste enabledPlugins del proyecto.

6. Worktrees más pequeños, acceso más amplio

• Worktrees parciales. claude --worktree arranca una sesión en un worktree de git nuevo, que por defecto trae todo el repositorio. El ajuste worktree.sparsePaths lista los directorios que se escriben en disco, más los archivos de la raíz, para que los worktrees arranquen antes y ocupen menos. Contexto en worktrees y sesiones en paralelo.
• Paquetes vecinos. Arrancando desde packages/api/, Claude solo puede tocar ese directorio. Para un cambio que también necesita packages/shared/, usa --add-dir o pon "permissions": { "additionalDirectories": ["../shared", "../web"] } en los ajustes de ese paquete. Las rutas relativas se resuelven desde donde arrancas Claude. Sirve igual para un segundo repositorio.

7. Cambios que cruzan paquetes

• Dale a Claude el cambio entero en una sola sesión, la edición compartida y sus usos a la vez, para que las decisiones detrás de cada edición sigan siendo coherentes.
• Planifica primero en modo plan. Claude escribe el plan en un archivo y Claude Code vuelve a inyectar ese archivo tras cada compactación, así que el plan sobrevive aunque el historial de la conversación no. Mira qué sobrevive a un compact.

Que no se pudra

• Revisa los cambios de CLAUDE.md en las pull requests, como cualquier documentación.
• Revísalos tras los grandes lanzamientos de modelos: una regla que esquivaba una limitación antigua puede pasar a ser puro lastre.
• Ejecuta /doctor sobre un CLAUDE.md que haya crecido demasiado.

Todas las guías están en el índice de guías, y la parte de tokens en gastar menos cuota. Esta página sigue la documentación de Anthropic sobre código grande tal como la leemos en octubre de 2026, acortada a propósito. No tenemos relación con Anthropic. La escribimos a partir de la documentación y no hemos probado todas las estructuras de repositorio. Los nombres de los ajustes y su comportamiento pueden cambiar, y donde esta página y la documentación no coincidan, manda la documentación.

La skill gratis loop-stop da a las tareas largas un límite y una regla de parada. Si quieres una segunda mirada a tu CLAUDE.md y a tus ajustes, el Tune-Up Kit es una lista de comprobación para eso (la ficha está en inglés).