CLAUDE.md es un archivo markdown simple en la raíz de tu proyecto. Claude lo lee automáticamente en cada sesión. Nivel de proyecto: ./CLAUDE.md. Global (todos los proyectos): ~/.claude/CLAUDE.md. El proyecto anula lo global: el archivo global contiene tus valores predeterminados, el archivo del proyecto contiene las especificaciones de este repositorio.
Piensa en él como el documento de incorporación que le das a un contratista altamente calificado que no sabe nada sobre tu proyecto. Sin él, cada sesión comienza con Claude adivinando tu stack, tus convenciones de nombres y tus decisiones pasadas. Las suposiciones se convierten en código, el código se convierte en errores. CLAUDE.md acorta esa cadena. Un archivo es mejor que un prompt inteligente porque funciona, lo recuerdes o no.
Cinco secciones que valen la pena. De tres a seis líneas de viñetas cada una:
1. Stack: frameworks, DB, autenticación, correo electrónico, con versiones. "Next.js 16, Postgres en Neon, Resend para correo electrónico, Stripe para pagos, Supabase para autenticación."
2. Rutas: dónde viven las cosas. "App en /app, acciones del servidor en /actions, API bajo /app/api/v2, componentes compartidos en /components/ui."
3. Convenciones: reglas obvias para ti, invisibles para Claude. "Dinero en centavos (int), fechas UTC, nombres de archivo kebab-case, IDs como UUID v4."
4. Reglas de seguridad: cosas que nunca deben suceder. "Nunca registres claves de API. Parametriza todo el SQL. Limita la tasa de todos los endpoints públicos."
5. No hagas esto: trampas en las que ya caíste. "No agregues dependencias sin preguntar. No ejecutes migraciones desde local contra producción."
Una plantilla de ejemplo. Sustituye los detalles reales de tu proyecto:
# Plinko Grant Tracker
## Stack
- Next.js 16, Postgres (Neon), Resend, Stripe
- Auth: Supabase Auth with Google OAuth
## Routes
- App in /app, actions in /actions, API under /app/api/v2
## Conventions
- Money in cents (int), dates UTC, filenames kebab-case
- IDs: UUID v4. Boolean columns: is_ or has_ prefix
## Security Rules
- Never log secrets, parameterize SQL
- Rate-limit all POST/PUT/DELETE endpoints (10/min per IP)
- New Supabase tables ship with RLS policies in same commit
## Don't Do This
- Don't add deps without asking
- Don't run migrations from local against prod
- Don't use select(*)Observa la especificidad. "10/min por IP" es accionable. "Usa limitación de tasa" no lo es.
El error más caro: reglas vagas que suenan específicas.
Débil: "Maneja el dinero con cuidado." Claude manejará el dinero de la manera que crea conveniente, lo que puede no coincidir con tu sistema.
Fuerte: "Todos los montos monetarios son centavos enteros. Nunca flotantes. Nunca muestres centavos en bruto; divide por 100 y formatea con un símbolo de moneda." Tipo de almacenamiento, regla de procesamiento, regla de visualización. Sin ambigüedad.
El segundo error: escribir aspiraciones en lugar de restricciones. "Valoramos el código limpio y legible" es una aspiración. "Los archivos de más de 200 líneas se dividen en módulos" es una restricción. Las aspiraciones requieren juicio; las restricciones producen un comportamiento consistente. Llena tu CLAUDE.md con restricciones.
CLAUDE.md es un documento vivo. Tres señales de que necesita actualización:
Pegas el mismo contexto en un prompt por segunda vez. Si lo estás diciendo de nuevo, pertenece a CLAUDE.md.
Claude comete un error que una regla habría prevenido. El error es la regla. Escríbela antes de la próxima sesión.
Le explicas una convención a un colega. Si valió la pena decirlo en voz alta, vale la pena cargarlo automáticamente.
Disciplina de longitud: de tres a seis viñetas por sección; si pasas de ocho, divide la sección. Un CLAUDE.md demasiado largo para ojear deja de funcionar porque las reglas importantes quedan enterradas. Seis líneas correctas son mejores que sesenta líneas de relleno.
Escalando más allá de aproximadamente 300 líneas: divide en archivos temáticos con inclusiones @filename:
# CLAUDE.md (root)
@rules/stack.md
@rules/security.md
@rules/db-migrations.mdCada archivo temático se mantiene enfocado; la raíz se mantiene corta.
Confirma CLAUDE.md en el control de versiones. Las reglas se vuelven revisables en los PRs, y un nuevo compañero de equipo clona el repositorio con Claude ya configurado. Agrega cada regla de "No hagas esto" en el mismo commit que la corrección de errores que la enseñó. Una precaución: generaliza las rutas específicas de la máquina antes de confirmar.
¿Qué pertenece a CLAUDE.md vs un prompt? Radio de impacto. Si una regla previene una clase de error que cuesta una hora o más corregir, va en CLAUDE.md. Las instrucciones específicas de la sesión se quedan en los prompts.
Crea tu primer CLAUDE.md en diez minutos. Dale a Claude este prompt:
"Estoy configurando Claude Code para un proyecto con este stack: [stack]. Convenciones clave que alguien nuevo no sabría: [convenciones]. Reglas de seguridad que nunca deben ser violadas: [reglas]. Cosas que causaron errores antes: [trampas]. Redacta un CLAUDE.md con cinco secciones: Stack, Rutas, Convenciones, Reglas de Seguridad, No hagas esto."
El primer borrador te da el 80 por ciento. Afínalo con lo que Claude omitió; el 20 por ciento restante es lo específico de tu experiencia real con el proyecto.
CLAUDE.md en la raíz del proyecto carga tu stack, rutas, convenciones, reglas de seguridad y trampas en cada sesión. Archivo global para valores predeterminados entre proyectos, archivo de proyecto para anulaciones. Restricciones, no aspiraciones. Seis líneas correctas son mejores que sesenta. Actualízalo cada vez que Claude cometa un error que una regla escrita habría prevenido.