Por qué el código de Claude es tan estable: Una inmersión profunda de un desarrollador en su diseño de almacenamiento local

Últimamente, el código Claude está en todas partes. Los desarrolladores lo utilizan para acelerar el lanzamiento de funcionalidades, automatizar flujos de trabajo y crear prototipos de agentes que funcionan en proyectos reales. Lo que es aún más sorprendente es la cantidad de personas que no son programadores que también se han lanzado a crear herramientas, cablear tareas y obtener resultados útiles sin apenas configuración. Es raro ver que una herramienta de programación de IA se extienda tan rápidamente a tantos niveles de conocimientos.

Pero lo que realmente destaca es su estabilidad. Claude Code recuerda lo que ha ocurrido en las distintas sesiones, sobrevive a los bloqueos sin perder el progreso y se comporta más como una herramienta de desarrollo local que como una interfaz de chat. Esta fiabilidad proviene de cómo gestiona el almacenamiento local.

En lugar de tratar su sesión de codificación como un chat temporal, Claude Code lee y escribe archivos reales, almacena el estado del proyecto en el disco y registra cada paso del trabajo del agente. Las sesiones pueden reanudarse, inspeccionarse o revertirse sin conjeturas, y cada proyecto permanece limpiamente aislado, evitando los problemas de contaminación cruzada con los que tropiezan muchas herramientas de agentes.

En este post, vamos a echar un vistazo más de cerca a la arquitectura de almacenamiento detrás de esa estabilidad, y por qué juega un papel tan importante en hacer Claude Code sentir práctico para el desarrollo diario.

Desafíos a los que se enfrenta todo asistente de codificación de IA local

Antes de explicar cómo aborda Claude Code el almacenamiento, echemos un vistazo a los problemas comunes con los que suelen encontrarse las herramientas de codificación local de IA. Estos surgen de forma natural cuando un asistente trabaja directamente en tu sistema de archivos y mantiene el estado a lo largo del tiempo.

1. Los datos del proyecto se mezclan a través de los espacios de trabajo.

La mayoría de los desarrolladores cambian entre varios repos a lo largo del día. Si un asistente lleva el estado de un proyecto a otro, se hace más difícil entender su comportamiento y más fácil para él hacer suposiciones incorrectas. Cada proyecto necesita su propio espacio limpio y aislado para el estado y el historial.

2. Las caídas pueden provocar pérdidas de datos.

Durante una sesión de codificación, un asistente produce un flujo constante de datos útiles -ediciones de archivos, llamadas a herramientas, pasos intermedios-. Si estos datos no se guardan inmediatamente, un fallo o un reinicio forzado pueden eliminarlos. Un sistema fiable escribe el estado importante en el disco tan pronto como se crea para que el trabajo no se pierda inesperadamente.

3. No siempre está claro qué ha hecho realmente el agente.

Una sesión típica implica muchas pequeñas acciones. Sin un registro claro y ordenado de esas acciones, es difícil rastrear cómo llegó el asistente a un determinado resultado o localizar el paso en el que algo salió mal. Un historial completo hace que la depuración y la revisión sean mucho más manejables.

4. Deshacer errores requiere demasiado esfuerzo.

A veces, el asistente realiza cambios que no acaban de funcionar. Si no tiene una forma integrada de deshacer esos cambios, acabará buscando manualmente las ediciones en el repositorio. El sistema debería rastrear automáticamente lo que ha cambiado para que puedas deshacerlo limpiamente sin trabajo extra.

5. Diferentes proyectos necesitan diferentes configuraciones.

Los entornos locales varían. Algunos proyectos requieren permisos específicos, herramientas o reglas de directorio; otros tienen scripts o flujos de trabajo personalizados. Un asistente debe respetar estas diferencias y permitir configuraciones por proyecto, manteniendo al mismo tiempo un comportamiento coherente.

Los principios de diseño de almacenamiento detrás de Claude Code

El diseño de almacenamiento de Claude Code se basa en cuatro ideas sencillas. Pueden parecer simples, pero juntas abordan los problemas prácticos que surgen cuando un asistente de IA trabaja directamente en su máquina y en múltiples proyectos.

1. Cada proyecto tiene su propio almacenamiento.

Claude Code vincula todos los datos de sesión al directorio del proyecto al que pertenecen. Esto significa que las conversaciones, ediciones y registros permanecen en el proyecto del que proceden y no se filtran a otros. Mantener el almacenamiento separado hace que el comportamiento del asistente sea más fácil de entender y simplifica la inspección o eliminación de datos de un repositorio específico.

