CLAUDE.md es un archivo de texto que vive en tu carpeta de proyecto. Cada vez que abrís Claude Code, él lo lee primero. Ahí ponés quién sos, cómo está estructurado el código, qué reglas no puede romper, y cómo trabajás vos. Una vez que lo escribís bien, no volvés a repetirte nunca más.
Cuando abrís Claude Code en una carpeta de proyecto, lo primero que hace es buscar un archivo llamado CLAUDE.md en esa carpeta. Si lo encuentra, lo lee completo antes de hacer cualquier cosa. Es su briefing de incorporación.
Sin ese archivo, Claude arranca sin contexto. No sabe si estás construyendo una tienda online o una app médica. No sabe si usás TypeScript o Python. No sabe qué partes del código no debe tocar. Tiene que adivinar, y cuando adivina, se equivoca.
Con un buen CLAUDE.md, Claude sabe exactamente dónde está parado desde el primer mensaje. Menos correcciones, menos idas y vueltas, mejor código desde el primer intento.
Claude hace suposiciones sobre tu stack, tu estilo y tus reglas. Tenés que corregirlo en cada sesión.
Tiempo perdido. Código inconsistente.
Claude sabe tu stack, tus convenciones, lo que no puede tocar y cómo tomás decisiones.
Contexto instantáneo. Cada sesión arranca bien.
Un CLAUDE.md que funciona tiene cinco bloques. Podés agregarle más, pero estos cinco son los que Claude realmente usa para tomar mejores decisiones.
No es un pitch de ventas ni un README para GitHub. Es contexto para Claude. Explicá qué hace la app, quién la usa y cuál es el core que no puede fallar.
"Una plataforma educativa con cursos online."
Claude no sabe nada útil
"Academia de IA para emprendedoras sin background técnico. El core es el área de alumnas: acceso a cursos, progreso y comunidad."
Claude entiende prioridades y audiencia
Listá las tecnologías principales. Solo las que Claude necesita para tomar decisiones: ¿Uso fetch o axios? ¿Guardo en localStorage o en la base de datos? ¿Hay un ORM o queries directas?
## Stack técnico - Frontend: Next.js 14 (App Router) — NO Pages Router - Base de datos: Supabase (Postgres + Auth + Storage) - Deploy: Vercel (rama main = producción automática) - Pagos: Stripe (webhooks en /api/webhooks/stripe) - Estilos: Tailwind CSS — sin CSS modules - ORM: ninguno — queries directas con Supabase
La más importante. Claude, por defecto, puede hacer cambios que no pediste si cree que mejoran el código. Las reglas son la forma de controlarlo.
## Reglas que NO debes romper // Archivos protegidos - No toques /lib/auth.ts sin avisarme primero - No modifiques /middleware.ts // Antes de actuar - No cambies el esquema de la BD sin mostrarme el migration primero - No instales dependencias sin preguntarme // Convenciones de código - Siempre escribe comentarios en español - Nunca uses `any` en TypeScript // Estilo de respuesta - Si hay más de una solución, dame opciones antes de implementar - Si detectás un bug que no pedí, avisame pero no lo toques sin permiso
Claude no puede ver tu Notion. Esta sección le dice en qué punto está el proyecto para que no rompa lo que ya funciona ni intente implementar algo que ya existe.
## Estado actual del proyecto ✅ Autenticación con Supabase lista ✅ Landing page desplegada en Vercel ✅ Módulo 1 del curso subido y funcionando 🔄 En progreso: pasarela de pagos con Stripe ❌ Pendiente: área de miembros ❌ Pendiente: dashboard de progreso de alumnas
La más ignorada y la que más diferencia hace. Definís la dinámica: cuándo querés opciones, cuánto detalle en las explicaciones, qué hacer si encuentra un bug que no pediste.
## Cómo trabajo yo - Primero entendé el problema, luego el código. No me des soluciones antes de confirmar que entendiste bien qué pido. - Si algo tiene más de una forma de hacerse, dame opciones con pros y contras antes de elegir una. - Prefiero código legible sobre código "inteligente". Simple siempre gana. - No expliques lo que hiciste línea por línea. Explicame el porqué cuando no sea obvio. - Si ves algo que se podría mejorar pero no te lo pedí, mencionalo pero no lo toques.
Copiá esto, pegalo en un archivo llamado CLAUDE.md en la raíz de tu proyecto, y reemplazá cada sección con tu información real. Un CLAUDE.md básico ya es mejor que ninguno.
# CLAUDE.md — [Nombre de tu proyecto] ## ¿Qué es este proyecto? [Descripción de 2-3 oraciones: qué hace la app, para quién es y cuál es la función más importante.] ## Stack técnico - Frontend: [framework y versión] - Base de datos: [servicio] - Deploy: [plataforma] - Pagos: [servicio, si aplica] - Estilos: [framework de CSS] - [Cualquier otro servicio clave] ## Reglas que NO debes romper - No toques [archivo crítico] sin avisarme - No cambies el esquema de la BD sin mostrarme la migration primero - No instales dependencias sin preguntarme - [Tus convenciones de código] - [Tus preferencias de estilo] ## Estado actual del proyecto ✅ [Qué ya funciona] ✅ [Qué ya funciona] 🔄 En progreso: [qué estás construyendo ahora] ❌ Pendiente: [qué falta] ❌ Pendiente: [qué falta] ## Cómo trabajo yo - [Tu proceso de decisión] - [Cuándo querés opciones antes de implementar] - [Qué nivel de explicación preferís] - [Qué hacer si encuentra un bug que no pediste] ## Contexto de negocio (opcional) - [Precio del producto, si ayuda a priorizar] - [El pain principal de tu usuario] - [El tono de la plataforma]
Abrí tu proyecto, creá un archivo CLAUDE.md en la raíz
y completá las 5 secciones. Tarda menos de 20 minutos.
Ese tiempo lo recuperás en la primera sesión.