¿Qué es el archivo CLAUDE.md? Guía + Ejemplos (2026)

Armaste tu app con Claude Code. Quedó perfecta. Cerrás la terminal. Al otro día volvés, abrís Claude... y olvidó todo: tu arquitectura, tus convenciones, las decisiones que tomaron juntos. Empezás de cero.

El archivo CLAUDE.md es la solución a eso. Suena aburrido, pero es probablemente la parte más importante de usar Claude Code bien.

¿Qué es el archivo CLAUDE.md?

CLAUDE.md es un archivo de texto que le da a Claude Code memoria persistente sobre tu proyecto: arquitectura, convenciones de código y decisiones importantes. Claude lo lee automáticamente al inicio de cada sesión, así no olvida cómo funciona tu proyecto entre un chat y otro. Sin él, Claude arranca en blanco cada vez.

¿Para qué sirve?

Sirve para que Claude respete, sin que se lo repitas:

• Decisiones arquitecturales —por qué elegiste tRPC sobre REST, etc.
• Convenciones de código —naming, validación, manejo de errores
• Patrones que debe seguir (y los que debe evitar)

El resultado: menos regresión, más consistencia, y documentación viva que sirve también para onboarding.

¿Cómo crear un CLAUDE.md?

Dentro de tu proyecto, escribí:

/init

Claude revisa todo el proyecto, analiza la estructura y genera un CLAUDE.md inicial. Eso es tu punto de partida —después lo afinás vos.

Agregá reglas en tiempo real con #

Mientras chateás, podés agregar una regla directo al archivo con el comando #:

# Usar siempre error boundaries en componentes que hacen llamadas a la API

Acostumbrate a hacerlo cuando notás un patrón que querés que Claude respete (o deje de romper).

Cómo se ve un CLAUDE.md

Un archivo bien armado se ve así:

# CLAUDE.md
 
Guía para Claude Code al trabajar en este repositorio.
 
## Architecture
- **Frontend**: React 18 + Vite, SPA
- **Backend**: Express.js REST API con SQLite
- **Comunicación**: el front llama al back en /api/
 
## Key Patterns
- Usar Zod para validación de inputs en todos los endpoints
- Error boundaries en componentes con llamadas a la API
- Respetar las convenciones de naming existentes
 
## Lo Que NO Hacer
- NUNCA usar `any` en TypeScript
- NUNCA commitear secrets

La jerarquía: podés tener varios CLAUDE.md

Claude Code soporta múltiples archivos en distintos niveles, y los combina:

~/.claude/CLAUDE.md          # Preferencias globales tuyas
~/dev/CLAUDE.md              # Standards de equipo/organización
~/dev/mi-proyecto/CLAUDE.md  # Conocimiento del proyecto
~/dev/mi-proyecto/backend/CLAUDE.md  # Patrones del backend

Regla simple: el más específico gana. Claude lee todos los que apliquen y prioriza la guía más cercana a lo que estás tocando.

Los 3 errores que me costaron horas

1. CLAUDE.md desactualizado. Agregué features y no actualicé el archivo. Claude "olvidó" decisiones y recreó código viejo. Actualizarlo es parte del workflow, no opcional.
2. Demasiado largo. Cuando pasó las ~150 líneas, Claude empezó a ignorar partes. Mantené el archivo core corto y movilizá los detalles a @docs/.
3. Sin sección "Lo Que NO Hacer". Documentar solo lo que querés no alcanza —Claude necesita saber qué evitar.

Checklist de un CLAUDE.md saludable

• Tech stack documentado
• Comandos principales (dev, test, build)
• Al menos 3 reglas de "NO hacer"
• Al menos 1 decisión con fecha
• Menos de 150 líneas (el archivo core)
• Commiteado en git —es código, no documentación opcional

Tu próximo paso (no cierres la pestaña):

• Guía completa de Claude Code — el sistema entero, de cero a producción
• Plan Mode en Claude Code — planificá antes de ejecutar
• Curso gratis: Claude Code Mastery — incluye el módulo de memoria y CLAUDE.md