CLAUDE.md: guía completa para configurar Claude Code

Qué es CLAUDE.md y por qué importa

CLAUDE.md es el archivo que le dice a Claude Code cómo trabajar en tu proyecto. Piensa en él como el onboarding que le darías a un nuevo desarrollador: qué stack usas, cómo se estructura el código, qué convenciones sigues y qué cosas no se deben hacer.

Sin CLAUDE.md, Claude Code funciona, pero de forma genérica. Con un buen CLAUDE.md, Claude Code se comporta como un miembro más del equipo que ya conoce el proyecto.

Es, probablemente, la funcionalidad más infravalorada de Claude Code. La diferencia entre un CLAUDE.md bien escrito y ninguno es la diferencia entre un junior que pregunta todo y un senior que ya sabe cómo trabajas.

La jerarquía: global, proyecto, usuario

CLAUDE.md puede vivir en tres sitios, cada uno con diferente alcance y prioridad:

1. Global: ~/.claude/CLAUDE.md

Aplica a todos tus proyectos. Aquí pones preferencias personales: idioma, estilo de respuesta, reglas universales. No se sube a git. Es privado de cada developer.

# ~/.claude/CLAUDE.md - Config global

## Reglas de estilo
- Español por defecto. Inglés solo para código.
- Respuestas cortas, sin preámbulo ni resumen.
- Challengear ideas, no asentir por asentir.

## Preferencias personales
- Prefiero TypeScript sobre JavaScript
- Prefiero Tailwind sobre CSS modules
- Siempre async/await, nunca .then() chains

2. Proyecto: CLAUDE.md en la raíz (o .claude/CLAUDE.md)

Aplica solo a este proyecto. Aquí pones el stack, las convenciones de código, las restricciones del proyecto. Se sube a git y lo comparte todo el equipo.

3. Usuario de proyecto: .claude/users/[username]/CLAUDE.md

Configuración personal dentro de un proyecto específico. Útil cuando quieres override personales que no aplican al equipo. Por ejemplo, un developer que trabaja solo en el frontend puede tener reglas adicionales para su contexto.

Esta jerarquía permite que cada nivel tenga su responsabilidad:

• Global: quién eres como developer (estilo, preferencias, idioma).
• Proyecto: cómo funciona el proyecto (stack, convenciones, restricciones).
• Usuario: tu relación particular con este proyecto (qué módulo mantienes, qué permisos extra necesitas).

Estructura recomendada

Un CLAUDE.md efectivo tiene estas secciones:

# CLAUDE.md — [Nombre del proyecto]

## Identidad
- Proyecto: [nombre]
- Stack: [tecnologías]
- URL: [producción]
- Repo: [GitHub]

## Convenciones de código
- Lenguaje: [Python 3.11+ / TypeScript 5.x / etc.]
- Estilo: [PEP8 / Prettier / etc.]
- Naming: [snake_case para Python, camelCase para TS]
- Tests: [pytest / vitest / etc.]
- Estructura: [breve descripción de carpetas]

## Reglas de estilo
- Idioma de respuesta: [español/inglés]
- Formato: [corto y directo / detallado]
- Commit messages: [conventional commits]

## Restricciones (NUNCA hacer)
- No modificar archivos en /config/production/
- No hacer push a main directamente
- No instalar dependencias sin consultar

## Paths clave
- Tests: tests/
- Docs: docs/
- Config: .env.example (nunca .env)
- CI: .github/workflows/

Cada sección debe ser concisa. Usa bullet points. Evita párrafos largos. Claude Code no necesita narrativa, necesita datos.

Template completo

Este template cubre los casos de uso más comunes. Cópialo y adapta las secciones a tu proyecto:

# CLAUDE.md — [Proyecto]

## 1. Identidad
Proyecto: [nombre y una frase de qué hace]
Stack: [lista de tecnologías principales]
URL prod: [URL]
Repo: [URL del repo]
Entorno: [dev/staging/prod URLs si aplica]

