CLAUDE.md — Memoria del Proyecto
El Problema que Resuelve CLAUDE.md
Cada vez que inicias una nueva sesión de Claude Code, Claude comienza desde cero. Puede leer tus archivos e inferir mucho sobre tu proyecto, pero no sabe inherentemente las convenciones de tu equipo, tu framework de testing preferido, los comandos para compilar y desplegar, o las decisiones arquitectónicas que has tomado. Sin este contexto, Claude podría generar código usando CommonJS cuando tú usas ES modules, sugerir Jest cuando usas Vitest, o formatear código en un estilo que choca con tu linter.
CLAUDE.md es la solución. Es un archivo de markdown plano que Claude carga automáticamente al inicio de cada sesión, dándole memoria persistente del proyecto. Piensa en él como un documento de incorporación para tu programador de pares con IA -- el mismo tipo de notas que le darías a un nuevo miembro del equipo en su primer día.
La Jerarquía de Memoria
Claude Code lee archivos CLAUDE.md desde múltiples ubicaciones, y cada nivel de la jerarquía agrega contexto. Los archivos cargados después pueden construir sobre o sobreescribir los anteriores:
Nivel global -- ~/.claude/CLAUDE.md se aplica a cada proyecto en tu máquina. Pon tus preferencias personales aquí: tu idioma preferido, estilo de código, convenciones del editor y cualquier regla universal.
Nivel de proyecto -- ./CLAUDE.md en la raíz de tu proyecto. Este es el archivo más importante. Contiene contexto específico del proyecto: stack tecnológico, comandos de compilación, instrucciones de testing, vista general de la estructura de archivos y convenciones del equipo.
Nivel de directorio -- ./src/api/CLAUDE.md, ./src/components/CLAUDE.md, y así sucesivamente. Estos proporcionan contexto con alcance específico para áreas determinadas de tu base de código. Cuando Claude está trabajando en un directorio particular, recoge el CLAUDE.md con alcance relevante automáticamente.
Los tres niveles se fusionan, dándole a Claude una comprensión en capas de tus preferencias globales, reglas del proyecto y convenciones específicas de directorio.
Qué Poner en Tu CLAUDE.md
Los archivos CLAUDE.md más efectivos cubren cuatro áreas: vista general del proyecto, comandos de desarrollo, convenciones de código y patrones comunes. Aquí hay un ejemplo completo para un proyecto Next.js:
# Proyecto: SkyDashboard
## Vista General
App Next.js 14 con App Router, TypeScript modo estricto, Tailwind CSS.
Rutas API del backend en src/app/api/. PostgreSQL via Prisma ORM.
## Comandos
- `npm run dev` — iniciar servidor de desarrollo en puerto 3000
- `npm run build` — compilacion para produccion
- `npm test` — ejecutar suite de tests con Vitest
- `npm run test:e2e` — ejecutar tests end-to-end con Playwright
- `npm run lint` — verificacion ESLint + Prettier
- `npx prisma migrate dev` — ejecutar migraciones de base de datos
## Convenciones de Codigo
- Usar ES modules (import/export), nunca CommonJS require
- Todos los componentes usan estilo funcional con interfaces TypeScript para props
- Rutas API retornan NextResponse.json() con codigos de estado apropiados
- Manejo de errores: usar clase personalizada AppError de src/lib/errors.ts
- Nombres de archivos: kebab-case para archivos, PascalCase para componentes
- Tests van en directorios __tests__/ junto al codigo que prueban
## Arquitectura
- src/app/ — paginas y rutas API de Next.js (App Router)
- src/components/ — componentes UI reutilizables
- src/lib/ — utilidades compartidas, cliente de base de datos, helpers de auth
- src/types/ — definiciones de tipos TypeScript
- prisma/ — esquema y migraciones
## Patrones Importantes
- Todas las consultas a base de datos van a traves de src/lib/db.ts, nunca importar PrismaClient directamente
- Autenticacion usa NextAuth.js con estrategia JWT
- Usar esquemas Zod para toda validacion de entrada de API
- Componentes de servidor por defecto, "use client" solo cuando sea necesario
Y aquí hay un ejemplo para un proyecto de API en Python:
# Proyecto: DataPipeline API
## Vista General
Servicio FastAPI con SQLAlchemy ORM, migraciones Alembic, cache Redis.
Python 3.12, gestionado con Poetry.
## Comandos
- `poetry run uvicorn app.main:app --reload` — servidor de desarrollo
- `poetry run pytest` — ejecutar suite de tests
- `poetry run pytest -x -k "test_name"` — ejecutar test individual
- `poetry run alembic upgrade head` — ejecutar migraciones
- `poetry run ruff check .` — lint
- `poetry run mypy .` — verificacion de tipos
## Convenciones
- Type hints en TODAS las firmas de funciones, sin excepciones
- Usar modelos Pydantic v2 para esquemas de request/response
- Async en todas partes: todos los handlers de rutas y operaciones de BD son async
- Tests usan pytest-asyncio con fixtures de fabrica
- Variables de entorno cargadas via pydantic-settings, nunca os.getenv directamente
Qué NO Poner en CLAUDE.md
Mantiene esto fuera de tu CLAUDE.md:
Secretos y credenciales. Nunca pongas claves API, contraseñas o tokens en CLAUDE.md. Es un archivo regular que se registra en control de versiones.
Listados exhaustivos de archivos. No listes cada archivo de tu proyecto. Claude puede leer el árbol de archivos por sí mismo. Una vista general de la arquitectura de alto nivel es mucho más útil que un volcado de directorio de 500 líneas.
Contexto específico de sesión. No pongas cosas como "actualmente estamos refactorizando el módulo de auth." Eso pertenece a tu conversación con Claude, no en un archivo persistente.
Documentación demasiado verbosa. Apunta a menos de 200 líneas. Claude tiene una ventana de contexto finita, y cada línea de CLAUDE.md consume tokens. Sé conciso y prioriza la información que Claude necesita con más frecuencia.
Memoria con Alcance de Directorio
Para proyectos más grandes, los archivos CLAUDE.md a nivel de directorio te permiten dar a Claude contexto especializado para diferentes partes de tu base de código. Esto es especialmente poderoso en monorepos.
# Archivo: src/api/CLAUDE.md
## Reglas del Modulo API
- Cada handler de ruta debe validar la entrada con Zod antes de procesar
- Siempre retornar tipo estandarizado ApiResponse<T>
- Usar middleware para verificaciones de auth, nunca verificar auth dentro de handlers
- El rate limiting se aplica a nivel de router
- Todas las operaciones de BD deben usar transacciones para operaciones de escritura
# Archivo: src/components/CLAUDE.md
## Guias de Componentes
- Cada componente debe tener un archivo .test.tsx correspondiente
- Usar composicion sobre prop drilling — preferir React context para estado compartido
- Todos los componentes deben ser accesibles (etiquetas ARIA, navegacion por teclado)
- Las stories de Storybook son requeridas para cualquier componente en el design system
Cuando Claude está editando un archivo en src/api/, automáticamente recoge las reglas específicas de la API. Cuando se mueve a src/components/, carga las guías de componentes en su lugar. Este enfoque dirigido previene la sobrecarga de reglas mientras mantiene a Claude alineado con tus convenciones en cada parte de la base de código.
Auto-Memoria y el Comando /memory
Claude Code también puede aprender tus preferencias con el tiempo a través de la auto-memoria. Cuando corriges a Claude durante una sesión -- "no, usamos tabs no espacios" o "siempre agrega manejo de errores a funciones async" -- Claude puede ofrecerte guardar esa preferencia en tu CLAUDE.md.
Puedes controlar este comportamiento con el comando /memory:
# Activar o desactivar auto-memoria
/memory
# Agregar manualmente una entrada de memoria
/memory add "Siempre usar vitest en lugar de jest para tests"
Esto crea un ciclo de retroalimentación donde Claude se vuelve más inteligente sobre tu proyecto cuanto más lo usas. Con el tiempo, tu CLAUDE.md crece orgánicamente basado en correcciones y preferencias reales.
El Comando /init
Si estás comenzando desde cero con Claude Code en un proyecto existente, el comando /init proporciona una forma interactiva de generar tu primer CLAUDE.md:
claude
> /init
Claude analizará tu proyecto -- leyendo package.json, archivos de configuración, estructura de directorios y documentación existente -- y luego generará un CLAUDE.md adaptado a lo que encuentre. Puedes revisar y editar el resultado antes de guardar.
Esto es más rápido que escribir un CLAUDE.md desde cero y asegura que no te pierdas elementos obvios como comandos de compilación y scripts de test.
Mejores Prácticas
Mantén tu CLAUDE.md bajo 200 líneas. Si está creciendo más allá de eso, divide las reglas en archivos con alcance de directorio. Revisa y actualiza tu CLAUDE.md mensualmente, especialmente después de refactorizaciones importantes o cambios de stack. Versiona el archivo junto a tu código para que cada miembro del equipo y cada ejecución de CI/CD obtenga el mismo contexto.
Escribe reglas como imperativos claros. En lugar de "generalmente preferimos usar async/await," escribe "usar async/await para todas las operaciones asíncronas, nunca usar callbacks crudos o cadenas .then()." Cuanto más explícito seas, más consistentemente Claude seguirá la regla.
Prueba este ejercicio: inicia una nueva sesión de Claude Code, pide a Claude que escriba un componente o función, luego revisa la salida en busca de cualquier cosa que viole las convenciones de tu proyecto. Por cada violación, agrega una regla a CLAUDE.md, luego inicia una nueva sesión e intenta la misma tarea de nuevo. Verás mejoras inmediatas.
Finalmente, comparte tu CLAUDE.md con tu equipo. Cuando todos usan el mismo archivo de memoria del proyecto, Claude produce salida consistente sin importar quién esté haciendo el prompting. Esta es una de las formas más simples de estandarizar el desarrollo asistido por IA en todo un equipo.