2. Los datos se guardan en el disco inmediatamente.

En lugar de mantener los datos de interacción en memoria, Claude Code los escribe en el disco tan pronto como se crean. Cada evento -mensaje, llamada a una herramienta o actualización de estado- se añade como una nueva entrada. Si el programa se bloquea o se cierra inesperadamente, casi todo sigue ahí. Este enfoque mantiene las sesiones duraderas sin añadir mucha complejidad.

3. Cada acción tiene un lugar claro en la historia.

Claude Code vincula cada mensaje y acción de la herramienta con el anterior, formando una secuencia completa. Este historial ordenado hace posible revisar cómo se desarrolló una sesión y rastrear los pasos que llevaron a un resultado específico. Para los desarrolladores, disponer de este tipo de traza facilita enormemente la depuración y la comprensión del comportamiento del agente.

4. Las ediciones de código son fáciles de revertir.

Antes de que el asistente actualice un archivo, Claude Code guarda una instantánea de su estado anterior. Si el cambio resulta ser erróneo, puede restaurar la versión anterior sin tener que rebuscar en el repositorio o adivinar qué ha cambiado. Esta simple red de seguridad hace que las ediciones basadas en IA sean mucho menos arriesgadas.

Disposición del almacenamiento local de Claude Code

Claude Code almacena todos sus datos locales en un único lugar: su directorio personal. Esto mantiene el sistema predecible y hace que sea más fácil de inspeccionar, depurar o limpiar cuando sea necesario. La estructura de almacenamiento se construye en torno a dos componentes principales: un pequeño archivo de configuración global y un directorio de datos más grande donde reside todo el estado del proyecto.

Dos componentes principales:

• ~/.claude.jsonAlmacena la configuración global y los accesos directos, incluidas las asignaciones de proyectos, la configuración del servidor MCP y los avisos utilizados recientemente.

• ~/.claude/El directorio de datos principal, donde Claude Code almacena conversaciones, sesiones de proyecto, permisos, plugins, habilidades, historial y datos de ejecución relacionados.

A continuación, vamos a examinar más detenidamente estos dos componentes principales.

(1) Configuración global: ~/.claude.json

Este archivo actúa como un índice más que como un almacén de datos. Registra en qué proyectos has trabajado, qué herramientas están vinculadas a cada proyecto y qué avisos has utilizado recientemente. Los datos de la conversación en sí no se almacenan aquí.

{
  "projects": {
    "/Users/xxx/my-project": {
      "mcpServers": {
        "jarvis-tasks": {
          "type": "stdio",
          "command": "python",
          "args": ["/path/to/run_mcp.py"]
        }
      }
    }
  },
  "recentPrompts": [
    "Fix the bug in auth module",
    "Add unit tests"
  ]
}

(2) Directorio principal de datos: ~/.claude/

El directorio ~/.claude/ es donde reside la mayor parte del estado local de Claude Code. Su estructura refleja algunas ideas centrales de diseño: aislamiento de proyectos, persistencia inmediata y recuperación segura de errores.

~/.claude/
├── settings.json                    # Global settings (permissions, plugins, cleanup intervals)
├── settings.local.json              # Local settings (machine-specific, not committed to Git)
├── history.jsonl                    # Command history
│
├── projects/                        # 📁 Session data (organized by project, core directory)
│   └── -Users-xxx-project/          # Path-encoded project directory
│       ├── {session-id}.jsonl       # Primary session data (JSONL format)
│       └── agent-{agentId}.jsonl    # Sub-agent session data
│
├── session-env/                     # Session environment variables
│   └── {session-id}/                # Isolated by session ID
│
├── skills/                          # 📁 User-level skills (globally available)
│   └── mac-mail/
│       └── SKILL.md
│
├── plugins/                         # 📁 Plugin management
│   ├── config.json                  # Global plugin configuration
│   ├── installed_plugins.json       # List of installed plugins
│   ├── known_marketplaces.json      # Marketplace source configuration
│   ├── cache/                       # Plugin cache
│   └── marketplaces/
│       └── anthropic-agent-skills/
│           ├── .claude-plugin/
│           │   └── marketplace.json
│           └── skills/
│               ├── pdf/
│               ├── docx/
│               └── frontend-design/
│
├── todos/                           # Task list storage
│   └── {session-id}-*.json          # Session-linked task files
│
├── file-history/                    # File edit history (stored by content hash)
│   └── {content-hash}/              # Hash-named backup directory
│
├── shell-snapshots/                 # Shell state snapshots
├── plans/                           # Plan Mode storage
├── local/                           # Local tools / node_modules
│   └── claude                       # Claude CLI executable
│   └── node_modules/                # Local dependencies
│
├── statsig/                         # Feature flag cache
├── telemetry/                       # Telemetry data
└── debug/                           # Debug logs

