Qué contiene tu carpeta .claude

Tu carpeta .claude alberga dos tipos de cosas distintas: instrucciones que se cargan en el contexto de Claude al inicio de cada sesión (CLAUDE.md, rules/, skills/, agents/) y configuración que gobierna el comportamiento de la herramienta (settings.json, hooks, servidores MCP). Ambos tipos se reparten entre un directorio de proyecto que sí commiteas y un directorio ~/.claude en tu carpeta personal que nunca commiteas.

La carpeta además tiende a crecer sola. Aprobar una solicitud de permiso escribe un archivo que tú no creaste, /init deja caer un CLAUDE.md, y un pull request puede terminar arrastrando un .claude/settings.local.json lleno de las reglas de permiso de un solo desarrollador.

Este es un recorrido archivo por archivo: qué hace cada ruta, cuál gana cuando dos de ellas definen lo mismo, y un veredicto por archivo sobre si pertenece o no al repositorio.

¿Dónde están las dos ubicaciones .claude?

Claude Code lee dos raíces .claude. Una está en el proyecto, viaja con el repositorio y está pensada para todo el equipo; la otra, ~/.claude en tu carpeta personal, es solo tuya y te acompaña en todos los proyectos de la máquina. Esa separación es lo más útil que puedes interiorizar. La referencia del directorio de Claude Code traza la misma línea: commitea los archivos del proyecto y deja donde están los de la carpeta personal. En Windows la raíz personal está en %USERPROFILE%\.claude, y apuntar CLAUDE_CONFIG_DIR a otro sitio lo mueve todo.

my-project/
├── CLAUDE.md                    # instrucciones cargadas en cada sesión
├── CLAUDE.local.md              # preferencias privadas, en gitignore
├── .mcp.json                    # servidores MCP compartidos por el equipo
└── .claude/
    ├── settings.json            # permisos, hooks, env, modelo por defecto
    ├── settings.local.json      # tus overrides personales, en gitignore
    ├── rules/*.md               # instrucciones por tema, opcionalmente filtradas por ruta
    ├── skills/<name>/SKILL.md   # prompts reutilizables invocados con /name
    ├── commands/*.md            # prompts de un solo archivo, mismo mecanismo que las skills
    ├── agents/*.md              # definiciones de subagentes con su propio prompt y herramientas
    ├── workflows/*.js           # scripts de workflow guardados desde /workflows
    ├── output-styles/*.md       # conjuntos de instrucciones que ajustan cómo trabaja Claude
    └── agent-memory/<name>/     # memoria persistente para subagentes

~/.claude.json                   # estado de la app, OAuth, servidores MCP personales
~/.claude/
├── CLAUDE.md                    # tus instrucciones, en todos los proyectos
├── settings.json                # valores por defecto personales
├── rules/*.md                   # reglas de nivel de usuario, aplicadas a todos los proyectos
├── keybindings.json             # atajos de teclado personalizados
├── themes/*.json                # temas de color personalizados
├── plugins/                     # marketplaces clonados y datos por plugin
├── projects/<project>/memory/   # memoria automática que Claude escribe por sí mismo
└── .credentials.json            # credenciales de inicio de sesión

En la práctica, dos archivos absorben casi toda la edición: CLAUDE.md y settings.json. Todo lo demás es opcional.

CLAUDE.md, imports y reglas filtradas por ruta

CLAUDE.md es el archivo que Claude Code carga en contexto al inicio de cada sesión, y se lee desde cuatro ubicaciones: la política gestionada (managed policy), ~/.claude/CLAUDE.md, el proyecto (./CLAUDE.md o ./.claude/CLAUDE.md) y ./CLAUDE.local.md para notas personales. La documentación sobre memoria deja claro que estos archivos se apilan en lugar de competir: cada archivo que Claude Code encuentra se añade al contexto en secuencia, empezando por la raíz del sistema de archivos y bajando hasta tu directorio de trabajo, y dentro de un mismo directorio el CLAUDE.local.md entra después del CLAUDE.md. Un archivo en un directorio padre se carga al arrancar; uno en un subdirectorio espera hasta que Claude abra un archivo allí.

La sintaxis @path/to/file incorpora otro archivo, resuelto de forma relativa al archivo que lo importa, hasta cuatro saltos de profundidad. Dividir un archivo largo en imports lo ordena, pero no recupera nada de contexto, ya que todo lo importado también se expande al arrancar. El análisis de imports ignora cualquier cosa dentro de backticks o de un bloque delimitado, que es la forma de nombrar una ruta en tus instrucciones sin que el archivo se cargue.

Importan dos límites. La cifra de 200 líneas es un objetivo más que un tope: pasado ese punto, un archivo consume más contexto y Claude lo sigue con menos fiabilidad. El techo real son 4 MiB. Claude Code carga íntegro un CLAUDE.md de hasta ese tamaño y omite el que lo supere.

.claude/rules/*.md es la alternativa modular. Los archivos de reglas se descubren de forma recursiva, un tema cada uno. Si una regla no tiene frontmatter, se carga al arrancar y queda al mismo nivel que .claude/CLAUDE.md; si le das un campo paths, se mantiene fuera del contexto hasta que Claude toque un archivo que coincida con el glob.

---
paths:
  - "src/components/**/*.tsx"