## 2. Arquitectura
[Estructura de carpetas principal]
src/
  api/        # Routes/controllers
  services/   # Lógica de negocio
  models/     # Modelos de datos
  utils/      # Utilidades compartidas
tests/        # Tests (mirror de src/)

## 3. Convenciones de código
- Lenguaje: [version]
- Formatter: [herramienta + config]
- Linter: [herramienta + config]
- Naming: [convenciones por tipo: archivos, funciones, clases, variables]
- Imports: [orden, agrupación]
- Tests: [framework, convenciones de nombrado, coverage mínimo]
- Commits: [formato, ejemplos]

## 4. Reglas de negocio
- [Regla 1: ej. "Todo endpoint necesita autenticación excepto /health"]
- [Regla 2: ej. "Los precios se almacenan en céntimos, nunca en decimales"]
- [Regla 3: ej. "Multi-tenant via RLS, NUNCA filtrar en application layer"]

## 5. Restricciones (NUNCA)
- NUNCA: [acción prohibida 1]
- NUNCA: [acción prohibida 2]
- NUNCA: [acción prohibida 3]

## 6. Patrones preferidos
- [Patrón: ej. "Dependency injection para DB y auth"]
- [Patrón: ej. "Error handling centralizado en middleware"]
- [Patrón: ej. "Pydantic schemas separados: Create, Update, Response"]

## 7. Paths clave
- Config: [path]
- Tests: [path]
- Migrations: [path]
- CI/CD: [path]
- Docs: [path]

Ejemplo real: Next.js + FastAPI

Un CLAUDE.md real para un proyecto fullstack:

# CLAUDE.md — MiApp

## Identidad
Proyecto: MiApp (SaaS de gestión de proyectos)
Stack: Next.js 14 + FastAPI + Supabase + Tailwind
URL prod: https://miapp.com
Repo: github.com/empresa/miapp

## Backend (FastAPI)
- Python 3.11+, async everywhere
- Pydantic v2 para validación
- Alembic para migraciones
- Tests: pytest + httpx (mínimo 80% coverage)
- Naming: snake_case, prefijo test_ para tests

## Frontend (Next.js)
- App Router, React Server Components por defecto
- Tailwind CSS (no CSS modules)
- TypeScript strict
- Tests: vitest + testing-library

## Base de datos
- Supabase PostgreSQL con RLS habilitado
- Cada tabla nueva necesita policy de RLS
- Migraciones en backend/migrations/

## Reglas
- Español por defecto en respuestas
- Conventional commits (feat:, fix:, docs:)
- No tocar .env — usar .env.example como referencia
- No hacer push a main — siempre PR con review

## Anti-patterns
- NUNCA: inline styles en frontend
- NUNCA: queries raw sin parametrizar
- NUNCA: endpoints sin autenticación
- NUNCA: console.log en producción

Patrones avanzados

Más allá de lo básico, hay patrones avanzados que maximizan la efectividad del CLAUDE.md:

Feature flags en CLAUDE.md:

Documenta tus feature flags para que Claude Code sepa qué código está activo y cuál no.

## Feature flags (GrowthBook)
- COORDINATOR_MODE: activo en prod. Multi-agent swarm.
- AUTO_PERMISSIONS: solo staging. ML classifier para permisos.
- VOICE_INPUT: roadmap Q3. No implementar aún.

Cuando trabajes con código detrás de un flag, verifica que:
1. El código funciona con el flag ON y OFF
2. No hay side effects si el flag se desactiva en caliente
3. El flag tiene TTL: si lleva 90 días sin cambiar, propón eliminarlo

Anti-patterns documentados:

No solo digas qué NO hacer. Explica por qué y qué hacer en su lugar.

## Anti-patterns
- NUNCA: fetch en useEffect para datos iniciales
  POR QUÉ: causa waterfall, doble render, flash de loading
  EN VEZ: usar Server Components con async/await directo

