CLAUDE.md: La guía completa para que Claude Code entienda tu proyecto como un senior

¿Por qué necesitas un CLAUDE.md?

Claude Code lee el archivo CLAUDE.md al inicio de cada sesión. Sin él, el agente tiene que explorar y adivinar las convenciones de tu proyecto. Con un buen CLAUDE.md, arranca sabiendo exactamente cómo trabajas, qué herramientas usas y qué no debe tocar.

La diferencia es brutal: sin CLAUDE.md, Claude Code puede generar código que no sigue tus convenciones, usar la librería equivocada o tocar archivos que no debería. Con un buen CLAUDE.md, es como trabajar con alguien que lleva semanas en tu proyecto.

La estructura que funciona

Después de probar muchos formatos, esta es la estructura que mejor funciona:

Sección 1 — Descripción del proyecto

Una o dos frases que expliquen qué hace la aplicación, para quién es y qué problema resuelve. No más.

# Mi Proyecto

SaaS de gestión de facturas para freelancers españoles.
Permite crear, enviar y cobrar facturas con firma digital y cumplimiento AEAT.

Sección 2 — Comandos esenciales

Esta es la sección más importante. Claude Code usará estos comandos constantemente para verificar que sus cambios no rompen nada.

## Comandos
```bash
npm run dev          # Desarrollo en localhost:3000
npm run build        # Build de producción
npm test             # Tests con Vitest (debe pasar siempre)
npm run lint         # ESLint + TypeScript check
npm run db:push      # Sincronizar schema Prisma → base de datos
npm run db:studio    # Abrir Prisma Studio para ver los datos
```

Sección 3 — Stack y arquitectura

Explica el stack con detalle suficiente para que Claude Code no tenga que adivinarlo.

## Stack
- **Framework:** Next.js 15 App Router (React 19, TypeScript strict)
- **Estilos:** Tailwind CSS v4 (CSS-first, sin tailwind.config.ts)
- **Base de datos:** PostgreSQL via Prisma ORM (schema en prisma/schema.prisma)
- **Auth:** Supabase Auth con middleware en middleware.ts
- **Email:** Resend para transaccionales
- **Deploy:** Vercel (auto-deploy en cada push a main)

## Arquitectura
- Server Components por defecto. 'use client' solo cuando hay estado/eventos del usuario
- Los datos se fetchen en page.tsx y se pasan como props a los componentes
- Las mutaciones van en Server Actions (src/app/actions/)
- Las validaciones usan Zod (src/lib/validations/)
- El alias @/ apunta a src/. Nunca uses rutas relativas con ../../

Sección 4 — Convenciones de código

Las convenciones específicas de TU proyecto, no las genéricas.

## Convenciones
- Componentes UI genéricos → src/components/ui/
- Componentes de negocio → src/components/ (con subcarpetas por dominio)
- Hooks → src/lib/hooks/ (prefijo: use)
- Tipos → src/lib/types.ts (interfaces, no types para objetos)
- Utilidades → src/lib/utils.ts

## Naming
- Componentes: PascalCase (InvoiceCard.tsx)
- Hooks: camelCase con prefijo use (useInvoiceForm.ts)
- Server Actions: camelCase con verbo (createInvoice.ts)
- Variables/funciones: camelCase
- Constantes globales: UPPER_SNAKE_CASE

Sección 5 — Lo que NO debes hacer

Esta sección previene los errores más costosos.

## NO hacer
- ❌ No instalar dependencias sin preguntar primero
- ❌ No usar console.log → usar src/lib/logger.ts
- ❌ No modificar prisma/schema.prisma sin ejecutar migration después
- ❌ No crear CSS custom → todo con Tailwind
- ❌ No modificar src/lib/auth.ts (lógica crítica de sesiones)
- ❌ No hacer push directo a main → siempre branch + PR

Sección 6 — Contexto de negocio

Lo que un developer nuevo necesitaría saber para no cometer errores de dominio.

## Dominio
- Los importes siempre se guardan en céntimos (entero) para evitar errores de coma flotante
- Las facturas tienen estados: borrador → enviada → pagada → cancelada
- Los usuarios tienen roles: admin, accountant, viewer
- El NIF del cliente es obligatorio para facturas > 2.500€ (requisito fiscal español)
- Nunca borrar facturas, solo marcarlas como canceladas (auditoría fiscal)

Genera el tuyo con Claude Code

El truco más útil: pídele a Claude Code que genere su propio CLAUDE.md después de explorar tu proyecto:

Explora toda la estructura de este proyecto y genera un archivo CLAUDE.md
completo que incluya: descripción, comandos, stack, arquitectura, convenciones
de código y lo que NO se debe hacer. Sé específico con los detalles reales
del proyecto, no genérico.

Luego léelo tú, corrígelo y añade el contexto de negocio que Claude Code no puede inferir del código.

Mantén el CLAUDE.md actualizado

Si Claude Code comete el mismo error dos veces, añade una regla al CLAUDE.md. Si cambias de librería, actualiza el stack. El CLAUDE.md es un documento vivo que mejora con cada sesión.