Esta disposición es intencionadamente simple: todo lo que genera Claude Code vive bajo un mismo directorio, organizado por proyecto y sesión. No hay ningún estado oculto disperso por su sistema, y es fácil de inspeccionar o limpiar cuando es necesario.

Cómo gestiona Claude Code la configuración

El sistema de configuración de Claude Code está diseñado en torno a una idea simple: mantener el comportamiento por defecto consistente en todas las máquinas, pero permitiendo que los entornos y proyectos individuales personalicen lo que necesiten. Para que esto funcione, Claude Code utiliza un modelo de configuración de tres capas. Cuando la misma configuración aparece en más de un lugar, siempre gana la capa más específica.

Los tres niveles de configuración

Claude Code carga la configuración en el siguiente orden, de menor a mayor prioridad:

┌─────────────────────────────────────────┐
│    Project-level configuration          │  Highest priority
│    project/.claude/settings.json        │  Project-specific, overrides other configs
├─────────────────────────────────────────┤
│    Local configuration                  │  Machine-specific, not version-controlled
│    ~/.claude/settings.local.json        │  Overrides global configuration
├─────────────────────────────────────────┤
│    Global configuration                 │  Lowest priority
│    ~/.claude/settings.json              │  Base default configuration
└─────────────────────────────────────────┘

Puede pensar en esto como si comenzara con valores predeterminados globales, luego aplicara ajustes específicos de la máquina y, finalmente, aplicara reglas específicas del proyecto.

A continuación veremos cada nivel de configuración en detalle.

(1) Configuración global: ~/.claude/settings.json

La configuración global define el comportamiento por defecto para Claude Code en todos los proyectos. Aquí es donde se establecen los permisos básicos, se habilitan los plugins y se configura el comportamiento de limpieza.

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": ["Read(**)", "Bash(npm:*)"],
    "deny": ["Bash(rm -rf:*)"],
    "ask": ["Edit", "Write"]
  },
  "enabledPlugins": {
    "document-skills@anthropic-agent-skills": true
  },
  "cleanupPeriodDays": 30
}

(2) Configuración local: ~/.claude/settings.local.json

La configuración local es específica para una sola máquina. No está pensada para ser compartida o verificada en el control de versiones. Esto la convierte en un buen lugar para claves API, herramientas locales o permisos específicos del entorno.

{
  "permissions": {
    "allow": ["Bash(git:*)", "Bash(docker:*)"]
  },
  "env": {
    "ANTHROPIC_API_KEY": "sk-ant-xxx"
  }
}

(3) Configuración a nivel de proyecto: project/.claude/settings.json

La configuración a nivel de proyecto sólo se aplica a un único proyecto y tiene la máxima prioridad. Aquí es donde se definen las reglas que deben aplicarse siempre que se trabaje en ese repositorio.

{
  "permissions": {
    "allow": ["Bash(pytest:*)"]
  }
}

Una vez definidas las capas de configuración, la siguiente pregunta es cómo resuelve Claude Code la configuración y los permisos en tiempo de ejecución.

Claude Code aplica la configuración en tres capas: comienza con valores por defecto globales, luego aplica anulaciones específicas de la máquina y finalmente aplica reglas específicas del proyecto. Cuando la misma configuración aparece en varios lugares, tiene prioridad la más específica.

Los permisos siguen un orden de evaluación fijo:

1. deny - siempre bloquea

2. ask - requiere confirmación

3. allow - se ejecuta automáticamente

4. default - se aplica sólo cuando ninguna regla coincide

De este modo, el sistema se mantiene seguro por defecto, sin dejar de ofrecer a los proyectos y máquinas individuales la flexibilidad que necesitan.

Almacenamiento de sesiones: Cómo persiste en Claude Code el núcleo de los datos de interacción

