El archivo CLAUDE.md: qué va aquí dentro.

Menos de 300 líneas. Cada línea que añades compite con el trabajo real por la ventana de contexto del agente. Si tienes dudas, fuera.

Solo lo que es cierto en todas las sesiones. Lo específico de una tarea va en una skill o en el propio prompt, no aquí.

Lo que el agente no debe hacer es más valioso que lo que sí puede hacer. Una restricción bien puesta evita trabajo rehecho.

Se actualiza con el proyecto. Cambia de stack, cambia el CLAUDE.md. Nuevo sprint, actualiza el bloque de sprint. Es parte del ritual del equipo.

El punto de partida. Nombre, tipo de producto y estado actual. Dos o tres frases que describan qué problema resuelve y para quién. No escribas un brief de 20 líneas. Si el agente necesita más contexto sobre la visión del producto, tiene /docs/product-vision.md para eso.

# Qué es este proyecto
**Nombre:** Plataforma de gestión editorial
**Tipo:** Web app B2B
**Estado:** Diseño — fase 2
Herramienta para equipos de contenido
que necesitan coordinar publicación...

Lista de personas con sus roles. Parece básico pero es muy útil: el agente adapta el nivel de detalle técnico de sus entregables según sepa si el receptor es un diseñador, un developer o un PM. Añade también el canal de comunicación preferido si es relevante.

# Equipo y roles
- **Ana** — Lead diseño de producto
- **Marc** — Frontend
- **Laia** — Product Manager
Entregables principales -> desarrollo.
Nivel técnico: intermedio.

El stack tecnológico y de diseño que usa el proyecto. Figma, librería de componentes, framework de frontend, sistema de tokens, control de versiones. No necesitas documentar cómo funcionan. Solo que existen y se usan en este proyecto.

# Stack y herramientas
- Figma (componentes + tokens)
- Style Dictionary -> tokens.md
- Next.js + Tailwind + shadcn/ui
- Storybook (componentes)
- Git / GitHub

Las convenciones de naming son críticas para que el código generado encaje sin retrabajo. PascalCase para componentes, kebab-case para tokens y archivos. Una tabla simple es suficiente. Si hay casos especiales o excepciones, inclúyelos aquí.

# Convenciones de nomenclatura
Componentes -> PascalCase
  ej: ProductCard, UserAvatar
Tokens -> kebab-case
  ej: color-brand-primary
Archivos -> kebab-case
  ej: product-card.jsx

2 o 3 principios de diseño específicos del proyecto. No los valores genéricos de "simplicidad y elegancia" que aplican a cualquier producto — los que son propios de este proyecto y de sus usuarios. El agente los usa como criterio cuando propone soluciones o evalúa alternativas.

# Principios de diseño
1. Claridad antes que densidad
2. El flujo manda sobre la forma
3. Consistencia > originalidad
Valida cualquier propuesta contra
estos principios antes de presentarla.

La sección más infrautilizada y la más poderosa. Una lista de prohibiciones concretas evita los errores más costosos: proponer componentes que no existen, generar copy en el idioma equivocado, inventar tokens. Cada restricción viene de un error que ya cometiste o que anticipas. Añádela la primera vez que pase.

# Restricciones — qué NO hacer
- No usar iconos externos (usamos Phosphor)
- No generar copy en inglés
- No inventar tokens nuevos
- No proponer componentes inexistentes
- No asumir usuario tech-savvy

Una lista de los archivos clave del proyecto con una línea de descripción de cada uno. No copies el contenido aquí — apunta dónde está. Añade la instrucción de cuándo leerlos: "Lee el archivo relevante antes de actuar en tareas relacionadas."

# Archivos de referencia
/docs/product-vision.md
/docs/users.md
/docs/decisions-log.md
/design-system/tokens.md
/design-system/components.md
Lee el archivo relevante antes de actuar.

El único bloque que cambia regularmente. Objetivo del sprint, en qué pantallas o flujos se está trabajando y qué decisiones están pendientes. Actualízalo al inicio de cada sprint. Sin esto, el agente puede proponer trabajo en áreas que ya están cerradas o ignorar el foco actual del equipo.

# Sprint actual
**Objetivo:** rediseño del flujo de publicación
**Trabajando en:** pantallas de revisión
**Pendiente:** decidir patrón de aprobación
# <- esto cambia cada 2 semanas

Claude Code analiza tu proyecto y propone un CLAUDE.md inicial. Úsalo como punto de partida, no como producto final. Elimina lo que no aplique y añade las restricciones del proyecto.

$ claude /init
-> genera CLAUDE.md
-> revisa y elimina

Solo el bloque 08. Hazte estas tres preguntas antes de cerrar la planning:

• ¿En qué pantallas o flujos vamos a trabajar esta semana?
• ¿Qué decisiones de diseño están abiertas o bloqueadas?
• ¿Cambió algo del sprint anterior que el agente deba saber?

Ejemplo real: "Arrancamos el sprint con el equipo preguntando al agente por el estado del flujo de onboarding. Como no habíamos actualizado el CLAUDE.md, propuso trabajo sobre pantallas que ya estaban cerradas."

No hace falta una revisión completa. Basta con identificar el disparador:

• Se incorpora alguien nuevo -> actualiza Equipo y roles
• Cambiáis de Tailwind a CSS Modules -> actualiza Stack
• El agente propone algo que ya rechazasteis -> añade una Restricción
• Cambia el foco del producto -> actualiza Principios
• Os dais cuenta de que los usuarios no son técnicos -> actualiza Audiencia

Ejemplo real: "El agente seguía proponiendo componentes en inglés. Añadimos 'No generar copy en inglés' a restricciones. No volvió a pasar."