23 de marzo de 2026

Claude Code: Domina el manejo de sesiones, memoria y permisos


En el artículo anterior vimos qué es Claude Code, cómo instalarlo y los conceptos básicos de contexto, memoria y permisos. Si ya lo tienes instalado y has hecho tus primeras pruebas, probablemente te has topado con la frustración número uno de todo developer que empieza a usarlo seriamente: cerrar la terminal y perder todo el contexto que habías acumulado en una sesión larga.

En este artículo vamos a resolver exactamente eso. Veremos cómo funciona el sistema de sesiones de Claude Code en profundidad: cómo guardarlas, cómo retomar una sesión anterior, cómo nombrarlas para encontrarlas después, cómo ramificarlas para experimentar sin miedo, y cómo el sistema de checkpoints te permite deshacer cambios con precisión quirúrgica. También veremos cómo inspeccionar el contexto activo y qué herramientas tienes para gestionarlo.

Sin más, vamos al tema.


Contenido

  1. Cómo se guardan las sesiones automáticamente
  2. Retomar una sesión: --continue y --resume
  3. Nombrar y organizar tus sesiones
  4. Ramificar una sesión con /fork
  5. Checkpoints y /rewind: deshacer sin miedo
  6. Ver y gestionar el contexto activo
  7. Memoria: guardar lo importante entre sesiones
  8. Exportar y compartir una sesión
  9. Un flujo de trabajo completo
  10. Conclusión

Cómo se guardan las sesiones automáticamente

Empecemos por algo que mucha gente no sabe: Claude Code guarda cada sesión de forma automática, sin que hagas nada. No hay un botón de "guardar", no hay que ejecutar ningún comando. Todo lo que ocurre en una sesión — los mensajes, los resultados de herramientas, los archivos leídos, los comandos ejecutados — queda almacenado en disco en el directorio ~/.claude/projects/.

La forma en que organiza ese directorio es relevante, porque determina qué sesiones aparecen disponibles cuando quieres retomar el trabajo. Cada proyecto tiene su propio subdirectorio, identificado por la ruta de trabajo codificada: 

~/.claude/
├── history.jsonl           ← historial global de todos tus prompts
├── settings.json           ← configuración global
└── projects/
    ├── -Users-tu-mi-proyecto/    ← sesiones del proyecto en /Users/tu/mi-proyecto
    │   ├── abc123-def456.jsonl   ← una sesión
    │   └── xyz789-aaa111.jsonl   ← otra sesión
    └── -Users-tu-otro-proyecto/
        └── bbb222-ccc333.jsonl

El nombre del subdirectorio es la ruta absoluta de tu proyecto con cada carácter no alfanumérico reemplazado por un guión. Así que /Users/tu/mi-proyecto se convierte en -Users-tu-mi-proyecto. Esto es importante por una razón práctica: si ejecutas claude desde un directorio diferente al original, el agente no encontrará las sesiones anteriores de tu proyecto. Siempre arranca Claude Code desde la raíz del proyecto.

Tip: Las sesiones y sus checkpoints se conservan durante 30 días y después se limpian automáticamente. Si tienes una sesión con contexto valioso que quieres conservar más tiempo, usa /export para guardarla como texto plano.

Retomar una sesión: --continue y --resume

Aquí está la respuesta a la frustración que mencioné al principio. Claude Code tiene dos formas de retomar trabajo anterior, y cada una sirve para un escenario diferente.

--continue: retomar la más reciente

Si cerraste la terminal y quieres seguir exactamente donde estabas, sin pensar mucho: 

claude --continue
# Forma corta equivalente:
claude -c

Esto carga la sesión más reciente del directorio actual con todo su contexto intacto: mensajes, resultados de comandos, archivos que leyó, decisiones que tomaron. Es como si nunca hubieras cerrado la terminal.

Un caso especial útil: si Claude se colgó o dejó de responder y tuviste que interrumpirlo, --continue retoma la sesión y reintenta el último request sin perder el historial.

--resume: elegir una sesión específica