En Claude Code, las sesiones son la unidad central de datos. Una sesión captura toda la interacción entre el usuario y la IA, incluyendo la conversación en sí, las llamadas a las herramientas, los cambios en los archivos y el contexto relacionado. La forma en que se almacenan las sesiones tiene un impacto directo en la fiabilidad, depurabilidad y seguridad general del sistema.

Mantener los datos de sesión separados para cada proyecto

Una vez definidas las sesiones, la siguiente cuestión es cómo las almacena Claude Code para mantener los datos organizados y aislados.

Claude Code aísla los datos de sesión por proyecto. Las sesiones de cada proyecto se almacenan en un directorio derivado de la ruta de archivo del proyecto.

La ruta de almacenamiento sigue este patrón

~/.claude/projects/ + path-encoded project directory

Para crear un nombre de directorio válido, los caracteres especiales como /, espacios y ~ se sustituyen por -.

Por ejemplo:

/Users/bill/My Project → -Users-bill-My-Project

Este enfoque garantiza que los datos de sesión de diferentes proyectos nunca se mezclen y puedan gestionarse o eliminarse por proyecto.

Por qué las sesiones se almacenan en formato JSONL

Claude Code almacena los datos de sesión utilizando JSONL (Líneas JSON) en lugar de JSON estándar.

En un archivo JSON tradicional, todos los mensajes están agrupados dentro de una gran estructura, lo que significa que todo el archivo tiene que ser leído y reescrito cada vez que cambia. En cambio, JSONL almacena cada mensaje como su propia línea en el archivo. Una línea equivale a un mensaje, sin envoltorio externo.

Aspecto	JSON estándar	JSONL (Líneas JSON)
Cómo se almacenan los datos	Una gran estructura	Un mensaje por línea
Cuándo se guardan los datos	Normalmente al final	Inmediatamente, por mensaje
Impacto del fallo	Puede romperse todo el archivo	Sólo afecta a la última línea
Escritura de nuevos datos	Reescribir todo el fichero	Añadir una línea
Uso de memoria	Cargar todo	Leer línea por línea

JSONL funciona mejor en varios aspectos clave:

• Almacenamiento inmediato: Cada mensaje se escribe en el disco en cuanto se genera, en lugar de esperar a que termine la sesión.

• Resistente a fallos: si el programa se bloquea, sólo se pierde el último mensaje inacabado. Todo lo escrito antes permanece intacto.

• Añadidos rápidos: Los mensajes nuevos se añaden al final del fichero sin leer ni reescribir los datos existentes.

• Bajo consumo de memoria: Los archivos de sesión pueden leerse línea a línea, por lo que no es necesario cargar todo el archivo en la memoria.

Un archivo de sesión JSONL simplificado tiene el siguiente aspecto:

{"type":"user","message":{"role":"user","content":"Hello"},"timestamp":"2026-01-05T10:00:00Z"}
{"type":"assistant","message":{"role":"assistant","content":[{"type":"text","text":"Hi!"}]}}
{"type":"user","message":{"role":"user","content":"Help me fix this bug"}}

Tipos de mensajes de sesión

Un archivo de sesión registra todo lo que sucede durante una interacción con Claude Code. Para hacerlo con claridad, utiliza diferentes tipos de mensajes para diferentes tipos de eventos.

• Los mensajes de usuario representan nuevas entradas en el sistema. Esto incluye no sólo lo que escribe el usuario, sino también los resultados devueltos por las herramientas, como la salida de un comando shell. Desde el punto de vista de la IA, ambas son entradas a las que debe responder.

• Los mensajes del asistente recogen lo que Claude hace como respuesta. Estos mensajes incluyen el razonamiento de la IA, el texto que genera y las herramientas que decide utilizar. También registran detalles de uso, como el recuento de tokens, para ofrecer una imagen completa de la interacción.

• Las instantáneas del historial de archivos son puntos de control de seguridad que se crean antes de que Claude modifique cualquier archivo. Al guardar primero el estado original del archivo, Claude Code permite deshacer los cambios si algo sale mal.

• Los resúmenes ofrecen una visión concisa de la sesión y están vinculados al resultado final. Facilitan la comprensión de la sesión sin necesidad de repetir cada paso.

Juntos, estos tipos de mensajes registran no sólo la conversación, sino la secuencia completa de acciones y efectos que se producen durante una sesión.

Para concretar, veamos algunos ejemplos de mensajes de usuario y mensajes de asistente.

