Documentos de referencia: la memoria del proyecto.
El CLAUDE.md es el contexto permanente. Pero hay información demasiado larga o específica para vivir ahí. Los documentos de referencia son la biblioteca que el agente consulta cuando la necesita — sin saturar la ventana de contexto en cada sesión.
Qué son los documentos de referencia
Archivos markdown que contienen información específica del proyecto: arquetipos de usuario, tokens del design system, decisiones de producto, patrones de componentes.
El agente no los carga siempre — los lee cuando una tarea los necesita. Eso los hace distintos del CLAUDE.md, que sí se carga en cada sesión.
CLAUDE.md
Siempre presente- Cargado en cada sesión automáticamente
- Comportamiento, tono, restricciones del agente
- Corto y denso — cada línea ocupa contexto
No es el lugar para información extensa
Documentos de referencia
Solo cuando se necesitan- El agente los lee cuando la tarea los requiere
- Información específica y extensa del proyecto
- Se actualizan de forma independiente
- No saturan el contexto en tareas que no los usan
Skills
Procesos especializados- Define pasos a seguir, no solo información
- Incluye qué documentos leer y en qué orden
- Garantiza un output consistente y reproducible
No es un repositorio de información, es un proceso
Analogía
El CLAUDE.md es el briefing que siempre tienes en la mesa. Los documentos de referencia son la biblioteca que consultas cuando necesitas un dato concreto. Las skills son el proceso de trabajo que sigues para hacer una tarea bien.
Por qué no todo va en el CLAUDE.md
Tres problemas de meter todo en un solo archivo — y cómo los documentos de referencia los resuelven.
Sin documentos de referencia
CLAUDE.md de 800 líneas
Metes todo en el CLAUDE.md: arquetipos, tokens, decisiones, roadmap. El agente lo carga entero en cada sesión, compitiendo con el trabajo real por la ventana de contexto.
Contexto obsoleto
Cuando algo cambia — un arquetipo, una decisión, un token — hay que encontrarlo en el bloque monolítico y editarlo. El equipo deja de actualizarlo.
El agente trabaja con ruido
En una tarea sobre tokens, el agente también carga los arquetipos de usuario. Información irrelevante que no ayuda y ocupa espacio.
Con documentos de referencia
CLAUDE.md de 200 líneas
El CLAUDE.md solo tiene punteros: /docs/users.md, /design-system/tokens.md. El agente sabe que existen y los lee cuando la tarea lo requiere.
Cada documento, su responsable
El lead de diseño actualiza users.md tras cada ronda de research. El dev toca tokens.md cuando cambia el sistema. Sin coordinación, sin conflictos.
Contexto quirúrgico
Una skill de auditoría le dice al agente "lee primero components.md y luego tokens.md". Carga exactamente lo que necesita. Nada más.
Qué documentos y dónde van
Los documentos de referencia organizados en dos carpetas: contexto de producto y design system.
docs/ — Contexto de producto y decisiones
product-vision.md
Objetivos del producto, métricas de éxito, roadmap de alto nivel. El agente lo consulta cuando propone features o evalúa si algo encaja con la dirección del producto.
¿Cuándo lo lee? Cuando le pides evaluar una propuesta o priorizar trabajo.
users.md
Arquetipos de usuario, jobs-to-be-done, niveles de conocimiento técnico. Sin esto, el agente diseña para un usuario genérico que probablemente no es el tuyo.
¿Cuándo lo lee? En tareas de UX, flujos, microcopy o cualquier decisión centrada en usuario.
decisions-log.md
Decisiones tomadas y descartadas con su razonamiento. El documento más infravalorado del proyecto. Sin él, el agente puede proponer esta semana lo que el equipo rechazó el mes pasado.
¿Cuándo lo lee? Antes de proponer cualquier solución de diseño o arquitectura.
competitive.md
Análisis de competidores: qué hacen bien, qué hacen mal, en qué nos diferenciamos. Útil cuando el agente propone patrones de interacción o posicionamiento de features.
¿Cuándo lo lee? En tareas de posicionamiento, naming o cuando propones un flujo nuevo.
design-system/ — La fuente de verdad de diseño
tokens.md
Todos los valores del sistema: color, tipografía, espaciado, sombras, radios. Generado desde Style Dictionary. El agente nunca inventa tokens si este documento existe y está bien referenciado.
¿Cuándo lo lee? En cualquier tarea que toque estilos, especificaciones o código de componentes.
components.md
Inventario de componentes existentes: nombre, variantes, estados, cuándo usar cada uno. Evita que el agente proponga componentes nuevos cuando ya existe uno que cumple la función.
¿Cuándo lo lee? En auditorías, especificaciones de entrega y cuando crea componentes nuevos.
patterns.md
Patrones de interacción recurrentes: cómo el sistema maneja errores, estados vacíos, carga, confirmaciones destructivas. La guía de comportamiento del sistema.
¿Cuándo lo lee? En tareas de flujo, estados de UI y cuando diseñas nuevas interacciones.
accessibility.md
opcionalCriterios de accesibilidad específicos del producto: niveles WCAG objetivo, patrones de teclado, roles ARIA habituales. El agente los aplica sin que tengas que recordárselo.
¿Cuándo lo lee? En cualquier tarea con componentes interactivos o especificaciones de entrega.
El decisions-log.md merece atención especial
Cada decisión descartada se apunta aquí con el razonamiento. El agente no volverá a proponer lo que ya rechazasteis. Y cuando alguien nuevo se incorpora al equipo, tiene el contexto de meses de decisiones en minutos. Es el documento más infravalorado y el que más impacto tiene.
Estructura de carpetas
La organización recomendada para los documentos de referencia.
Proyecto editorial — ejemplo
docs/
Información de producto y negocio. Arquetipos, visión, decisiones pasadas, guías de contenido. El agente los consulta cuando la tarea involucra usuarios o estrategia de producto.
design-system/
Documentación técnica del sistema de diseño. Tokens, componentes, patrones, accesibilidad. El agente los consulta en tareas de auditoría, specs y revisión de componentes.
La carpeta no importa, el nombre sí
Puedes organizar los docs como quieras. Lo que importa es que el CLAUDE.md o la skill diga explícitamente dónde están y cuándo leerlos.
Cuándo y cómo los lee el agente
Tres modos en los que el agente accede a los documentos de referencia.
Referenciado desde el CLAUDE.md
Automático· bajo demandaEn el bloque de archivos de referencia del CLAUDE.md incluyes la ruta y una instrucción: "Lee este archivo antes de tareas de UX". El agente decide cuándo es relevante y lo carga.
Instrucción en una skill
Explícito· controladoUna skill de auditoría incluye en su proceso: "Leer primero /design-system/components.md y luego /design-system/tokens.md". El agente siempre sigue ese orden cuando ejecuta la skill.
Pedido directamente en el prompt
Manual· puntualEn tu mensaje escribes: "Antes de responder, lee /docs/users.md". Simple y efectivo cuando necesitas contexto puntual sin modificar ningún archivo de configuración.
La regla de oro
¿Dónde vive esta información? Tres preguntas para decidir.
¿Cambiará con el tiempo?
Si la información evoluciona (arquetipos, tokens, decisiones), va en su propio archivo.
-> /docs/ o /design-system/
¿Es siempre cierto?
Si es una regla permanente del proyecto (restricciones, stack, convenciones), va en el briefing principal.
-> CLAUDE.md
¿Solo aplica a esta tarea?
Si es una instrucción puntual que no aplica a otras sesiones, va directamente en el mensaje.
-> El prompt