Sistema de memoria compartida

El problema de la memoria en agentes IA

Los agentes IA operan con una ventana de contexto limitada. Cada sesión de trabajo comienza sin memoria de sesiones anteriores: el agente no recuerda qué decisiones se tomaron ayer, qué principios arquitectónicos se acordaron la semana pasada ni qué restricciones técnicas se descartaron en iteraciones previas.

Este comportamiento no es un defecto del agente, es una característica de diseño de los modelos de lenguaje. Pero en el contexto de un proyecto de software, donde las decisiones se acumulan durante semanas o meses, la ausencia de memoria persistente genera problemas reales. Un agente que no recuerda la constitución del proyecto puede generar código que contradiga los principios acordados. Uno que no conoce el modelo de datos definido en la especificación puede inventar estructuras incompatibles.

El sistema de memoria de Spec Kit resuelve la amnesia de los agentes IA almacenando las decisiones del proyecto en archivos que cada slash command consulta automáticamente.

Spec Kit aborda este problema con un mecanismo directo: almacenar las decisiones y el contexto del proyecto en archivos de texto plano que los slash commands inyectan en el prompt del agente al inicio de cada ejecución. El agente no necesita "recordar" nada porque la información relevante se le proporciona explícitamente cada vez que ejecuta un comando.

El directorio .specify/memory/

El directorio .specify/memory/ es el almacén de memoria persistente del proyecto. Los archivos que contiene representan conocimiento que debe estar disponible para todos los slash commands, independientemente de la sesión de trabajo o la feature en la que se esté trabajando.

El archivo principal que reside en este directorio es constitution.md, que contiene los principios de gobernanza del proyecto. La constitución es el artefacto más importante de la memoria compartida porque define las reglas que deben respetarse en todas las fases del flujo SDD.

.specify/memory/
  constitution.md

Diferencia entre memoria y artefactos

Es importante distinguir entre la memoria compartida (.specify/memory/) y los artefactos de feature (specs/):

| Aspecto | .specify/memory/ | specs/ | |---|---|---| | Alcance | Todo el proyecto | Una feature concreta | | Contenido | Principios, restricciones globales | Especificaciones, planes, tareas | | Quién lo consulta | Todos los slash commands | Slash commands de esa feature | | Frecuencia de cambio | Baja (principios estables) | Alta (cada feature nueva) |

La memoria compartida contiene información que trasciende a las features individuales. Un principio como "usar PostgreSQL como base de datos" o "seguir el patrón Repository" afecta a todas las features del proyecto, por lo que reside en la memoria global y no en el directorio de una feature concreta.

La constitución como memoria fundamental

El archivo constitution.md es el artefacto central de la memoria compartida. Se genera mediante el slash command /speckit.constitution y define los principios inmutables que gobiernan el desarrollo del proyecto.

Un extracto típico de una constitución generada por Spec Kit incluye artículos como:

## Article 1: Library-First
Prefer well-maintained libraries over custom implementations.
Before writing any custom code, search for existing libraries
that solve the problem.

## Article 2: Test-First
Write tests before implementation. Every feature must have
automated tests that verify its behavior.

## Article 3: Simplicity
Choose the simplest solution that satisfies the requirements.
Avoid premature optimization and unnecessary complexity.

Estos artículos no son genéricos. Durante la generación de la constitución, el agente IA los adapta al stack tecnológico, las convenciones del equipo y las restricciones del proyecto. Un proyecto en Python con FastAPI tendrá una constitución diferente a uno en TypeScript con Next.js.

La constitución funciona como el "ADN" del proyecto: define las reglas que todos los slash commands deben respetar al generar especificaciones, planes y código.

Cómo los slash commands consumen la constitución

Cada slash command de Spec Kit incluye en su prompt una instrucción para leer la constitución antes de generar cualquier artefacto. El flujo es transparente para el usuario:

flowchart TB
    U["Usuario ejecuta<br>/speckit.specify"] --> CMD["Slash command<br>lee instrucciones"]
    CMD --> CONST["Lee .specify/memory/<br>constitution.md"]
    CMD --> TPL["Lee .specify/templates/<br>spec-template.md"]
    CONST --> GEN["Genera artefacto<br>respetando principios"]
    TPL --> GEN
    GEN --> OUT["specs/001-feature/<br>spec.md"]

El agente no necesita que el usuario le recuerde los principios del proyecto. Al ejecutar /speckit.specify, el prompt del slash command ya incluye la directiva de leer la constitución y aplicar sus principios al generar la especificación. Lo mismo ocurre con /speckit.plan, /speckit.tasks y el resto de comandos.

Persistencia entre sesiones

La memoria compartida resuelve uno de los problemas más habituales del trabajo con agentes IA: la pérdida de contexto entre sesiones. Cuando un desarrollador cierra el editor y lo abre al día siguiente, el agente IA parte de cero. No recuerda la conversación anterior, las decisiones tomadas ni el estado del proyecto.

Con el sistema de memoria de Spec Kit, esta pérdida de contexto se mitiga de forma estructural:

• La constitución persiste en disco y se carga automáticamente en cada invocación de slash command.
• Los artefactos de feature (en specs/) complementan la memoria con el estado actual de la especificación, el plan y las tareas.
• El historial de Git proporciona una capa adicional de persistencia, permitiendo ver cómo han evolucionado los artefactos a lo largo del tiempo.

El resultado es que el agente IA, aunque no tiene memoria propia, recibe en cada sesión un contexto suficiente para continuar el trabajo donde se dejó. La calidad de este contexto depende directamente de la calidad de los artefactos almacenados: una constitución bien definida y unas especificaciones completas proporcionan un punto de partida sólido para cualquier sesión de trabajo.

Contexto acumulativo

A medida que el proyecto avanza, la cantidad de contexto disponible crece. Cada feature especificada añade artefactos a specs/, cada ejecución de /speckit.constitution refina los principios del proyecto y cada iteración de clarificación (/speckit.clarify) elimina ambigüedades de las especificaciones.

Este contexto acumulativo es una de las ventajas de trabajar con SDD frente al vibe coding. En el vibe coding, el contexto del proyecto vive en la cabeza del desarrollador y se pierde o distorsiona con el tiempo. En SDD, el contexto se externaliza en archivos de texto que se versionan, se revisan y se comparten con el equipo.

La memoria de Spec Kit no es un sistema de caché temporal. Es un registro estructurado de las decisiones del proyecto que crece con cada feature y se mantiene disponible de forma permanente.

Buenas prácticas con la memoria compartida

Versionar la constitución

La constitución debe tratarse como un archivo de primera categoría en el repositorio. Incluirla en el control de versiones permite:

• Rastrear cambios: ver cuándo y por qué se modificaron los principios del proyecto.
• Revisar en equipo: los cambios en la constitución pueden pasar por el mismo proceso de revisión que el código (pull requests, code review).
• Recuperar versiones anteriores: si una enmienda resulta contraproducente, se puede revertir con git restore.

Mantener la constitución actualizada

Una constitución que no refleja el estado actual del proyecto genera más problemas de los que resuelve. Si el equipo decide cambiar de PostgreSQL a MongoDB, la constitución debe reflejar ese cambio. De lo contrario, los slash commands seguirán generando artefactos que asumen PostgreSQL.

El enfoque recomendado es revisar la constitución periódicamente, especialmente después de cambios significativos en el stack tecnológico, la incorporación de nuevos miembros al equipo o la adopción de nuevas convenciones.

No almacenar información volátil

La memoria compartida está diseñada para almacenar principios estables del proyecto, no información que cambia con frecuencia. Datos como tokens de API, URLs de entornos de desarrollo o credenciales no pertenecen a .specify/memory/. Esa información se gestiona mejor mediante variables de entorno o archivos de configuración específicos del entorno.