CLAUDE.md: la guía definitiva

CLAUDE.md se carga automáticamente al inicio de cada sesión de Claude Code en ese directorio. Es la memoria persistente del proyecto — todo lo que Claude necesita saber para trabajar sin que le expliques nada.

Sin CLAUDE.md, cada sesión empieza de cero. Con uno bien escrito, Claude sabe tu stack, tus convenciones, tus decisiones de arquitectura y hasta tus preferencias personales.

El efecto compuesto: después de 3-4 meses de mantenerlo actualizado, Claude trabaja como un desarrollador senior que lleva meses en tu proyecto.

Un CLAUDE.md efectivo tiene estas secciones:

# Nombre del Proyecto

Descripción breve de qué es el proyecto y para quién.

## Stack
- Framework, lenguaje, base de datos
- Servicios externos (APIs, hosting)

## Comandos
- Dev, build, test, deploy
- Migraciones de base de datos

## Estructura del proyecto
- Dónde viven los componentes
- Dónde van las API routes
- Patrones de carpetas

## Convenciones
- Naming, formatting
- Patrones que seguir
- Anti-patrones que evitar

## Decisiones de arquitectura
- Por qué elegiste X sobre Y
- Trade-offs aceptados

## Contexto de negocio
- Quién es el usuario
- Qué problema resuelve

Este es un ejemplo de CLAUDE.md para una aplicación SaaS genérica:

# TaskFlow

Aplicación SaaS de gestión de tareas y proyectos
para equipos pequeños.

## Stack
- Next.js con App Router
- Prisma + PostgreSQL
- Tailwind CSS
- Vercel para deploy

## Deployment
- Deploy automático desde la rama main
- Dos entornos: staging y producción
- Nunca deployar cambios de schema sin probar en staging primero

## Design Principles
1. Silence is confidence — show results, not process
2. Density with clarity — information-rich without clutter
3. Progressive disclosure — essentials first, details on demand
4. Dark theme only — no light mode

Lo importante: cada línea responde una pregunta que Claude haría si no tuviera la respuesta.

Demasiado genérico:

# Mi Proyecto
Un proyecto web con React.

Esto no ayuda a Claude a tomar decisiones.

Demasiado largo: Un CLAUDE.md de 2000 líneas consume contexto innecesariamente. Los detalles específicos deben ir en archivos separados referenciados desde CLAUDE.md.

Desactualizado: Si el CLAUDE.md dice "usa PostgreSQL" pero migraste a MongoDB hace un mes, Claude escribirá código para PostgreSQL.

Regla práctica: actualiza CLAUDE.md cada vez que tomes una decisión de arquitectura, cambies un patrón, o descubras algo que Claude debería saber siempre.

Claude Code carga CLAUDE.md a tres niveles:

1. Global (~/.claude/CLAUDE.md) — preferencias que aplican a todos tus proyectos
2. Proyecto (./CLAUDE.md en la raíz) — stack, convenciones, arquitectura
3. Directorio (./src/components/CLAUDE.md) — reglas específicas de un módulo

Los tres se combinan. Usa el global para tus preferencias personales, el de proyecto para contexto técnico, y los de directorio solo cuando un módulo tiene reglas especiales.

Para proyectos maduros, añade:

Prohibited patterns:

## Prohibido
- No usar `any` en TypeScript — resolver el tipo real
- No crear componentes client cuando server component funciona
- No hardcodear URLs — usar variables de entorno

Testing strategy:

## Tests
- Unit tests para lógica de negocio pura
- Integration tests para API routes
- No mockear Prisma — usar la DB de test

Error handling patterns:

## Errores
- API routes devuelven { error: string, code: string }
- Errores de validación: 400
- No autorizado: 401
- No encontrado: 404
- Errores internos: 500 con log a console.error

Un buen CLAUDE.md es la base de todo lo demás:

• Tu primer proyecto con Claude Code — si aún no has instalado Claude Code
• Instalar oh-my-claudecode — OMC usa CLAUDE.md como contexto base para todos sus agentes
• Patrones de orquestación — cómo los agentes leen CLAUDE.md para tomar decisiones informadas