Dale memoria de IA a tu proyecto con archivos Markdown en el repositorio

Tarde o temprano, todo desarrollador que trabaja con un asistente de IA se topa con el mismo muro. Le pides que monte la autenticación de tu app en Next.js y la respuesta es buena. Luego le dices «ahora conéctalo a mi esquema de usuarios actual» y actúa como si nunca hubiera visto el proyecto. No tiene ni idea de:

• tu estructura de carpetas
• tu esquema de base de datos
• tus estándares de código
• las decisiones que tomaste sobre las funciones
• por qué existen ciertos archivos
• qué evitaste a propósito

Así que vuelves a explicarlo todo, una y otra vez. En algún momento queda claro que el problema no es el modelo. Es la memoria.

La solución sale barata: guarda una memoria del proyecto en archivos Markdown dentro del repositorio, para que el asistente empiece cada sesión sabiendo ya cómo funciona el proyecto. No depende de Claude de Anthropic. Los modelos de OpenAI, Gemini y cualquier otro asistente de código pueden leer los mismos archivos.

Qué es la memoria del proyecto

Es una capa de conocimiento persistente para tu código. El historial del chat desaparece, así que guardas conocimiento estructurado del proyecto en el propio repositorio:

• a qué se dedica el negocio y por qué
• cómo está construido el sistema
• qué funciones se lanzaron y cuándo
• cómo se relacionan los archivos entre sí
• convenciones de código
• el razonamiento detrás de decisiones pasadas
• contratos de API
• esquemas de base de datos

En la práctica, tu repositorio pasa a documentarse solo, en un formato que una IA puede leer. Eso importa, porque sin contexto un modelo adivina y con contexto se vuelve mucho más útil.

Por qué merece la pena

Piensa en lo que le darías a un ingeniero senior nuevo el primer día: documentación de arquitectura, guía de instalación, estructura de carpetas, documentación de la API, una explicación de la lógica de negocio, la hoja de ruta, los problemas conocidos y las convenciones de código. Una IA necesita el mismo material, y lo asimila al instante.

Compara los prompts. Sin memoria solo puedes preguntar algo genérico como «explícame mi flujo de pagos». Con ella puedes pedir «añade reintentos a los webhooks fallidos de Razorpay siguiendo nuestra arquitectura de eventos actual». Uno es vago y el otro, preciso.

La carpeta de memoria

Pon una carpeta oculta en la raíz del repositorio, junto a tus directorios de código:

/project-root
 ├── src
 ├── components
 ├── services
 ├── .ai-memory

Y dentro de .ai-memory:

.ai-memory/
├── project-overview.md
├── architecture.md
├── folder-structure.md
├── database-schema.md
├── api-contracts.md
├── coding-guidelines.md
├── feature-history.md
├── active-tasks.md
├── known-issues.md
├── decision-log.md

Es sencillo, legible y está bajo control de versiones. Hace de cerebro del proyecto. Cada archivo tiene su función.

project-overview.md

Es el archivo más importante. Explica qué hace el proyecto, quién lo usa, qué problema resuelve y cuáles son sus funciones principales. Por ejemplo:

# Project Overview

Project Name: DevResume AI
Purpose:
A SaaS platform where developers create digital resumes,
ATS-friendly resumes, and portfolio profiles.
Primary Users:
- Developers
- Students
- Recruiters
Core Features:
- Resume builder
- Portfolio generator
- Job tracker
- AI interview prep

Sin él, la IA solo ve código. Con él, entiende para qué sirve ese código, y eso cambia la calidad de todo lo que sugiere.

architecture.md

Describe cómo está montada la app:

# Architecture

Frontend:
- Next.js 16
- React 19
- Tailwind CSS
Backend:
- Node.js
- Express
Database:
- PostgreSQL
Authentication:
- NextAuth
Storage:
- AWS S3
Deployment:
- Vercel

Así la IA deja de proponer el stack equivocado y te ahorras muchas correcciones.

folder-structure.md

Enseña la relación entre archivos, con una breve explicación junto a cada directorio:

src/
 ├── app/
 ├── modules/
 ├── shared/
 ├── services/
 ├── hooks/