---

Prefer function components with explicitly typed props.
Co-locate the test file beside the component it covers.

Las instrucciones contradictorias entre archivos se resuelven de forma arbitraria, así que ahí no hay ninguna regla que memorizar. Ejecuta /context o /memory para ver qué se cargó realmente y, si una instrucción realmente debe ejecutarse en un punto fijo, escríbela como un hook PreToolUse. Un hook se ejecuta como un comando de shell en un punto fijo de la sesión, lo hubiera elegido Claude o no.

¿Dónde encaja AGENTS.md?

Un repositorio que ya lleva AGENTS.md para otros agentes de codificación no necesita nada extra: Claude Code lee esos archivos por sí mismo, solos o junto a CLAUDE.md. Cuando el directorio de trabajo y sus padres no contienen ningún CLAUDE.md, lo que se carga es AGENTS.md. Qué archivos se cargan lo define “Project instructions” en /config, y esa opción solo aparece en sesiones que pueden obtener los feature flags de Anthropic, por lo que no está presente en Bedrock, Vertex ni Foundry.

Para una sesión que no puede cargar AGENTS.md, o cuando quieras conservar un CLAUDE.md existente, añade un CLAUDE.md junto a AGENTS.md que lo importe:

@AGENTS.md

## Claude Code

Run `pnpm typecheck` before proposing any change under `packages/api/`.

Un enlace simbólico también funciona cuando no necesitas contenido específico de Claude: ln -s AGENTS.md CLAUDE.md. Windows no crea uno sin privilegios de Administrador o el Modo Desarrollador, así que allí el import es la vía más segura. Un AGENTS.md leído directamente no aparece bajo Memory files en /context ni en /memory. En su lugar, la sesión imprime una línea “AGENTS.md loaded”.

No confundas AGENTS.md con CLAUDE.local.md. Este último es el complemento personal e ignorado por git de CLAUDE.md y no tiene nada que ver con la interoperabilidad entre herramientas.

¿Cuál es la diferencia entre skills/, commands/ y agents/?

Los commands y las skills funcionan sobre el mismo mecanismo y ambos responden a /name. La referencia de directorios orienta el trabajo nuevo hacia skills/<name>/SKILL.md, porque un directorio de skill puede empaquetar archivos de apoyo junto a las instrucciones, mientras que un command es un único archivo markdown. Un directorio commands/*.md existente sigue funcionando. Para saber cómo estructurar una skill para trabajo de frontend, consulta nuestra guía sobre las skills de Claude Code para flujos de trabajo de frontend.

agents/*.md contiene definiciones de subagentes, cada una con su propio prompt y lista de herramientas. Ambos directorios existen a nivel de proyecto y bajo ~/.claude, y ambos se detectan por su ubicación en lugar de por un registro en un archivo de configuración.

Precedencia de configuración en Claude Code: settings.json frente a settings.local.json

settings.json es el archivo compartido del proyecto y settings.local.json es tu override personal por proyecto, y cuando ambos definen la misma clave gana el archivo local. La referencia de settings establece cinco niveles de precedencia, de mayor a menor: managed settings, argumentos de línea de comandos, .claude/settings.local.json, .claude/settings.json y ~/.claude/settings.json. El JSON que pasas a --settings se sitúa justo por debajo de los managed settings y por encima de tus tres archivos propios.

Lo que despista a muchos es que no todas las claves siguen esa pila. Las claves de tipo lista, como permissions.allow, permissions.ask y permissions.deny, se combinan entre ámbitos en lugar de reemplazarse, así que una regla deny en el settings.json compartido de un compañero sigue actuando aunque tu archivo local permita la misma herramienta. Cuatro claves de modelo son la excepción a esa fusión. fallbackModel es una cadena ordenada, por lo que el archivo de mayor precedencia que la defina aporta el valor completo. modelPicker funciona igual, salvo que solo lee managed settings, --settings y los settings de usuario, e ignora la clave en los archivos de proyecto y locales (Claude Code v2.1.242 y posteriores). Una lista availableModels gestionada se aplica tal cual y tus añadidos se descartan, aunque entre los archivos de usuario, proyecto y local esos arrays sí se fusionan. modelSettings se resuelve modelo por modelo.

Archivo compartido:

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "cleanupPeriodDays": 30,
  "permissions": {
    "deny": ["Read(./.env)"]
  }
}

Archivo local:

{
  "cleanupPeriodDays": 7,
  "permissions": {
    "allow": ["Bash(npm run lint)"]
  }
}

La sesión resultante usa cleanupPeriodDays: 7, porque el archivo local tiene más precedencia que el compartido en una clave escalar. Ambas reglas de permisos siguen activas: npm run lint se ejecuta sin solicitud de confirmación y la lectura de .env sigue bloqueada. Los archivos de settings son JSON estricto: añade un comentario // o una coma final y el archivo no se podrá parsear. La línea $schema te da autocompletado en el editor y, como el esquema publicado a veces va por detrás de las versiones más recientes de la CLI, una advertencia sobre una clave documentada la semana pasada dice más del esquema que de tu archivo. Ejecuta /status para confirmar qué archivos de settings se cargaron.

¿Dónde viven los hooks y los servidores MCP?

Los hooks no son archivos aparte. Viven bajo la clave hooks de settings.json, en el ámbito en el que quieras que apliquen, y una edición surte efecto sin reiniciar la sesión. Los servidores MCP se dividen por audiencia: .mcp.json está en la raíz del proyecto, viaja con el repositorio y es la lista compartida del equipo. Los servidores MCP personales viven en ~/.claude.json, que además almacena el estado de la app, datos de OAuth y servidores de ámbito local indexados por ruta de proyecto, así que trátalo como estado de la máquina y no como un archivo de configuración que editas a mano.

Qué commitear y qué poner en gitignore

La primera vez que Claude Code escribe ese archivo local en un repositorio que aún no lo ignora, añade **/.claude/settings.local.json a tus exclusiones globales de git. Esa escritura es lo que ocurre cuando respondes “Yes, and don’t ask again” a una solicitud de permiso. Si creas el archivo a mano no se añade nada por ti, así que deja la entrada explícita:

# Claude Code personal config
# settings.local.json is usually auto-excluded already; this covers hand-created files
.claude/settings.local.json
CLAUDE.local.md

Los settings compartidos son también lo que ven las sesiones en la nube, ya que estas se ejecutan sobre un clon nuevo. Los archivos de usuario y locales se quedan en tu máquina y nunca llegan hasta ellas.

Todo lo que hay bajo ~/.claude es texto plano

Las transcripciones de sesión, la salida de las herramientas, el texto pegado y el registro de prompts history.jsonl aterrizan en disco como texto plano, con los permisos de archivo como única barrera. Si un comando imprimió un token durante una sesión, ese token está en alguna transcripción. .credentials.json guarda tus credenciales de inicio de sesión y sobrevive a la limpieza de retención, que por lo demás borra los archivos elegibles una vez superan cleanupPeriodDays: 30 días por defecto, 1 como mínimo, y 0 rechazado como valor inválido.

La carpeta es más pequeña de lo que parece una vez que la ordenas: las instrucciones se concatenan, los settings tienen precedencia, los permisos se fusionan y el directorio personal nunca entra en el control de versiones. Abre tu propio .claude/ frente al árbol de arriba, borra los archivos que nadie escribió a propósito y añade el bloque de dos líneas al .gitignore antes de que lo haga por ti el próximo pull request.

Preguntas frecuentes

¿Tengo que aprobar los servidores MCP que llegan en el .mcp.json commiteado por un compañero?

Sí. En una sesión interactiva Claude Code pregunta antes de usar cualquier servidor de ámbito de proyecto declarado en un .mcp.json, y cada desarrollador responde por su cuenta en lugar de una vez para todo el repositorio. Ejecuta claude mcp reset-project-choices para borrar esas respuestas. Los contextos no interactivos no pueden mostrar la solicitud: las ejecuciones de claude -p, las sesiones del Agent SDK y las sesiones en la nube cargan los servidores de ámbito de proyecto sin preguntar, así que usa disabledMcpjsonServers para bloquear un servidor en todos los modos de permisos.

¿Cómo sobrescribo un ajuste de Claude Code para una sola sesión sin editar un archivo?

Pasa --settings con una ruta a un archivo JSON o con una cadena JSON en línea. Se sitúa por debajo de los managed settings y por encima de tus archivos de usuario, proyecto y local. Algunas claves también tienen su propio flag o variable de entorno, y cuál gana se decide clave por clave: --model y /model se imponen sobre ANTHROPIC_MODEL, mientras que CLAUDE_CODE_EFFORT_LEVEL se impone sobre /effort.

¿Editar settings.json a mitad de sesión surte efecto de inmediato?

Algunas claves se recargan en caliente y otras se leen una sola vez al inicio de la sesión, así que una edición puede parecer ignorada hasta el siguiente arranque. Los permisos y los hooks se recargan sin reiniciar, mientras que model, effortLevel y modelSettings se leen una vez al inicio. Un cambio de outputStyle se aplica desde tu siguiente mensaje a partir de la v2.1.251, aunque en el terminal un archivo de estilo que crees o edites a mitad de sesión solo se detecta tras un reinicio. Si un valor sigue pareciendo incorrecto después de reiniciar, ejecuta /status y revisa la precedencia: un archivo de mayor ámbito como .claude/settings.local.json puede estar definiendo la misma clave.

¿Qué pierdo si borro la carpeta projects bajo ~/.claude?

Borrar projects/ elimina las transcripciones retenidas y puede impedirte reanudar sesiones pasadas, aunque las sesiones nuevas no se ven afectadas. El comando claude project purge es la alternativa dirigida: borra las transcripciones, la memoria automática, las tareas y las entradas de historial de archivos de un proyecto, las líneas de prompt correspondientes en history.jsonl y la entrada de ese proyecto en ~/.claude.json. Tanto shell-snapshots/ como backups/ se dejan donde están. Pasa -i para recorrer el plan de borrado paso a paso.