Toolbox — Sesión 03: Gestión de memoria y contexto con archivos .md

Objetivo de la sesión

Al terminar esta sesión serás capaz de:

Crear un CLAUDE.md (o equivalente) que haga productiva a la IA desde el primer minuto
Estructurar la memoria de proyecto con archivos .md especializados
Diseñar una jerarquía de carpetas que la IA entienda sin explicación
Gestionar contexto entre sesiones sin perder información
Aplicar estos patrones a cualquier herramienta IA, no solo Claude Code

Vídeo: Antes y después de un CLAUDE.md bien escrito

La diferencia de un archivo que cambia todo

2:30 min

Abrir un proyecto SIN CLAUDE.md. Pedir a Claude Code "añade un endpoint de login". Ver respuesta genérica. Crear CLAUDE.md con stack, convenciones, reglas. Repetir la misma petición. Ver como la respuesta usa el stack correcto, respeta convenciones, no rompe nada.

Próximamente

1. CLAUDE.md: el archivo más importante de tu proyecto

Que es

CLAUDE.md es un archivo en la raíz de tu proyecto que Claude Code lee automáticamente al empezar cada sesión. Es como darle a un nuevo compañero de trabajo el manual del proyecto el primer día.

Pero el concepto aplica a cualquier IA: es tu "briefing de proyecto" en formato archivo.

Por que importa tanto

Sin CLAUDE.md, cada sesión empieza de cero. Le explicas el stack, las convenciones, los archivos importantes. Con CLAUDE.md, la IA ya sabe todo eso. Cada sesión empieza donde la anterior termino.

Estructura básica


    # CLAUDE.md — [Nombre del proyecto]
    
    ## Que es este proyecto
    [1-3 frases: que hace, para quien, problema que resuelve]
    
    ## Stack
    - Frontend: [framework, librerias clave]
    - Backend: [framework, lenguaje]
    - Base de datos: [tipo, ORM]
    - Deploy: [donde]
    - CI/CD: [como]
    
    ## Convenciones
    - Nombrado: [snake_case, camelCase, etc.]
    - Estructura: [donde van los componentes, rutas, etc.]
    - Commits: [formato, idioma]
    - Testing: [framework, donde van los tests]
    
    ## Archivos importantes
    - `src/config.ts` — configuracion principal
    - `src/lib/db.ts` — conexion a base de datos
    - [otros archivos que la IA debe conocer]
    
    ## Reglas
    - [lo que NUNCA debe hacer]
    - [lo que SIEMPRE debe hacer]
    - [restricciones especificas]
    
    ## Comandos utiles
    - `npm run dev` — servidor desarrollo
    - `npm run build` — build produccion
    - `npm run test` — ejecutar tests

Errores comunes en CLAUDE.md

Error	Problema	Solución
Demasiado largo (>200 líneas)	La IA diluye atención	Máximo 100-150 líneas. Lo esencial
Copiar el README	README es para humanos, CLAUDE.md para IA	Escribir instrucciones para la IA, no documentación
No actualizar	CLAUDE.md de hace 3 meses con stack viejo	Actualizar cada vez que cambie algo importante
Demasiado genérico	"Escribe buen código" no dice nada	Ser específico: "Usa Zod para validación de inputs"
Incluir secretos	Passwords, tokens en el archivo	NUNCA. Usar .env y referenciar: "Secrets en .env"

2. Archivos .md especializados

CLAUDE.md no es suficiente

Para proyectos medianos o grandes, un solo archivo no cubre todo. Necesitas archivos especializados.

Jerarquía recomendada


    mi-proyecto/
      CLAUDE.md              ← Contexto global (siempre se lee)
      PRODUCT.md             ← Que es el producto, usuarios, objetivo
      DESIGN.md              ← Sistema de diseno, colores, tipografia, componentes
      WORKPLAN.md            ← Plan actual, tareas pendientes, prioridades
      docs/
        ADR-001-elegir-db.md ← Decisiones arquitectonicas
        ADR-002-auth.md
      .claude/
        commands/            ← Comandos custom reutilizables
        settings.json        ← Configuracion de Claude Code

PRODUCT.md: que es tu producto


    # Product
    
    ## Platform
    web / mobile / desktop / CLI
    
    ## Users
    [Quien usa esto, que busca, que nivel tecnico tiene]
    
    ## Product Purpose
    [Que problema resuelve, como mide exito]
    
    ## Brand Personality
    [Tono, estilo, anti-referencias]