Cuando tienes varias sesiones activas o quieres volver a algo de hace unos días: 

# Abre un picker interactivo con las sesiones del proyecto actual
claude --resume
# Forma corta:
claude -r
 
# Retomar una sesión específica por su ID
claude --resume abc123-def456

El picker interactivo que abre --resume sin argumentos es sorprendentemente útil. Muestra cada sesión con metadatos: rama de Git en la que trabajabas, número de mensajes, timestamp y una preview del primer mensaje. Desde ahí puedes navegar con las flechas y tienes dos atajos de teclado importantes:

  • P — Preview de la sesión antes de abrirla
  • R — Renombrar la sesión directamente desde el picker

--from-pr: retomar la sesión vinculada a un PR

Este es uno de esos comandos que muchos no conocen pero que son genuinamente útiles. Cuando creas un Pull Request usando gh pr create dentro de una sesión de Claude Code, la sesión queda vinculada automáticamente a ese PR. Semanas después, si necesitas retomar el contexto de ese trabajo: 

claude --from-pr 47
# Retoma la sesión vinculada al PR #47 con todo su contexto

Para retomar una sesión desde dentro de una sesión ya activa (por ejemplo, para cambiar de tarea sin salir), usa el comando interno: 

/resume
# Abre el picker desde dentro de la sesión activa

Nombrar y organizar tus sesiones

Por defecto, Claude Code nombra las sesiones con el primer mensaje que escribiste. Eso está bien cuando tienes dos o tres sesiones, pero cuando llevas semanas trabajando en varios features y bugs en paralelo, el picker empieza a parecerse a esto:

[2025-03-10] "explícame cómo funciona este módulo"
[2025-03-11] "hay un NullPointerException en el servicio..."
[2025-03-11] "refactoriza esta clase para que use..."
[2025-03-12] "explícame cómo funciona este módulo"

La solución es nombrar las sesiones desde el principio, tan pronto como sabes en qué estás trabajando: 

# Renombrar la sesión actual
/rename payment-integration-bug
 
# Sin argumentos, Claude genera un nombre descriptivo automáticamente
/rename
La documentación oficial de Anthropic tiene una frase que vale la pena repetir: "Name sessions early: Use /rename when starting work on a distinct task — it's much easier to find 'payment-integration' than 'explain this function' later."

Una convención útil es usar el mismo esquema que usarías para nombrar ramas de Git: feature/nombre, bug/descripcion, refactor/modulo. Así cuando retomas trabajo después de unos días, el nombre ya te dice exactamente de qué se trata.

Ramificar una sesión con /fork

Este es probablemente el comando menos usado y más útil de Claude Code para developers que ya están cómodos con Git. La idea es simple: en un punto de la sesión, puedes crear una "rama" de esa conversación para explorar un enfoque diferente sin perder el estado actual. 

# Crear una rama de la sesión en su estado actual
/fork

El fork crea una nueva sesión que parte con una copia exacta del historial hasta ese momento, pero que a partir de ahí diverge de forma independiente. La sesión original queda intacta con su propio ID. Terminas con dos sesiones independientes que puedes retomar por separado.

¿Cuándo usarlo? Cuando tienes una refactorización grande y quieres probar dos estrategias diferentes sin comprometerte con ninguna antes de ver los resultados: 

# Sesión principal: hemos analizado el módulo de pagos juntos
# Ahora queremos probar dos enfoques de refactorización distintos
 
/fork
# → Se crea sesión "fork-1" (copia del estado actual)
 
# En la sesión original, probamos el enfoque A:
> Refactoriza PaymentService usando el patrón Command
 
# En la sesión fork (claude --resume fork-1), probamos el enfoque B:
> Refactoriza PaymentService usando el patrón Strategy
 
# Comparamos resultados y elegimos el mejor enfoque
Importante: /fork ramifica la conversación, no el sistema de archivos. Si el agente edita archivos en la sesión fork, esos cambios son reales y los verá cualquier otra sesión que trabaje en el mismo directorio. Para aislar cambios en el sistema de archivos, usa Git worktrees (lo veremos en un artículo dedicado).

