- 1CLAUDE.md = contexto persistente del proyecto para la IA.
- 260-200 líneas es el sweet spot.
- 3Documentá lo que el código no cuenta: por qué, qué evitar, dónde mirar primero.
- 4Funciona con Claude Code; el patrón se replica en Cursor, Aider, etc.
Cuando empezamos a usar agentes de IA dentro de nuestro flujo de diseño y desarrollo, nos topamos con el mismo problema cada lunes: cada conversación arrancaba en cero. Re-explicar el stack, las convenciones, los nombres de las clases utilitarias y la data principal del sitio. Una y otra vez.
La solución resultó ser tan simple como un archivo Markdown en la raíz del repo: CLAUDE.md. Un documento corto — entre 60 y 200 líneas — que la IA lee automáticamente al iniciar cada sesión y que define las reglas del juego.
Qué es CLAUDE.md
CLAUDE.md es la convención de Claude Code (la CLI oficial de Anthropic) para inyectar contexto persistente del proyecto en cada conversación. La IA lo lee antes de tu primer mensaje, así que cualquier cosa escrita ahí se da por hecho.
Estructura que funciona
# Nombre del proyecto
## Stack
- Next.js 16 (App Router)
- Tailwind CSS v4 (configuración en globals.css)
- TypeScript
## Estructura
src/
app/ # Rutas
components/ # UI reutilizable
data/ # Contenido estático
## Convenciones
- Componentes client siempre con "use client"
- Imágenes externas: Unsplash con ?w=1200&q=85
- Paleta: #EAEAEA / #0A0A0A / #FF4D00
## Data principal
- content.ts contiene siteConfig, projects, services
- siteConfig.nav define la navegación
## Dev
npm run dev # http://localhost:3000