Mejores Prácticas de CLAUDE.md: Configura Claude Code para Cualquier Proyecto
CLAUDE.md es la configuración de mayor impacto para Claude Code. Uno bien escrito transforma la asistencia genérica de IA en experiencia específica del proyecto.
CLAUDE.md es un archivo markdown en la raíz de tu proyecto. Claude Code lo lee al inicio de cada sesión antes de que escribas nada. Un buen CLAUDE.md transforma una IA genérica en una herramienta que entiende las convenciones, el stack tecnológico y las líneas rojas de tu proyecto.
Qué deberías incluir en CLAUDE.md
Enfócate en la información que un desarrollador inteligente que se une a tu equipo necesitaría el primer día. Mantenlo práctico: stack tecnológico, comandos, convenciones y cosas que evitar.
Plantilla mínima de CLAUDE.md
# Contexto del Proyecto
App Next.js 14 con TypeScript, Tailwind CSS y Prisma.
Base de datos: PostgreSQL. Auth: NextAuth.js.
## Comandos
- `npm run dev` — iniciar servidor de desarrollo (puerto 3000)
- `npm run test` — ejecutar pruebas Jest
- `npm run lint` — ejecutar ESLint
- `npm run db:migrate` — ejecutar migraciones de Prisma
## Arquitectura
- Server components por defecto, client components en /components/client/
- Rutas API en /app/api/ con validación Zod
- Consultas a base de datos en /lib/db/ (nunca en componentes)
## Convenciones
- TypeScript modo estricto, nunca usar `any`
- Tailwind para estilos, sin CSS modules
- Commits convencionales: feat:, fix:, chore:
## NO hacer
- Modificar archivos en /legacy/ o /vendor/
- Cambiar configuración de auth sin aprobación explícita
- Añadir nuevas dependencias sin preguntar primeroCuáles son los errores más comunes en CLAUDE.md
| Error | Por qué perjudica | Solución |
|---|---|---|
| Demasiado largo (500+ líneas) | Desperdicia la ventana de contexto en cada sesión | Mantener bajo 200 líneas, enlazar a documentación para detalles |
| Demasiado vago ("escribe código limpio") | No da guía accionable | Sé específico: "Usa server components por defecto" |
| Faltan comandos | Claude adivina cómo ejecutar/probar/compilar | Lista cada script npm relevante |
| Sin restricciones | Claude podría modificar archivos sensibles | Añade una sección clara de "NO hacer" |
| Duplicado del README | README es para humanos, CLAUDE.md es para IA | Enfócate en convenciones y reglas, no en descripción del proyecto |
Cómo estructurar CLAUDE.md para proyectos grandes
Para grandes bases de código, usa la sintaxis @import para dividir la configuración entre directorios. Claude Code sigue los imports y construye una imagen completa.
# CLAUDE.md raíz
## Convenciones globales
- TypeScript estricto, sin `any`
- Todas las rutas API validan entrada con Zod
@import packages/api/CLAUDE.md
@import packages/web/CLAUDE.md
@import packages/shared/CLAUDE.mdCada sub-CLAUDE.md contiene reglas específicas de ese paquete. Esto mantiene el archivo raíz corto mientras da a Claude Code contexto profundo sobre cada área de la base de código.
Cómo generar CLAUDE.md automáticamente
Claude Code puede generar un CLAUDE.md inicial analizando tu proyecto:
# Auto-generar CLAUDE.md
claude /init
# Esto crea un CLAUDE.md basado en:
# - Scripts del package.json
# - Estructura del proyecto
# - Archivos de configuración existentes
# - Patrones del historial gitEmpieza con /init, luego refina manualmente. El archivo auto-generado es un buen punto de partida, pero no conocerá las convenciones no escritas de tu equipo. Añádelas tú mismo.
Jerarquía de memoria de CLAUDE.md
Claude Code lee archivos CLAUDE.md de múltiples ubicaciones, en orden de prioridad:
- +CLAUDE.md en la raíz del proyecto (todos en el equipo lo comparten)
- +Archivos CLAUDE.md de subdirectorios (vía @import)
- +~/.claude/CLAUDE.md (tus preferencias personales globales)
- +Memoria Automática (MEMORY.md, gestionado por el comando /memory)
La configuración a nivel de proyecto sobrescribe la personal. Esto significa que las convenciones del equipo siempre ganan sobre las preferencias individuales.