(1) Ejemplo de mensajes de usuario:

{
  "type": "user",
  "uuid": "7d90e1c9-e727-4291-8eb9-0e7b844c4348",
  "parentUuid": null,
  "sessionId": "e5d52290-e2c1-41d6-8e97-371401502fdf",
  "timestamp": "2026-01-05T10:00:00.000Z",
  "message": {
    "role": "user",
    "content": "Analyze the architecture of this project"
  },
  "cwd": "/Users/xxx/project",
  "gitBranch": "main",
  "version": "2.0.76"
}

(2) Ejemplo de mensajes del asistente:

{
  "type": "assistant",
  "uuid": "e684816e-f476-424d-92e3-1fe404f13212",
  "parentUuid": "7d90e1c9-e727-4291-8eb9-0e7b844c4348",
  "message": {
    "role": "assistant",
    "model": "claude-opus-4-5-20251101",
    "content": [
      {
        "type": "thinking",
        "thinking": "The user wants to understand the project architecture, so I need to check the directory structure first..."
      },
      {
        "type": "text",
        "text": "Let me take a look at the project structure first."
      },
      {
        "type": "tool_use",
        "id": "toolu_01ABC",
        "name": "Bash",
        "input": {"command": "ls -la"}
      }
    ],
    "usage": {
      "input_tokens": 1500,
      "output_tokens": 200,
      "cache_read_input_tokens": 50000
    }
  }
}

Cómo se vinculan los mensajes de sesión

Claude Code no almacena los mensajes de sesión como entradas aisladas. En su lugar, los enlaza para formar una clara cadena de acontecimientos. Cada mensaje incluye un identificador único (uuid) y una referencia al mensaje que le precede (parentUuid). Esto permite ver no sólo lo que ha ocurrido, sino por qué ha ocurrido.

Una sesión comienza con un mensaje de usuario, que inicia la cadena. Cada respuesta de Claude apunta al mensaje que la causó. Las llamadas a las herramientas y sus resultados se añaden de la misma manera, con cada paso vinculado al anterior. Cuando finaliza la sesión, se adjunta un resumen al mensaje final.

Dado que cada paso está conectado, Claude Code puede reproducir la secuencia completa de acciones y comprender cómo se produjo un resultado, lo que facilita enormemente la depuración y el análisis.

Cambios en el código fáciles de deshacer con instantáneas de archivos

Las ediciones generadas por la IA no siempre son correctas, y a veces van en la dirección completamente equivocada. Para que sea seguro experimentar con estos cambios, Claude Code utiliza un sencillo sistema de instantáneas que le permite deshacer las ediciones sin tener que rebuscar en los diffs o limpiar manualmente los archivos.

La idea es sencilla: antes de que Claude Code modifique un archivo, guarda una copia del contenido original. Si la edición resulta ser un error, el sistema puede restaurar la versión anterior al instante.

¿Qué es una instantánea del historial de archivos?

Una instantánea del historial de archivos es un punto de control creado antes de que se modifiquen los archivos. Registra el contenido original de cada archivo que Claude está a punto de editar. Estas instantáneas sirven como fuente de datos para las operaciones de deshacer y retroceder.

Cuando un usuario envía un mensaje que puede modificar archivos, Claude Code crea una instantánea vacía para ese mensaje. Antes de editar, el sistema realiza una copia de seguridad del contenido original de cada archivo de destino en la instantánea y, a continuación, aplica las modificaciones directamente al disco. Si el usuario desencadena la acción de deshacer, Claude Code restaura el contenido guardado y sobrescribe los archivos modificados.

En la práctica, el ciclo de vida de una edición que se puede deshacer es el siguiente:

1. Elusuario envía un mensajeClaudeCode crea un nuevo registro vacío en file-history-snapshot.

2. Claude se prepara para modificar los archivosElsistema identifica qué archivos serán editados y realiza una copia de seguridad de su contenido original en trackedFileBackups.

3. Claude ejecuta laediciónSe realizan las operaciones deedicióny escritura, y el contenido modificado se escribe en el disco.

4. El usuario desencadena la acción de deshacerElusuario pulsa Esc + Esc, indicando que los cambios deben revertirse.

5. Se restaura el contenido originalClaudeCode lee el contenido guardado de trackedFileBackups y sobrescribe los archivos actuales, completando el deshacer.

Por qué funciona Deshacer: Las instantáneas guardan la versión antigua

