CLAUDE.md — Memoria del Proyecto
El Problema que Resuelve CLAUDE.md
Cada vez que inicias una nueva sesion 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 arquitectonicas que has tomado. Sin este contexto, Claude podria generar codigo usando CommonJS cuando tu usas ES modules, sugerir Jest cuando usas Vitest, o formatear codigo en un estilo que choca con tu linter.
CLAUDE.md es la solucion. Es un archivo de markdown plano que Claude carga automaticamente al inicio de cada sesion, dandole memoria persistente del proyecto. Piensa en el como un documento de incorporacion para tu programador de pares con IA -- el mismo tipo de notas que le darias a un nuevo miembro del equipo en su primer dia.
La Jerarquia de Memoria
Claude Code lee archivos CLAUDE.md desde multiples ubicaciones, y cada nivel de la jerarquia agrega contexto. Los archivos cargados despues pueden construir sobre o sobreescribir los anteriores:
Nivel global -- ~/.claude/CLAUDE.md se aplica a cada proyecto en tu maquina. Pon tus preferencias personales aqui: tu idioma preferido, estilo de codigo, convenciones del editor y cualquier regla universal.
Nivel de proyecto -- ./CLAUDE.md en la raiz de tu proyecto. Este es el archivo mas importante. Contiene contexto especifico del proyecto: stack tecnologico, comandos de compilacion, 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 asi sucesivamente. Estos proporcionan contexto con alcance especifico para areas determinadas de tu base de codigo. Cuando Claude esta trabajando en un directorio particular, recoge el CLAUDE.md con alcance relevante automaticamente.
Los tres niveles se fusionan, dandole a Claude una comprension en capas de tus preferencias globales, reglas del proyecto y convenciones especificas de directorio.
Que Poner en Tu CLAUDE.md
Los archivos CLAUDE.md mas efectivos cubren cuatro areas: vista general del proyecto, comandos de desarrollo, convenciones de codigo y patrones comunes. Aqui 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 aqui 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
Que NO Poner en CLAUDE.md
Mantiene esto fuera de tu CLAUDE.md:
Secretos y credenciales. Nunca pongas claves API, contrasenas 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 arbol de archivos por si mismo. Una vista general de la arquitectura de alto nivel es mucho mas util que un volcado de directorio de 500 lineas.
Contexto especifico de sesion. No pongas cosas como "actualmente estamos refactorizando el modulo de auth." Eso pertenece a tu conversacion con Claude, no en un archivo persistente.
Documentacion demasiado verbosa. Apunta a menos de 200 lineas. Claude tiene una ventana de contexto finita, y cada linea de CLAUDE.md consume tokens. Se conciso y prioriza la informacion que Claude necesita con mas frecuencia.
Memoria con Alcance de Directorio
Para proyectos mas grandes, los archivos CLAUDE.md a nivel de directorio te permiten dar a Claude contexto especializado para diferentes partes de tu base de codigo. 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 esta editando un archivo en src/api/, automaticamente recoge las reglas especificas de la API. Cuando se mueve a src/components/, carga las guias 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 codigo.
Auto-Memoria y el Comando /memory
Claude Code tambien puede aprender tus preferencias con el tiempo a traves de la auto-memoria. Cuando corriges a Claude durante una sesion -- "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 retroalimentacion donde Claude se vuelve mas inteligente sobre tu proyecto cuanto mas lo usas. Con el tiempo, tu CLAUDE.md crece organicamente basado en correcciones y preferencias reales.
El Comando /init
Si estas 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 analizara tu proyecto -- leyendo package.json, archivos de configuracion, estructura de directorios y documentacion existente -- y luego generara un CLAUDE.md adaptado a lo que encuentre. Puedes revisar y editar el resultado antes de guardar.
Esto es mas rapido que escribir un CLAUDE.md desde cero y asegura que no te pierdas elementos obvios como comandos de compilacion y scripts de test.
Mejores Practicas
Manten tu CLAUDE.md bajo 200 lineas. Si esta creciendo mas alla de eso, divide las reglas en archivos con alcance de directorio. Revisa y actualiza tu CLAUDE.md mensualmente, especialmente despues de refactorizaciones importantes o cambios de stack. Versiona el archivo junto a tu codigo para que cada miembro del equipo y cada ejecucion 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 asincronas, nunca usar callbacks crudos o cadenas .then()." Cuanto mas explicito seas, mas consistentemente Claude seguira la regla.
Prueba este ejercicio: inicia una nueva sesion de Claude Code, pide a Claude que escriba un componente o funcion, luego revisa la salida en busca de cualquier cosa que viole las convenciones de tu proyecto. Por cada violacion, agrega una regla a CLAUDE.md, luego inicia una nueva sesion e intenta la misma tarea de nuevo. Veras 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 quien este haciendo el prompting. Esta es una de las formas mas simples de estandarizar el desarrollo asistido por IA en todo un equipo.