La IA consulta PRODUCT.md cuando necesita tomar decisiones de producto: que texto poner, que flujo diseñar, que priorizar.

DESIGN.md: sistema de diseño


    # Design System
    
    ## Colors
    - Primary: #... — [cuando usarlo]
    - Secondary: #...
    - Background: #...
    - Text: #...
    
    ## Typography
    - Headlines: [fuente, peso, tamanos]
    - Body: [fuente, peso]
    
    ## Components
    - Buttons: [estilos, tamanos, estados]
    - Cards: [estructura, sombras, bordes]
    - Forms: [inputs, labels, errores]
    
    ## Spacing
    - Base unit: [4px, 8px]
    - Section padding: [...]
    
    ## Anti-patterns
    - [lo que NO usar]

Con DESIGN.md, la IA genera frontend que respeta tu marca sin que le expliques los colores cada vez.

WORKPLAN.md: estado actual


    # Workplan
    
    ## Prioridad actual
    [Que estamos haciendo AHORA y por que]
    
    ## Tareas pendientes
    - [ ] [tarea 1] — [contexto breve]
    - [ ] [tarea 2]
    - [x] [tarea completada]
    
    ## Decisiones recientes
    - [fecha]: [decision y razon]
    
    ## Bloqueantes
    - [que esta parado y por que]

Actualiza WORKPLAN.md al final de cada sesión. La próxima sesión empieza con contexto fresco.

ADRs: decisiones arquitectonicas

ADR = Architecture Decisión Record. Un archivo corto que documenta POR QUE tomaste una decisión técnica.


    # ADR-001: Elegir Supabase como base de datos
    
    ## Contexto
    Necesitamos DB con auth integrado, RLS para multi-tenant, y free tier generoso.
    
    ## Decision
    Supabase PostgreSQL.
    
    ## Alternativas evaluadas
    - PlanetScale: sin RLS, MySQL (no PostgreSQL)
    - Neon: bueno pero sin auth integrado
    - Self-hosted PG: mas trabajo de setup
    
    ## Consecuencias
    - Dependencia de Supabase para auth
    - Migracion a PG puro posible si necesario

La IA lee los ADRs cuando necesita entender por que el proyecto esta disenado así. Evita que sugiera alternativas que ya descartaste.

3. Estructura de carpetas que la IA entiende

Principio: nombres descriptivos, estructura predecible

La IA infiere contexto de los nombres de carpetas y archivos. Cuanto más descriptivos, menos explicación necesita.

Estructura Next.js recomendada


    src/
      app/                   ← Rutas (App Router)
        (auth)/              ← Grupo rutas auth
        (dashboard)/         ← Grupo rutas dashboard
        api/                 ← API routes
      components/
        ui/                  ← Componentes genericos (botones, inputs)
        features/            ← Componentes de dominio (UserCard, InvoiceTable)
        layout/              ← Header, Footer, Sidebar
      lib/
        db.ts                ← Conexion DB
        auth.ts              ← Logica auth
        utils.ts             ← Utilidades puras
      hooks/                 ← Custom hooks React
      types/                 ← TypeScript types compartidos
      config/                ← Configuracion app

Estructura FastAPI recomendada


    app/
      main.py                ← Entrypoint
      config.py              ← Settings
      api/
        v1/
          routes/            ← Endpoints por dominio
          deps.py            ← Dependencies (auth, db session)
      models/                ← SQLAlchemy/Pydantic models
      schemas/               ← Pydantic schemas (request/response)
      services/              ← Logica de negocio
      workers/               ← Tareas async (Celery/background)
      utils/                 ← Utilidades
    tests/
      test_api/
      test_services/

Regla: si un nuevo developer (o IA) no sabe donde poner un archivo mirando la estructura, la estructura esta mal.

4. Gestión de contexto entre sesiones

El problema

Cada sesión de IA empieza sin memoria de la anterior. Has avanzado 2 horas en una tarea, cierras, abres mañana y la IA no sabe nada.

Solución: checkpoint al final de cada sesión

Al terminar una sesión, pide:


    Resume en un bloque de texto:
    1. Que hicimos hoy
    2. Estado actual del trabajo
    3. Decisiones tomadas
    4. Tareas pendientes
    5. Problemas encontrados
    
    Formato para pegar en WORKPLAN.md