Deshacer en Claude Code funciona porque el sistema guarda el contenido original del archivo antes de que se produzca cualquier edición.

En lugar de intentar revertir los cambios a posteriori, Claude Code adopta un enfoque más sencillo: copia el archivo tal y como existía antes de la modificación y almacena esa copia en trackedFileBackups. Cuando el usuario activa la acción de deshacer, el sistema restaura esta versión guardada y sobrescribe el archivo editado.

El diagrama siguiente muestra este flujo paso a paso:

┌─────────────────────────┐
│    before edit,  app.py │
│    print("old")         │───────→  Backed up into snapshot trackedFileBackups
└─────────────────────────┘
↓
┌──────────────────────────┐
│   After Claude edits     │
│    print(“new”)          │───────→  Written to disk (overwrites the original file)
└──────────────────────────┘
↓
┌──────────────────────────┐
│    User triggers undo    │
│    Press   Esc + Esc     │───────→ Restore “old” content to disk from snapshot
└──────────────────────────┘

Aspecto interno de una instantánea del historial de archivos

La instantánea se almacena como un registro estructurado. Captura metadatos sobre el mensaje del usuario, la hora de la instantánea y, lo que es más importante, un mapa de los archivos con su contenido original.

El ejemplo siguiente muestra un único registro de file-history-snapshot creado antes de que Claude edite ningún archivo. Cada entrada de trackedFileBackups almacena el contenido previo a la edición de un archivo, que posteriormente se utiliza para restaurar el archivo durante una operación de deshacer.

{
  "type": "file-history-snapshot",
  "messageId": "7d90e1c9-e727-4291-8eb9-0e7b844c4348",
  "snapshot": {
    "messageId": "7d90e1c9-e727-4291-8eb9-0e7b844c4348",
    "trackedFileBackups": {
      "/path/to/file1.py": "Original file content\ndef hello():\n    print('old')",
      "/path/to/file2.js": "// Original content..."
    },
    "timestamp": "2026-01-05T10:00:00.000Z"
  },
  "isSnapshotUpdate": false
}

Dónde se almacenan las instantáneas y cuánto tiempo se conservan

• Dónde se almacenan los metadatos de las instantáneas: Los registros de instantáneas están vinculados a una sesión específica y se guardan como archivos JSONL en~/.claude/projects/-path-to-project/{session-id}.jsonl.

• Dónde se guarda la copia de seguridad del contenido original de los archivos: El contenido previo a la edición de cada archivo se almacena por separado por hash de contenido en~/.claude/file-history/{content-hash}/.

• Cuánto tiempo se conservan lasinstantáneas por defecto: Los datos de las instantáneas se conservan durante 30 días, de acuerdo con la configuración global de cleanupPeriodDays.

• Cómo cambiar el periodo de retención: El número de días de retención se puede ajustar a través del campo cleanupPeriodDays en ~/.claude/settings.json.

Comandos relacionados

Comando / Acción	Descripción
Esc + Esc	Deshacer la ronda más reciente de ediciones de archivos (más utilizado)
/retroceso	Volver a un punto de control especificado previamente (instantánea)
/diff	Ver las diferencias entre el archivo actual y la instantánea de copia de seguridad

Otros directorios importantes

(1) plugins/ - Gestión de complementos

El directorio plugins/ almacena complementos que proporcionan a Claude Code capacidades adicionales.

Este directorio almacena qué plugins están instalados, de dónde provienen y las habilidades extra que esos plugins proporcionan. También guarda copias locales de los plugins descargados para que no tengan que ser recuperados de nuevo.

~/.claude/plugins/
├── config.json
│   Global plugin configuration (e.g., enable/disable rules)
├── installed_plugins.json
│   List of installed plugins (including version and status)
├── known_marketplaces.json
│   Plugin marketplace source configuration (e.g., Anthropic official marketplace)
├── cache/
│   Plugin download cache (avoids repeated downloads)
└── marketplaces/
    Marketplace source storage
    └── anthropic-agent-skills/
        Official plugin marketplace
        ├── .claude-plugin/
        │   └── marketplace.json
        │       Marketplace metadata
        └── skills/
            Skills provided by the marketplace
            ├── pdf/
            │   PDF-related skills
            ├── docx/
            │   Word document processing skills
            └── frontend-design/
                Frontend design skills

(2) skills/ - Donde se almacenan y aplican las habilidades