- NUNCA: un try/catch genérico que traga errores
  POR QUÉ: oculta bugs, hace debugging imposible
  EN VEZ: catch específico, log + re-throw o error boundary

- NUNCA: string literals para estados (status = "active")
  POR QUÉ: typos silenciosos, no hay autocompletado
  EN VEZ: enum o union type (Status = "active" | "inactive")

Convenciones de naming avanzadas:

## Naming conventions
- Archivos: kebab-case (user-profile.tsx, not UserProfile.tsx)
- Componentes: PascalCase (UserProfile, not userProfile)
- Hooks: camelCase con prefix use (useUserProfile)
- Utils: camelCase (formatDate, parseCSV)
- Constants: UPPER_SNAKE_CASE (MAX_RETRIES, API_BASE_URL)
- Types/Interfaces: PascalCase con suffix (UserResponse, CreateUserInput)
- Test files: [filename].test.ts (user-profile.test.ts)
- API routes: kebab-case plural (/api/v1/user-profiles)

Contexto de decisiones (mini-ADRs):

## Decisiones arquitectónicas
- DB: PostgreSQL (no MongoDB) porque necesitamos transacciones ACID y RLS
- Auth: Supabase Auth (no NextAuth) porque ya usamos Supabase para DB
- State: Zustand (no Redux) porque la app es mediana y Redux es overkill
- CSS: Tailwind (no styled-components) porque SSR sin runtime CSS-in-JS

CLAUDE.md para equipos

Cuándo trabajas en equipo, el CLAUDE.md se convierte en documentación viva del proyecto. Algunos patrones específicos para equipos:

Sección de equipo con roles:

## Equipo
- Lead backend: María — decisiones de arquitectura API y DB
- Lead frontend: Pedro — decisiones de UX y componentes
- DevOps: Ana — decisiones de infra, CI/CD, deploy
- Si tienes dudas sobre dominio de negocio, pregunta (no asumas)
- Si tienes dudas sobre arquitectura, consulta ADRs en docs/adrs/

Proceso de actualización:

## Mantenimiento de este archivo
- Cualquier PR que cambia convenciones DEBE actualizar este CLAUDE.md
- Review obligatorio para cambios en secciones de Seguridad y Restricciones
- Retro mensual: revisar si las reglas siguen siendo relevantes
- Si algo no está documentado aquí y debería estarlo, añádelo

Onboarding automático:

Un CLAUDE.md bien escrito es la mejor documentación de onboarding que existe. Un developer nuevo clona el repo, abre Claude Code, y tiene todo el contexto para empezar a contribuir. No necesita leer un wiki de 50 páginas ni hacer una sesión de 2 horas con un senior.

Para una guía completa de configuración en equipo, lee nuestro artículo de Claude Code en equipo.

Errores comunes

• CLAUDE.md demasiado largo: Si supera las 500 líneas, Claude Code consume contexto en leerlo. Sé conciso. Usa bullet points, no párrafos. Si necesitas más, divide por subdirectorio.
• Instrucciones contradictorias: Si el global dice "responde en inglés" y el de proyecto dice "responde en español", genera confusión. Define prioridades claras o elimina la contradicción.
• Información obsoleta: Un CLAUDE.md con paths que ya no existen o reglas de un stack anterior es peor que no tener CLAUDE.md. Mantenlo actualizado con cada cambio relevante.
• Secretos en CLAUDE.md: Nunca pongas API keys, passwords o tokens. CLAUDE.md se sube a git. Usa .env.example para documentar qué variables se necesitan.
• Solo reglas negativas: Un CLAUDE.md lleno de "nunca hagas X" sin decir qué SÍ hacer es frustrante para el modelo. Equilibra restricciones con guía positiva.
• Copiar-pegar sin adaptar: Un template genérico sin adaptar a tu proyecto es ruido. Cada regla debe ser relevante para TU código, no para un proyecto hipotético.
• No versionarlo: Si el CLAUDE.md no está en git, cada developer tiene una versión diferente (o ninguna). Commitéalo siempre.

