Cómo escribir un archivo CLAUDE.md para tu proyecto

CLAUDE.md es un archivo Markdown que Claude Code carga automáticamente como contexto al arrancar una sesión en tu proyecto. Es memoria persistente: lo que pongas ahí, Claude lo sabe sin que se lo repitas. Si aún no tienes Claude Code, instálalo con el instalador nativo (no con npm). Después entra en la raíz de tu repo, lanza claude y ejecuta el comando /init dentro de la sesión. Claude analizará la estructura, el package.json o pyproject, los scripts y los README, y propondrá un CLAUDE.md en la raíz. Trátalo como un borrador: suele acertar con el stack y los comandos, pero se queda corto en lo que solo sabe tu equipo (decisiones de arquitectura, trampas conocidas, qué no tocar). En los siguientes pasos lo vas a reescribir con criterio.

# Instalar Claude Code con el instalador nativo (macOS / Linux / WSL)
curl -fsSL https://claude.ai/install.sh | bash

# Entrar en tu proyecto y abrir Claude Code
cd ~/proyectos/mi-app
claude

# Dentro de la sesión de Claude Code, escribe:
# /init

Un buen CLAUDE.md responde a cuatro preguntas que Claude se hace constantemente: ¿cómo ejecuto cosas?, ¿cómo está organizado esto?, ¿qué estilo sigo? y ¿qué no debo hacer? Usa encabezados Markdown claros y listas cortas; Claude lo parsea mejor que párrafos largos. Pon primero los comandos exactos, copiables, porque es lo que más usa. Después una visión de arquitectura en pocas líneas, las convenciones de código y una sección explícita de prohibiciones. Si tu producto sirve a España y LATAM, este es el sitio para fijar detalles de localización: formato de fechas, monedas, idioma de los textos de UI y de los mensajes de commit. El ejemplo de abajo es para un proyecto Node/TypeScript; adapta los comandos a tu stack. Apunta a 50-150 líneas: es contexto que se carga en cada sesión y consume tokens.

cat > CLAUDE.md <<'EOF'
# Mi App – Guía para Claude

## Comandos
- Instalar: `pnpm install`
- Dev: `pnpm dev` (puerto 3000)
- Tests: `pnpm test` | un archivo: `pnpm test src/lib/precio.test.ts`
- Lint + tipos: `pnpm lint && pnpm typecheck` (ejecutar SIEMPRE antes de dar una tarea por terminada)

## Arquitectura
- Next.js (App Router) en `src/app`, lógica de negocio en `src/lib`
- Acceso a BD solo vía `src/db/queries.ts` (Drizzle). Nunca SQL suelto en componentes
- Pagos: `src/lib/pagos/` soporta EUR, MXN, COP y ARS

## Convenciones
- TypeScript estricto, sin `any`. Usa `unknown` + validación con zod
- Componentes en PascalCase, funciones y archivos de lib en camelCase
- Textos de UI en español neutro, a través de `src/i18n/es.json`
- Fechas al usuario en DD/MM/AAAA con `formatFecha()` de `src/lib/fechas.ts`
- Commits en español, formato Conventional Commits: `feat: añade filtro por país`

## Prohibido
- NO modificar archivos en `src/db/migrations/` ya existentes; crea una migración nueva
- NO añadir dependencias sin preguntar antes
- NO hacer commit de `.env*`
EOF

El error más habitual es escribir consejos genéricos que Claude ya sigue por defecto o que no puede comprobar: 'escribe código limpio', 'sigue buenas prácticas', 'ten cuidado con la seguridad'. No aportan nada y ocupan espacio. Cada regla debería ser concreta (qué archivo, qué función, qué comando) y comprobable (Claude o tú podéis verificar si se cumplió). Repasa tu borrador línea por línea y pregúntate: ¿un dev nuevo sabría exactamente qué hacer con esta frase? Si no, reescríbela. Para reglas críticas puedes usar énfasis con mayúsculas como IMPORTANTE o SIEMPRE; funciona, pero si lo usas en todo pierde efecto. Resérvalo para dos o tres reglas cuyo incumplimiento rompa algo de verdad, como migraciones o secretos. El bloque de abajo muestra el antes y el después para que lo uses como checklist de revisión.

# Busca frases vagas en tu CLAUDE.md para revisarlas
grep -niE 'buenas prácticas|código limpio|ten cuidado|si es posible|intenta' CLAUDE.md