En Claude Code, una habilidad es una pequeña capacidad reutilizable que ayuda a Claude a realizar una tarea específica, como trabajar con PDFs, editar documentos o seguir un flujo de trabajo de codificación.

No todas las habilidades están disponibles en todas partes. Algunas se aplican globalmente, mientras que otras están limitadas a un único proyecto o son proporcionadas por un plugin. Claude Code almacena las habilidades en diferentes ubicaciones para controlar dónde puede utilizarse cada habilidad.

La jerarquía que se muestra a continuación indica cómo se clasifican las habilidades por ámbito, desde las disponibles globalmente hasta las específicas de un proyecto y las proporcionadas por un plugin.

Nivel	Ubicación de almacenamiento	Descripción
Usuario	~/.claude/skills/	Disponible globalmente, accesible por todos los proyectos
Proyecto	proyecto/.claude/habilidades/	Disponible sólo para el proyecto actual, personalización específica del proyecto
Plugin	~/.claude/plugins/mercados/*/habilidades/	Instalado con plugins, depende del estado de habilitación del plugin

(3) todos/ - Almacenamiento de listas de tareas

El directorio todos/ almacena listas de tareas que Claude crea para realizar un seguimiento del trabajo durante una conversación, como pasos a completar, elementos en curso y tareas completadas.

Las listas de tareas se guardan como archivos JSON en~/.claude/todos/{session-id}-*.json. Cada nombre de archivo incluye el ID de sesión, que vincula la lista de tareas a una conversación específica.

El contenido de estos archivos procede de la herramienta TodoWrite e incluye información básica sobre la tarea, como su descripción, estado actual, prioridad y metadatos relacionados.

(4) local/ - Tiempo de ejecución local y herramientas

El directorio local/ contiene los archivos centrales que Claude Code necesita para ejecutarse en su máquina.

Esto incluye el ejecutable de línea de comandos claude y el directorio node_modules/ que contiene sus dependencias de tiempo de ejecución. Al mantener estos componentes locales, Claude Code puede ejecutarse de forma independiente, sin depender de servicios externos o instalaciones en todo el sistema.

（5）Directorios de apoyo adicionales

• shell-snapshots/: Almacena instantáneas del estado de la sesión de shell (como el directorio actual y las variables de entorno), permitiendo la reversión de operaciones de shell.

• plans/: Almacena los planes de ejecución generados por el modo Plan (por ejemplo, desgloses paso a paso de tareas de programación de varios pasos).

• statsig/: Almacena en caché las configuraciones de los indicadores de características (por ejemplo, si las nuevas características están habilitadas) para reducir las solicitudes repetidas.

• telemetry/: Almacena datos telemétricos anónimos (como la frecuencia de uso de las funciones) para optimizar el producto.

• debug/: Almacena los registros de depuración (incluidas las pilas de errores y las trazas de ejecución) para facilitar la resolución de problemas.

Conclusión

Después de escarbar en cómo Claude Code almacena y gestiona todo localmente, la imagen se vuelve bastante clara: la herramienta se siente estable porque la base es sólida. Nada del otro mundo, sólo ingeniería bien pensada. Cada proyecto tiene su propio espacio, cada acción se anota y se hace una copia de seguridad de las ediciones de los archivos antes de que nada cambie. Es el tipo de diseño que hace tranquilamente su trabajo y te permite centrarte en el tuyo.

Lo que más me gusta es que aquí no hay nada místico. Claude Code funciona bien porque lo básico está bien hecho. Si alguna vez ha tratado de construir un agente que toca archivos reales, usted sabe lo fácil que es que las cosas se caigan a pedazos - el estado se mezcla, los accidentes borran el progreso, y deshacer se convierte en una conjetura. Claude Code evita todo eso con un modelo de almacenamiento que es simple, consistente y difícil de romper.

Para los equipos que crean agentes de IA locales o locales, especialmente en entornos seguros, este enfoque muestra cómo un almacenamiento y una persistencia sólidos hacen que las herramientas de IA sean fiables y prácticas para el desarrollo diario.

Si está diseñando agentes de IA locales u on-prem y desea hablar sobre la arquitectura de almacenamiento, el diseño de sesiones o la reversión segura con más detalle, no dude en unirse a nuestro canal de Slack. También puede reservar una sesión individual de 20 minutos a través de Milvus Office Hours para obtener orientación personalizada.