Guía de migración

Si ya usas Claude Code sin CLAUDE.md, migrar es sencillo. Si vienes de otro asistente de código (Cursor, Copilot), aquí tienes el proceso:

Desde cero (nunca has usado CLAUDE.md):

1. Copia el template de la sección anterior.
2. Rellena las secciones de Identidad y Convenciones (5 minutos).
3. Añade 3-5 restricciones que conozcas de tu proyecto.
4. Guárdalo en la raíz del proyecto.
5. Usa Claude Code normalmente durante 3 días.
6. Cada vez que Claude Code haga algo que no te gusta, añade una regla al CLAUDE.md.
7. En una semana tendrás un CLAUDE.md que cubre el 90% de los casos.

Desde Cursor (.cursorrules):

Si tienes un archivo .cursorrules, la migración es casi directa. El formato es similar (Markdown con reglas). Diferencias clave:

• CLAUDE.md soporta la jerarquía global/proyecto/usuario (Cursor no).
• Puedes referenciar paths relativos y Claude Code los resolverá.
• Las restricciones con "NUNCA" funcionan especialmente bien en CLAUDE.md.
• Copia el contenido de .cursorrules a CLAUDE.md y ajusta el formato.

Desde GitHub Copilot (sin archivo de reglas):

Copilot no tiene un equivalente a CLAUDE.md. Empieza desde el template y enfócate en las convenciones que Copilot no podía seguir: estructura de archivos, patrones de arquitectura, reglas de negocio.

Evolución del CLAUDE.md:

Un CLAUDE.md maduro pasa por estas fases:

1. Semana 1: Identidad + convenciones básicas (20-30 líneas).
2. Semana 2-3: Restricciones y anti-patterns (50-80 líneas).
3. Mes 1-2: Patrones avanzados, decisiones arquitectónicas (100-200 líneas).
4. Mes 3+: Consolidación. Elimina reglas que ya no aplican. Refina las que quedan (150-300 líneas estables).

Preguntas frecuentes

¿CLAUDE.md afecta el rendimiento de Claude Code?

Un CLAUDE.md de menos de 300 líneas tiene impacto negligible. Se carga una vez al inicio de la sesión y ocupa una fracción mínima de la ventana de contexto. El beneficio supera con creces el coste.

¿Puedo incluir código ejecutable en CLAUDE.md?

No se ejecuta automáticamente, pero puedes incluir snippets de ejemplo que Claude Code usará como referencia. "Los endpoints deben seguir este patrón: [snippet]" es perfectamente válido.

¿Con qué frecuencia debo actualizar el CLAUDE.md?

Cada vez que cambies una convención, añadas una tecnología, o descubras un patrón que Claude Code debería seguir. En la práctica, 2-4 cambios por mes es normal para un proyecto activo.

¿Funciona CLAUDE.md con Claude Code en VS Code?

Sí. Claude Code lee el CLAUDE.md independientemente de si lo ejecutas desde terminal, VS Code, o cualquier otro entorno. El archivo vive en el proyecto, no en el editor.

¿Puedo tener reglas condicionales?

No hay sintaxis condicional, pero puedes documentar contexto: "Si estás trabajando en /backend, usa Python async. Si estás en /frontend, usa TypeScript". Claude Code infiere el contexto del directorio actual.

Siguiente paso

Crea tu CLAUDE.md ahora. Empieza con la plantilla de la sección anterior, adáptala a tu proyecto y guárdala en la raíz. Notarás la diferencia en la primera sesión de Claude Code.

Después, explora la memoria de Claude Code para que tu configuración persista entre sesiones, y los skills para crear comandos reutilizables.