CLAUDE.md y memoria persistente: mi flujo real con Claude Code

Nombre y propósito del proyecto

[Una o dos líneas. Para qué sirve y quién lo opera.]

Reglas globales

[Idioma, tono, convenciones no negociables. Las cosas que si Claude Code
ignora, el output es inutilizable.]

Estructura del repositorio

[Árbol de directorios con una línea explicando qué hay en cada carpeta.
Claude Code necesita saber dónde está cada cosa sin tener que explorar.]

Comandos disponibles

[Los scripts, CLIs y comandos que puede ejecutar. Con ejemplo real de uso.]

Convenciones de nomenclatura

[Patrones de nombres de archivos. Crítico para proyectos con muchos docs.]

Qué NO hacer

[Igual de importante que lo que sí hacer. Archivos que no tocar,
patrones que evitar, decisiones ya tomadas que no reabrir.]


Lo que no incluyo: historia del proyecto, motivaciones, "por qué elegimos X tecnología". Eso es contenido para un ADR o el README. El CLAUDE.md tiene que ser operativo al 100%.

**Longitud objetivo: menos de 200 líneas.** Si supera eso, estás incluyendo demasiado. Claude Code no necesita el contexto completo de cada decisión — necesita las reglas de operación.

### Lo que la mayoría mete en CLAUDE.md y no debería

He revisado muchos CLAUDE.md de proyectos de developers en la comunidad. El error más común: meter todo lo que "podría ser útil".

Eso mata el propósito del documento. Cuando el CLAUDE.md tiene 500 líneas, Claude Code lo lee entero pero no distingue qué es crítico y qué es relleno. El resultado es el mismo que no tener CLAUDE.md: ruido.

Solo va al CLAUDE.md lo que, si Claude Code lo ignora, rompe el proyecto o produce output inutilizable.

---

## El sistema de memoria persistente

El contexto de una sesión de Claude Code desaparece cuando la sesión termina. Eso es una limitación real y no va a cambiar pronto — la ventana de contexto no es memoria a largo plazo.

El workaround que funciona: archivos Markdown.

### La estructura que uso

En el directorio del proyecto tengo una carpeta `memory/` con dos tipos de archivos:

1. **`MEMORY.md`** — el índice. Una lista de una línea por cada archivo de memoria con un enlace y una descripción de qué contiene. Claude Code lo lee al arrancar la sesión y sabe qué hay disponible.

2. **Archivos individuales de memoria** — uno por tema. Nomenclatura descriptiva: `project_kursar.md`, `feedback_email_style.md`, `reference_tools.md`.

Una entrada en `MEMORY.md` tiene esta forma:

```markdown
# Memory Index — Dominicode Company Agents

- [User Profile](user_profile.md) — Solo creator, YouTube + Udemy + books, comunidad en español
- [Curso Angular 22](project_curso_angular22.md) — Regrabación en curso; ejemplos verificados en ejemplos/v22-features/
- [Estilo emails Bezael](feedback_email_style.md) — Abrir con historia breve; no estilo telegráfico
- [WordPress taxonomía](reference_wordpress_taxonomia.md) — IDs reales verificados (AI=37, TypeScript=42…)

Hay tres prefijos que uso para distinguir el tipo de contenido:

project_ — estado de un proyecto activo con decisiones tomadas
feedback_ — algo que salió mal o que aprendí de una sesión anterior y no quiero volver a repetir
reference_ — datos estáticos que Claude Code necesita consultar (IDs, URLs, credenciales de formato)

Por qué funciona mejor que repetirlo en cada sesión

La alternativa es pegar el contexto en el primer prompt de cada sesión. Lo hice durante semanas. El problema: acumulas un primer prompt de 800 palabras que tarde o temprano omites porque es tedioso, y cuando lo omites, Claude Code trabaja sin ese contexto.

Con archivos de memoria, el contexto está disponible siempre que Claude Code los lea. Y como están versionados en el repo, no se pierden entre sesiones ni entre máquinas.

El inconveniente honesto: Claude Code no lee esos archivos automáticamente a menos que se lo indiques. Tienes que incluirlos en el arranque de sesión o referenciarlos con @archivo cuando son relevantes. Esto lo resuelvo con el ritual de inicio que cuento más adelante.

Gestión del contexto en sesiones largas

Esto es lo que menos se habla y lo que más impacta en la calidad del trabajo.

Una sesión larga de Claude Code acumula contexto de forma lineal. Cada intercambio, cada archivo leído, cada respuesta generada ocupa espacio en la ventana. Cuando la ventana se llena, el modelo empieza a "comprimir" el historial — mantiene las instrucciones recientes y los bloques de código más relevantes, pero los matices de conversaciones anteriores se difuminan.

El resultado es exactamente lo que me pasó esa tarde: Claude Code responde con coherencia local (el último intercambio está bien) pero pierde coherencia global (contradice decisiones tomadas hace cuarenta minutos).

Cómo lo detecto

Hay tres señales de que el contexto está degradado:

Claude Code propone algo que ya descartamos explícitamente en la misma sesión
Las respuestas se vuelven más genéricas y pierden el tono específico del proyecto
Me pide información que ya le di al inicio de la sesión

Cuando aparece cualquiera de las tres, no sigo. Empiezo sesión nueva.

Cuándo empezar sesión nueva (aunque duela)

La respuesta rápida: cuando terminas un bloque de trabajo concreto.

No esperes a que el contexto se degrade. Trata cada sesión de Claude Code como una unidad de trabajo enfocada. Si estoy escribiendo un post del blog, esa es la sesión. Si paso a revisar el curriculum de un curso, es una sesión nueva.

Este cambio de mentalidad es lo que más impacta en la consistencia del output. Una sesión larga y dispersa produce resultados mediocres. Sesiones cortas y enfocadas producen resultados que puedes usar directamente.

@files: cuándo y cómo los uso

Claude Code tiene la sintaxis @archivo para incluir el contenido de un archivo específico en el contexto. Es la herramienta más infrautilizada que conozco entre developers que llevan meses con Claude Code.

Uso @archivo para tres cosas:

Dar contexto específico sin abrir un archivo manualmente. Si estoy trabajando en el agente de blog y necesito que Claude Code vea el estado actual del MEMORY.md, escribo @memory/MEMORY.md en el prompt. El contenido entra directamente en el contexto sin que yo tenga que copiarlo.

Anclar decisiones pasadas. Si en una sesión nueva necesito que recuerde una decisión de arquitectura que está en specs/agentkit-pro/spec.md, la referencio con @. Entra en el contexto de esa sesión específicamente donde la necesito.

Forzar coherencia entre archivos. Si estoy modificando un componente y quiero que Claude Code sea consciente de cómo lo usa otro módulo, incluyo ambos con @. Sin eso, trabaja con el archivo aislado y puede romper la integración.

Lo que no hago: incluir diez archivos con @ en el mismo prompt. Cuantos más archivos incluyes, más contexto consumes antes de empezar el trabajo real. Selecciono solo los que son directamente relevantes para la tarea concreta de esa sesión.

El ritual de inicio de sesión

Después de meses ajustando esto, tengo un primer prompt que uso como plantilla base. No es magia — es contexto específico entregado de forma eficiente.

Contexto de esta sesión:
- Proyecto: [nombre]
- Tarea: [qué voy a hacer hoy, en una línea]
- Decisiones previas que aplican: @memory/MEMORY.md
- Archivos relevantes: @[archivo-1] @[archivo-2]
- Restricciones: [lo que NO quiero que haga en esta sesión]

Empieza por [primera acción concreta].

Los tres elementos críticos son:

La tarea en una línea. No el proyecto entero, solo lo que hacemos hoy. Cuanto más específico, mejor el foco de Claude Code durante toda la sesión.

Las restricciones. Es lo que más me ha ahorrado tiempo. "No toques el archivo X", "no propongas cambiar el stack", "si necesitas más información, pregunta antes de generar código". Sin restricciones explícitas, Claude Code optimiza para completar la tarea con las decisiones que considera mejores — que no siempre son las que tú ya tomaste.

Una primera acción concreta. No "ayúdame con el proyecto". Sino "lee el archivo X y dime si la estructura de directorios es coherente con las reglas de CLAUDE.md". La primera acción específica establece el tono de toda la sesión.

Lo que todavía falla y cómo lo mitigo

Honestidad completa aquí, porque la mayoría de posts sobre Claude Code solo muestran los casos de éxito.

Los archivos de memoria no se actualizan solos. Si en una sesión tomo una decisión importante — por ejemplo, cambio la arquitectura de un módulo o descubro que una librería no funciona para mi caso de uso — tengo que acordarme de actualizar el archivo de memoria correspondiente antes de cerrar la sesión. Si no lo hago, en la siguiente sesión Claude Code no tiene ese contexto. Todavía me olvido. La solución parcial: incluir "actualiza MEMORY.md con las decisiones de esta sesión" como último paso de cada sesión de trabajo.

El CLAUDE.md global a veces entra en conflicto con el del proyecto. Tengo reglas globales que son sensatas para el 90% de mis proyectos pero que en algún proyecto específico quiero anular. Claude Code no siempre resuelve bien ese conflicto — a veces aplica la regla global aunque el CLAUDE.md del proyecto diga lo contrario. La solución: en el CLAUDE.md del proyecto, cuando necesito anular una regla global, lo digo explícitamente: "Aunque el CLAUDE.md global indica X, en este proyecto aplicamos Y."

La compresión de contexto no es predecible. No hay un indicador que te diga "estás al 80% de la ventana de contexto, es hora de empezar sesión nueva". Lo detecto por los síntomas que describí antes. Estoy esperando que Claude Code añada algún tipo de indicador de uso de contexto — de momento no existe.

Las sesiones cortas y enfocadas son más difíciles de mantener. Cuando estoy en el flow, la tentación de seguir en la misma sesión es real. Cada vez que cedo, la calidad del output en la segunda mitad de la sesión baja. Es un problema de disciplina, no de herramienta.

FAQ

¿Cuántas secciones debe tener un CLAUDE.md?

No hay un número correcto. Lo importante es que cada sección tenga una función operativa clara. Si no puedes responder "qué hace Claude Code diferente por tener esta sección", esa sección sobra. En mis proyectos suelo tener entre 5 y 8 secciones.

¿Puedo tener múltiples CLAUDE.md en subdirectorios?

Sí. Claude Code lee el CLAUDE.md del directorio raíz y también los de subdirectorios cuando trabaja en ellos. Esto es útil en monorepos o cuando tienes un frontend y un backend con convenciones distintas. No lo abuses — si tienes CLAUDE.md en diez subdirectorios, el agente pasa más tiempo leyendo instrucciones que trabajando.

¿Qué diferencia hay entre poner algo en CLAUDE.md y decirlo en el primer prompt?

El CLAUDE.md aplica a todas las sesiones del proyecto de forma permanente. El primer prompt aplica solo a esa sesión. Usa CLAUDE.md para convenciones estables que no cambian entre sesiones. Usa el primer prompt para el contexto específico de lo que haces hoy.

¿Cuándo tiene sentido usar memoria persistente vs. simplemente tener un CLAUDE.md más completo?

CLAUDE.md es para reglas e instrucciones: cómo trabajar en este proyecto. Los archivos de memoria son para estado e historial: qué ha pasado ya, qué decisiones están tomadas, qué feedback recibí en sesiones anteriores. Si en tu CLAUDE.md estás escribiendo cosas como "el curso de Angular lleva dos semanas atrasado" o "el cliente pidió cambiar el color primario a azul", eso debería ir en un archivo de memoria, no en CLAUDE.md.

¿Funciona igual en proyectos de código que en proyectos de contenido?

Igual de bien, o incluso mejor en proyectos de contenido. Todo lo que describí aquí lo uso tanto para el repositorio de código de Kursar como para el sistema de agentes de Dominicode — que no tiene una sola línea de código productivo, pero tiene 18 agentes, 118 documentos en la base de conocimiento, y decisiones editoriales acumuladas durante meses. El sistema de memoria persistente es especialmente valioso cuando el "código" son documentos, estrategias y decisiones.

Conclusión

El contexto no es un detalle técnico de Claude Code que puedas ignorar. Es el recurso central que determina si el agente trabaja contigo o contra ti.

CLAUDE.md bien estructurado te da coherencia por defecto. La memoria persistente te da continuidad entre sesiones. El ritual de inicio te da foco en cada sesión. Y saber cuándo empezar sesión nueva te salva de la degradación silenciosa que destruye la calidad del output.

No necesitas implementar todo esto de golpe. Empieza por el CLAUDE.md del proyecto — 100 líneas operativas, sin relleno. Eso solo ya cambia radicalmente cómo trabaja Claude Code en tu repositorio.

Si quieres ver este sistema aplicado a un proyecto real de principio a fin, en el curso Construye con IA trabajamos exactamente con este flujo: CLAUDE.md, memoria, gestión del contexto y SDD como metodología para que el agente tenga siempre el contexto correcto en el momento correcto.

Y si ya tienes Claude Code corriendo y quieres profundizar con otros developers que están en el mismo camino, en Dominicode Labs compartimos los patrones que van funcionando en producción — incluyendo los que fallan y cómo los arreglamos.

Posts relacionados

Bezael Pérez es developer senior con 15+ años de experiencia y fundador de Dominicode. Construye con Claude Code, Angular y TypeScript, y documenta lo que funciona — y lo que no — para developers que quieren ir más allá del vibe coding.