# ANTES (vago)                         -> DESPUÉS (verificable)
# 'Escribe tests'                       -> 'Toda función nueva en src/lib lleva test en el mismo directorio (*.test.ts)'
# 'Cuidado con la seguridad'            -> 'Valida todo input de API con zod en src/app/api/**/route.ts'
# 'Usa el estilo del proyecto'          -> 'Ejecuta pnpm lint --fix; no desactives reglas con eslint-disable'
# 'Formatea bien las fechas'            -> 'Usa formatFecha() de src/lib/fechas.ts, nunca toLocaleDateString directo'

Claude Code no lee un único CLAUDE.md: combina varios niveles. El de usuario, en ~/.claude/CLAUDE.md, aplica a todos tus proyectos: ahí van tus preferencias personales (idioma de las respuestas, tu editor, tu estilo). El de proyecto, en la raíz del repo, se versiona y lo comparte todo el equipo. Además puedes poner CLAUDE.md en subdirectorios (por ejemplo en packages/api de un monorepo); Claude los carga cuando trabaja con archivos de esa carpeta, así que son ideales para reglas específicas de un paquete. Para no duplicar contenido, usa imports: una línea con @ seguido de una ruta incluye otro archivo dentro del contexto. Así puedes referenciar una guía de estilo existente o tus preferencias personales sin copiarlas. Mantén lo personal fuera del CLAUDE.md compartido para no imponer tus manías al equipo.

# 1. Preferencias personales para todos tus proyectos
mkdir -p ~/.claude
cat > ~/.claude/CLAUDE.md <<'EOF'
# Preferencias personales
- Respóndeme siempre en español
- Antes de cambios grandes, propón un plan y espera mi confirmación
EOF

# 2. Reglas específicas de un paquete en un monorepo
cat > packages/api/CLAUDE.md <<'EOF'
# API
- Tests de integración: `pnpm --filter api test:int` (requiere Docker levantado)
- Errores HTTP siempre con `httpError()` de `src/errors.ts`
EOF

# 3. Importar documentación existente desde el CLAUDE.md raíz
cat >> CLAUDE.md <<'EOF'

## Referencias
- Guía de estilo: @docs/estilo.md
- Flujo de despliegue: @docs/deploy.md
EOF

No des el archivo por bueno hasta comprobar que Claude lo interpreta como esperas. Abre una sesión nueva (el contenido de memoria se carga al arrancar) y usa el comando /memory para ver qué archivos de memoria están activos y editarlos desde ahí. Luego haz dos pruebas. Primero, pídele que resuma las reglas que va a seguir: si omite algo importante o lo malinterpreta, la redacción es ambigua. Segundo, encárgale una tarea pequeña que toque tus reglas críticas, por ejemplo añadir un campo a una tabla, y observa si crea una migración nueva en lugar de editar una existente y si ejecuta lint y typecheck al final. Cada fallo es una pista directa de qué reescribir. Este ciclo de probar, observar y corregir es lo que convierte un CLAUDE.md genérico en uno que realmente ahorra tiempo.

# En una sesión NUEVA de Claude Code:
claude

# Comprueba qué archivos de memoria están cargados y edítalos:
# /memory

# Prompt de verificación (cópialo tal cual en la sesión):
# Resume en una lista las reglas de este proyecto que vas a seguir,
# indicando de qué archivo CLAUDE.md sale cada una.

# Prompt de prueba de comportamiento:
# Añade un campo 'pais' (ISO 3166, ej. ES, MX, AR) a la tabla clientes
# y verifica el resultado.

El CLAUDE.md de proyecto es código: va al repositorio, pasa por pull request y se revisa como cualquier otro cambio. Así todo el equipo, esté en Madrid, Ciudad de México o Bogotá, trabaja con el mismo contexto y Claude se comporta igual para todos. Acordad una regla sencilla: cuando alguien corrige a Claude por algo que se repetirá, actualiza CLAUDE.md en el mismo PR. Revisa el archivo cada pocas semanas para borrar reglas obsoletas (comandos que cambiaron, carpetas que ya no existen); una regla desactualizada es peor que ninguna porque Claude la sigue con total confianza. Asegúrate también de que los archivos personales no acaban en el repo por accidente.

# Versionar el CLAUDE.md del proyecto y el de los paquetes
git add CLAUDE.md packages/*/CLAUDE.md docs/estilo.md
git commit -m "docs: añade CLAUDE.md con comandos, convenciones y reglas del proyecto"

# Detectar referencias a rutas que ya no existen en CLAUDE.md
grep -oE '`(src|packages|docs)/[^` ]+`' CLAUDE.md | tr -d '`' | while read -r p; do
  [ -e "$p" ] || echo "Ruta obsoleta en CLAUDE.md: $p"
done