La memoria de Claude Code dentro de un proyecto
En un agente de programación basado en LLM, el contexto del proyecto constituye una parte fundamental de la interacción. Claude Code no trabaja únicamente con el código que recibe en una petición concreta: puede utilizar información persistente asociada al repositorio para interpretar la arquitectura, aplicar convenciones y mantener determinadas reglas de trabajo entre sesiones.
En este modelo, el directorio .claude adquiere especial relevancia. No debe entenderse simplemente como una carpeta de configuración, sino como uno de los mecanismos mediante los cuales se estructura el contexto operativo del agente.
CLAUDE.md: memoria declarativa del proyecto
Uno de los elementos principales es CLAUDE.md. Este archivo permite describir información que Claude Code debe conocer cuando trabaja sobre el proyecto.
Puede contener, por ejemplo:
- Arquitectura y organización del código.
- Comandos para ejecutar tests.
- Convenciones de nomenclatura.
- Reglas específicas de implementación.
- Dependencias relevantes.
- Restricciones técnicas.
- Procedimientos de despliegue.
- Decisiones arquitectónicas que deben respetarse.
Un ejemplo sencillo podría ser:
# Proyecto
## Arquitectura
La aplicación utiliza Symfony y API Platform.
## Reglas
- Los controladores deben utilizar atributos de Symfony.
- La lógica de negocio debe permanecer fuera de los controladores.
- Ejecutar los tests antes de modificar una API pública.
## Comandos
Tests:
php bin/phpunit
Servidor:
symfony server:startEl valor de este archivo no reside únicamente en almacenar información. Su función es proporcionar contexto semántico persistente al agente.
Sin este contexto, una petición como «añade un endpoint para usuarios» puede provocar que el modelo tome decisiones basadas exclusivamente en los patrones que conoce. Con contexto, la misma petición puede interpretarse dentro de las convenciones concretas del repositorio.
La carpeta .claude
.claude permite organizar diferentes elementos relacionados con el comportamiento de Claude Code dentro del proyecto.
Esto resulta especialmente interesante cuando las instrucciones dejan de ser suficientemente pequeñas como para mantenerlas todas en un único archivo.
Una estructura conceptual podría ser:
project/
├── .claude/
│ ├── commands/
│ └── ...
├── CLAUDE.md
├── src/
├── tests/
└── composer.jsonEl objetivo no es convertir .claude en una segunda documentación del proyecto. Su utilidad aparece cuando determinadas instrucciones, automatizaciones o comportamientos del agente necesitan una ubicación explícita dentro del repositorio.
Jerarquía del contexto
La memoria de un agente de programación no funciona exactamente como la memoria humana.
Un LLM no «recuerda» indefinidamente todas las conversaciones anteriores. En cada interacción dispone de una ventana de contexto formada por diferentes fuentes de información.
En Claude Code pueden coexistir:
Instrucciones
↓
Contexto del proyecto
↓
CLAUDE.md
↓
Configuración de .claude
↓
Código y archivos relevantes
↓
Petición actual
↓
Respuesta / modificaciónEsta distinción es importante porque permite separar dos conceptos que habitualmente se confunden: persistencia de información y memoria del modelo.
Guardar una regla en CLAUDE.md no modifica los pesos del modelo ni crea una memoria permanente dentro del LLM. Lo que hace es proporcionar esa información como contexto cuando Claude Code trabaja con el proyecto.
Memoria frente a documentación
Existe además una diferencia práctica entre documentar un proyecto y proporcionar memoria operativa a un agente.
Una documentación convencional está escrita principalmente para desarrolladores. Un archivo utilizado por Claude Code debe responder también a una pregunta diferente:
¿Qué información necesita el agente para tomar decisiones correctas sobre este repositorio?
Por eso una instrucción como:
La aplicación utiliza Symfony.aporta menos información operacional que:
La aplicación utiliza Symfony 7.
Las rutas nuevas deben definirse mediante atributos #[Route].
No crear archivos YAML para rutas nuevas.La segunda forma reduce el espacio de decisiones posibles del agente.
En términos de ingeniería de prompts, las instrucciones funcionan como restricciones sobre el espacio de generación. El modelo sigue siendo probabilístico, pero el contexto proporcionado modifica qué soluciones considera compatibles con el proyecto.
Memoria local y memoria compartida
Otra propiedad relevante es la ubicación de las instrucciones.
Si determinadas reglas forman parte del propio repositorio, almacenarlas junto al código permite que sean versionadas con Git y compartidas con otros desarrolladores.
Esto convierte determinados elementos de .claude y CLAUDE.md en parte de la infraestructura del proyecto.
El repositorio puede contener entonces tres capas diferenciadas:
Código
Documentación
Contexto para el agenteEsta última capa resulta cada vez más relevante en proyectos donde el desarrollo asistido por agentes forma parte del proceso habitual.
La memoria deja de ser únicamente una característica de la herramienta y pasa a convertirse en un artefacto versionable del proyecto.
El problema del exceso de contexto
Más información no implica necesariamente mejores resultados.
Un CLAUDE.md excesivamente extenso puede introducir instrucciones irrelevantes, redundantes o contradictorias. Desde la perspectiva de un LLM, cada nueva instrucción compite por espacio y atención dentro del contexto disponible.
Por esta razón, las instrucciones más útiles suelen ser aquellas que contienen información que el agente no puede inferir con seguridad leyendo el código.
Por ejemplo:
No modificar migraciones existentes.puede ser una regla crítica aunque el código no permita deducirla.
En cambio:
El proyecto contiene controladores.aporta poca información si la estructura del repositorio ya lo demuestra.
La calidad de la memoria del proyecto depende, por tanto, tanto de qué información se almacena como de qué información se excluye.
En un entorno de desarrollo con agentes, .claude y CLAUDE.md pueden entenderse como una capa adicional situada entre el repositorio y el modelo: una capa destinada a transformar conocimiento disperso del proyecto en contexto explícito para la ejecución de tareas de programación.