/modules = feature-based architecture
/shared = reusable UI
/services = API integrations
/hooks = custom hooks

El asistente sabe entonces dónde va el código nuevo y se acaban los archivos colocados al azar.

database-schema.md

Este vale oro:

User
- id
- name
- email
- role
Resume
- id
- userId
- templateId
- content
Portfolio
- id
- userId
- slug

Con el esquema a mano, la IA escribe consultas, migraciones, joins y validaciones con precisión.

api-contracts.md

Documenta tus API:

POST /api/auth/login
Request:
{
 email: string
 password: string
}

Response:
{
 token: string
 user: object
}

La recompensa es código de frontend listo para integrar, basado en contratos reales y no en suposiciones.

feature-history.md

Lleva un registro de lo que ya se ha lanzado:

# Feature History

v1.0
- Authentication
- Resume Builder
v1.1
- Portfolio Export
v1.2
- AI Resume Suggestions

Así la IA no reconstruye cosas que ya tienes, una ventaja grande y poco valorada.

decision-log.md

Anota por qué se tomaron las decisiones:

Decision:
Used PostgreSQL instead of MongoDB.

Reason:
Need relational joins for resume templates.

Ahora el asistente no propondrá una arquitectura que ya descartaste. Este archivo por sí solo puede ahorrarte horas.

Memoria por función

Para más detalle, dale a cada función su propio archivo de memoria:

/features/auth/auth.memory.md
/features/payments/payments.memory.md
/features/profile/profile.memory.md

Uno típico tiene este aspecto:

# Auth Feature

Purpose:
Handles login/signup.
Flow:
Signup → Verify Email → Create Profile → Generate JWT
Files:
- auth.service.ts
- auth.controller.ts
- auth.routes.ts
Known edge cases:
- Duplicate emails
- Expired tokens

Eso aporta un contexto muy local, casi a nivel de componente.

Prompts para crearla y mantenerla

Para arrancar la memoria de un proyecto que ya existe, usa este prompt:

Analyze my entire project and generate AI memory files.

Create:
1. project-overview.md
2. architecture.md
3. folder-structure.md
4. database-schema.md
5. api-contracts.md
6. feature-history.md
7. known-issues.md
8. coding-guidelines.md
9. decision-log.md
Rules:
- Read all folders
- Understand relationships
- Summarize clearly
- Keep markdown structured
- Mention business logic
- Mention important dependencies
- Mention reusable patterns

Para una función cada vez, este prompt genera su archivo, y escala bien:

Analyze this feature folder and create featureName.memory.md.

Include:
- Feature purpose
- Business logic
- File roles
- API dependencies
- Database dependencies
- Edge cases
- Future improvements
- Current limitations

Cuando se integre trabajo nuevo, ejecuta un prompt de actualización. Es fundamental, porque una memoria desactualizada es peligrosa:

Update my AI memory files based on the new changes.

Check:
- New files
- Modified APIs
- Schema changes
- New feature flows
- New dependencies
- New business logic
Update only relevant markdown files.

Hábitos que la mantienen útil

• Mantenla ligera. No escribas novelas: los modelos rinden mejor con textos claros y breves.
• Versiónala con Git. Haz commit, revísala y deja que evolucione como el código.
• Actualízala después de cada función importante. La regla es sencilla: función lanzada, memoria actualizada. Sin excepciones.
• Usa Markdown sin más. Es universal, portátil y se lee en cualquier parte.

No es solo para Claude

La misma configuración funciona con Claude Code, OpenAI Codex, GitHub Copilot, Cursor, Google Gemini CLI y Windsurf. Lo que hace que funcione no es el modelo. Es la memoria.

La idea de fondo

Muchos desarrolladores tratan a la IA como un chatbot. Los compañeros de equipo necesitan contexto, y una simple carpeta .ai-memory basta para convertir los prompts repetitivos en colaboración de verdad. Cuando el proyecto tiene memoria, el asistente deja de comportarse como un becario y empieza a comportarse más como un arquitecto. Es de esperar que en un par de años esto sea práctica habitual de ingeniería, así que vale la pena empezar ya.