Checkpoints y /rewind: deshacer sin miedo

Uno de los cambios de mentalidad más importantes cuando empiezas a usar Claude Code es que puedes pedirle al agente que haga cambios grandes y agresivos sin el miedo habitual de "¿y si rompe algo?". El sistema de checkpoints es la razón.

Cómo funcionan los checkpoints

Cada vez que Claude Code va a editar un archivo a través de sus herramientas internas (Write, Edit, NotebookEdit), crea automáticamente un snapshot del estado anterior. Sin que hagas nada. Sin que tengas que pedírselo. Estos snapshots son los checkpoints.

Los checkpoints persisten entre sesiones durante 30 días, así que puedes retomar una sesión de hace tres días y aún tener acceso a todos los puntos de rollback de esa sesión.

Límite importante: Los checkpoints solo rastrean archivos modificados por las herramientas de edición de Claude Code. Los comandos Bash (rm, mv, sed -i, etc.) no se rastrean. Si Claude ejecuta un script que borra archivos, eso no tiene rollback vía checkpoints.

/rewind: el rollback quirúrgico

Para acceder al menú de checkpoints: 

# Con comando:
/rewind
 
# Con atajo de teclado (más rápido):
Esc Esc

Esto abre una lista scrolleable con todos los prompts de la sesión. Seleccionas el punto al que quieres volver y el sistema te da tres opciones:

Opción Qué hace Cuándo usarla
Restore code and conversation Revierte archivos Y la conversación al punto seleccionado El agente tomó un camino completamente equivocado
Restore code only Revierte solo los archivos; la conversación queda intacta Los cambios no funcionaron pero el análisis del problema fue útil
Restore conversation only Revierte el historial de mensajes; los archivos quedan como están Compactar una sesión verbose sin perder el código generado

La opción de "restore code only" es la más interesante desde el punto de vista práctico. Te permite tener esta secuencia de trabajo:

  1. Pedirle al agente una refactorización agresiva
  2. Revisar y discutir los resultados en la conversación
  3. Decidir que el enfoque no fue el correcto
  4. Revertir solo el código al estado anterior, conservando el análisis
  5. Intentar un enfoque diferente con el contexto de por qué el anterior no funcionó

Esto elimina por completo el ciclo de git stash / git reset para el trabajo exploratorio con el agente.

Ver y gestionar el contexto activo

Ya vimos en el artículo anterior qué es la ventana de contexto. Ahora veamos las herramientas concretas para inspeccionarla y gestionarla durante una sesión real.

Ver cuánto contexto llevas consumido

/cost

Este comando muestra el uso de tokens de la sesión actual y, si usas facturación por API, el costo estimado. Es el equivalente a echarle un vistazo al indicador de combustible antes de un viaje largo. Úsalo periódicamente en sesiones de más de 30-40 minutos.

Compactar sin perder el hilo: /compact

# Compactar con resumen automático
/compact
 
# Compactar con instrucciones específicas sobre qué preservar
/compact resume solo los TODOs pendientes y las decisiones arquitectónicas

/compact le pide al agente que genere un resumen de la conversación y empieza una nueva ventana de contexto cargada con ese resumen. La sesión sigue siendo la misma (mismo ID, mismo nombre), pero el contexto ahora es más eficiente.

Claude Code también compacta automáticamente cuando la ventana alcanza el 95% de su capacidad. Puedes ver y cambiar este comportamiento con /config.

Limpiar completamente: /clear

/clear

Borra el historial de la conversación activa completamente. La diferencia con /compact: no queda ni un resumen. Úsalo cuando terminas una tarea y empiezas algo completamente diferente dentro de la misma sesión de trabajo, o cuando el contexto acumulado ha empezado a confundir al agente.

Incluir archivos con @

Cuando quieres que el agente tenga en contexto un archivo específico sin esperar a que lo descubra navegando el repositorio, puedes incluirlo directamente en tu prompt con la sintaxis @: 