Pega ese resumen en WORKPLAN.md. La próxima sesión, la IA lo lee automáticamente.

Solución avanzada: archivos de memoria persistente

Para proyectos largos, crea una carpeta de memoria:


    .claude/
      memory/
        decisions.md          ← Decisiones acumuladas
        learnings.md          ← Cosas que la IA aprendio sobre el proyecto
        context.md            ← Contexto que cambia (sprint actual, prioridades)

Claude Code puede escribir en estos archivos al final de cada sesión si se lo pides. La próxima sesión los lee y tiene continuidad.

Patrón de "handoff"


    Al terminar cada sesion, escribe en .claude/memory/context.md:
    - Fecha
    - Que se hizo
    - Estado de cada tarea (completada / en progreso / pendiente)
    - Proximos pasos sugeridos

5. Estos patrones en otras herramientas

ChatGPT

CLAUDE.md → Custom Instructions (campo "que quieres que ChatGPT sepa")
PRODUCT.md → Archivo subido en GPT custom (Knowledge)
DESIGN.md → Archivo subido en GPT custom
No hay equivalente a lectura automática de archivos locales

Gemini

CLAUDE.md → Gem instructions
PRODUCT.md + DESIGN.md → Fuentes en NotebookLM
No hay equivalente a WORKPLAN.md dinámico

Cursor / Windsurf

CLAUDE.md → .cursorrules (Cursor) o .windsurfrules (Windsurf)
Misma lógica: archivo en raíz que el editor IA lee automáticamente
Estructura idéntica

Principio universal


    Archivo de contexto en raiz + archivos especializados por dominio
    = IA productiva desde el primer mensaje de cada sesion

6. Lab práctico: Estructura tu proyecto

Instrucciones

Elige un proyecto (real o nuevo) y crea toda la estructura de archivos .md. 25 minutos.

Paso 1: CLAUDE.md (10 min)

Escribe el CLAUDE.md de tu proyecto usando la plantilla de la sección 1. Máximo 100 líneas.

Paso 2: Archivos especializados (10 min)

Crea al menos 2 de estos:

PRODUCT.md
DESIGN.md
WORKPLAN.md
Un ADR

Paso 3: Prueba (5 min)

Abre Claude Code (o tu IA con archivos) en el proyecto. Pidele una tarea sin darle contexto extra. Respeta las convenciones del CLAUDE.md? Usa el stack correcto? Si no, ajusta el CLAUDE.md.

Evaluación

Criterio	Si	No
La IA conoce el stack sin que se lo digas?	[ ]	[ ]
Respeta las convenciones de naming?	[ ]	[ ]
Sabe donde crear archivos nuevos?	[ ]	[ ]
No sugiere tecnologías que descartaste en ADRs?	[ ]	[ ]

Entregable de la sesión

Tu estructura .md completa lista para usar en tu proyecto.


    ESTRUCTURA DE CONTEXTO
    =======================
    
    Proyecto: _________________________________
    Archivos creados:
      [ ] CLAUDE.md (_____ lineas)
      [ ] PRODUCT.md
      [ ] DESIGN.md
      [ ] WORKPLAN.md
      [ ] ADR-001: _________________________________
      [ ] .claude/memory/ configurado
    
    Test con IA: [ ] Paso  [ ] Necesita ajustes
    
    Proxima revision: ____/____/2026

Recursos descargables

Templates .md por tipo de proyecto (GitHub repo) — CLAUDE.md, PRODUCT.md, DESIGN.md para Next.js, FastAPI, fullstack
Checklist estructura proyecto (PDF) — Verificación rápida de que no falta nada
Guía de ADRs (PDF) — Como escribir decisiones arquitectonicas que la IA respete

Siguientes pasos

En la siguiente sesión (AB-04: Estructura de proyecto IA) vas a diseñar la arquitectura de carpetas y módulos para proyectos que incluyen agentes IA. De la estructura general a la estructura específica para IA.

Antes de pasar a AB-04, asegurate de que:

Has creado CLAUDE.md para al menos 1 proyecto
Has probado que la IA respeta el contexto sin explicación extra
Has configurado un sistema de checkpoints entre sesiones

Toolbox — Sesión 03 de 09

IAcademy — iacedemy.com