> @src/main/java/com/miapp/pagos/PaymentService.java
  Esta clase tiene un problema de rendimiento. ¿Puedes analizarla?

Esto incluye el contenido completo del archivo en el contexto inmediatamente, sin que el agente tenga que buscarlo. Es más rápido y consume menos tokens que esperar a que navegue el árbol de archivos.

Memoria: guardar lo importante entre sesiones

Hasta aquí hemos hablado de cómo manejar el contexto dentro de una sesión. Pero hay otro nivel de memoria: la información que quieres que el agente recuerde no solo en esta sesión sino en todas las futuras. Para eso existen los archivos CLAUDE.md y, dentro de una sesión activa, el comando /memory.

Guardar cosas importantes desde dentro de la sesión

Imagina que estás en medio de una sesión larga y el agente acaba de descubrir algo importante sobre tu codebase — una particularidad de tu arquitectura, un patrón que usas en todos tus servicios, una restricción del negocio — que no está documentada en ningún lado. En vez de esperar a acordarte de actualizar el CLAUDE.md manualmente, puedes pedírselo directamente: 

> Guarda en memoria que en este proyecto todos los servicios
  deben implementar la interfaz Auditable y que ningún servicio
  puede llamar directamente a otro sin pasar por el EventBus

El agente actualizará el archivo de memoria correspondiente. También puedes ver y editar el estado actual de la memoria en cualquier momento: 

/memory
# Abre el panel de memoria. Puedes ver los archivos CLAUDE.md activos,
# navegar a la Auto Memory del proyecto, y editar o eliminar entradas

El mapa completo de la memoria

Para tener una visión clara de todos los niveles de memoria disponibles, aquí está el panorama completo:

Nivel Archivo Alcance Versionable con Git
Global ~/.claude/CLAUDE.md Todos tus proyectos No (es tuyo, personal)
Proyecto /raiz/CLAUDE.md Todo el equipo Sí
Local del proyecto /raiz/CLAUDE.local.md Solo tú en este proyecto No (añádelo a .gitignore)
Subdirectorio /raiz/modulo/CLAUDE.md Solo cuando trabajas en ese módulo Sí
Auto Memory ~/.claude/projects/*/ Por proyecto, gestionado por el agente No

Qué va en cada nivel

La pregunta que siempre surge es: ¿cómo distribuyo la información entre estos niveles? Una heurística simple:

  • Global (~/.claude/CLAUDE.md): Tus preferencias personales de developer. El idioma en que quieres las respuestas, tu estilo preferido de código, cómo te gusta que estructure los commits, preferencias de herramientas. Cosas que aplican sin importar en qué proyecto estés.
  • Proyecto (CLAUDE.md en raíz): Las convenciones del equipo. Comandos de build y test, estructura de paquetes, restricciones arquitectónicas, patrones que el equipo ha acordado usar. Esto va en Git porque todo el equipo debe beneficiarse.
  • Local del proyecto (CLAUDE.local.md): Tu configuración específica para este proyecto que no debe compartirse. Rutas locales, credenciales de entorno de desarrollo, preferencias propias que difieren del estándar del equipo.
  • Subdirectorio: Reglas específicas de un módulo. Si tienes un microservicio con convenciones propias, un módulo legacy con restricciones especiales, o un subdirectorio de infraestructura con sus propios patrones.
Tip de organización: El CLAUDE.md global acepta la sintaxis @ruta/archivo.md para importar otros archivos Markdown. Esto te permite tener un archivo principal corto que referencia archivos más detallados por tema, evitando que el archivo principal se convierta en un monstruo de 500 líneas que consume todo tu contexto desde el arranque.

Exportar y compartir una sesión

Hay escenarios donde quieres sacar la conversación de una sesión hacia afuera: documentar una sesión de debugging para el equipo, crear un postmortem, compartir el análisis que hizo el agente sobre una parte del sistema, o simplemente conservar el historial de una sesión importante antes de que expire. 

# Exportar la sesión activa como texto plano
/export
 
# El archivo se guarda en el directorio actual con un nombre tipo:
# claude-session-2025-03-12.txt

El archivo exportado contiene la conversación completa en texto legible: tus prompts, las respuestas del agente, los resultados de herramientas. Es útil tanto para documentación como para hacer búsqueda de texto sobre sesiones pasadas si necesitas encontrar algo específico que se discutió.

Un flujo de trabajo completo

Para cerrar, veamos cómo encajan todas estas piezas en un escenario real. Supón que tienes que implementar un feature medianamente complejo — digamos, agregar rate limiting a tu API — y quieres usar Claude Code de forma eficiente durante varios días de trabajo.

Día 1: arrancar con estructura

# Arrancas desde la raíz del proyecto
cd /mi-proyecto
claude
 
# Lo primero que haces es nombrar la sesión
/rename feature/rate-limiting
 
# Incluyes los archivos relevantes en contexto
> @src/main/java/com/miapp/api/filters/ @src/main/java/com/miapp/config/
  Quiero agregar rate limiting a la API. Analiza la estructura actual
  y propón un diseño antes de tocar nada.
 
# El agente analiza y propone. Antes de aprobar cualquier cambio:
/cost
# → Verificas que el contexto no está desbordado con el análisis
 
# Apruebas el diseño y pides la implementación.
  Al terminar el día, exportas la sesión para el equipo:
/export

Día 2: retomar donde lo dejaste

# Al día siguiente, desde la raíz del proyecto:
claude --resume
# → Buscas "feature/rate-limiting" en el picker
# → Presionas P para preview y confirmas que es la correcta
# → El contexto completo del día anterior está disponible
 
# Si la conversación creció mucho, compactas antes de continuar:
/compact conserva el diseño acordado y los archivos modificados hasta ahora
 
# Continúas con la implementación.
  Quieres probar un enfoque diferente para el storage del rate limiting:
/fork
# → Creas un fork para probar Redis vs. memoria en caché local

Cuando algo sale mal: /rewind al rescate

# El agente hizo cambios en tres archivos que rompieron los tests
# No quieres perder el análisis de por qué intentó ese enfoque
 
Esc Esc
# → Se abre el menú de rewind
# → Seleccionas el punto antes de los cambios problemáticos
# → Eliges "Restore code only"
# → Los archivos vuelven al estado anterior, la conversación permanece
 
> El enfoque anterior rompió los tests porque X. Intentemos con Y en su lugar.

Al terminar: guardar lo aprendido

# Antes de cerrar, le pides que guarde las lecciones aprendidas
> Guarda en el CLAUDE.md del proyecto que el rate limiting usa Redis
  con la biblioteca Bucket4j, y que los tests de integración para
  filters requieren el perfil "integration-test" activo.
 
# El agente actualiza el CLAUDE.md. Próxima sesión, ese contexto
  ya estará disponible desde el arranque.

Conclusión

El sistema de sesiones de Claude Code es más rico de lo que parece a primera vista. La mayoría de los developers lo usan como si fuera un chat: abren, trabajan, cierran, y al día siguiente empiezan de cero. La diferencia entre eso y dominarlo está en tres hábitos:

  • Nombrar las sesiones desde el principio (/rename) para poder encontrarlas y retomar el trabajo con --resume sin adivinar
  • Usar /rewind con confianza para experimentar sin miedo, sabiendo que siempre puedes revertir el código, la conversación, o ambos
  • Persistir lo aprendido en memoria para que el agente mejore progresivamente en tu proyecto específico, en lugar de empezar de cero en cada sesión

En futuros artículo de la serie, una vez que terminemos con los elementos básicos, veremos los flujos de trabajo avanzados: cómo usar Claude Code para code reviews, cómo integrarlo en pipelines de CI/CD en modo no-interactivo.

Espero que este tutorial les sea de utilidad. Si tienen alguna duda, sugerencia, comentario o aclaración, pueden dejarla en la sección de comentarios o enviar un correo a programadorjavablog@gmail.com (pueden agregarme al chat de gmail).

© javatutoriales.com – Serie: Desarrollo Asistido por IA