CursosBlogClaude WebinarIniciar sesión
Inicio

CLAUDE.md - La Memoria Persistente del Proyecto

Capítulo 3: CLAUDE.md - La Memoria Persistente del Proyecto

La Revolución de la Documentación Inteligente

El archivo CLAUDE.md representa una innovación fundamental en la gestión de contexto para proyectos de desarrollo. No es simplemente otro archivo de documentación; es la memoria persistente del proyecto que permite que Claude Code mantenga comprensión profunda y consistente del contexto, las decisiones arquitectónicas, y las peculiaridades específicas que definen cómo debe abordarse el trabajo en cada proyecto único.

Esta aproximación transforma la relación entre documentación y desarrollo activo. Tradicionalmente, la documentación se vuelve obsoleta rápidamente porque requiere mantenimiento manual que compite con la presión de entregar features. CLAUDE.md invierte esta dinámica: se convierte en una herramienta activa que mejora directamente la productividad diaria, creando incentivos naturales para mantenerla actualizada y relevante.

¿Qué es CLAUDE.md?

CLAUDE.md es un archivo especial que Claude Code lee automáticamente al comenzar cualquier sesión en tu proyecto. Funciona como un "cerebro compartido" que contiene:

  • Contexto del proyecto: Qué hace tu aplicación y por qué existe
  • Decisiones arquitectónicas: Por qué elegiste ciertas tecnologías y patrones
  • Convenciones del código: Estilo, naming, y mejores prácticas específicas
  • Comandos útiles: Scripts, herramientas, y workflows comunes
  • Información de contacto: Emails, recursos, y links importantes

Estructura Básica de CLAUDE.md

Ejemplo de Estructura Completa

1# Mi Proyecto - Context para Claude
2
3## Descripción del Proyecto
4Una aplicación web de e-commerce construida con React y Node.js que permite...
5
6## Stack Tecnológico
7- **Frontend**: React 18, TypeScript, Tailwind CSS
8- **Backend**: Node.js, Express, PostgreSQL
9- **Testing**: Jest, React Testing Library
10- **Deployment**: Vercel (frontend), Railway (backend)
11
12## Estructura de Archivos
13- `src/components/` - Componentes reutilizables
14- `src/pages/` - Páginas principales
15- `src/hooks/` - Custom hooks
16- `src/utils/` - Funciones utilitarias
17- `src/types/` - Definiciones de TypeScript
18
19## Convenciones de Código
20- Usar arrow functions para componentes
21- Nombres de archivos en camelCase
22- Interfaces con prefijo 'I': `IUser`, `IProduct`
23- Custom hooks empiezan con 'use': `useAuth`, `useCart`
24
25## Scripts Útiles
26- `npm run dev` - Desarrollo local
27- `npm run build` - Build para producción
28- `npm run test` - Ejecutar tests
29- `npm run lint` - Verificar código
30
31## APIs y Servicios
32- **Auth**: usando JWT tokens en localStorage
33- **Payments**: Stripe integration en `/api/payments`
34- **Database**: PostgreSQL con Prisma ORM
35
36## Información de Contacto
37- **Email principal**: dev@miempresa.com
38- **Documentación**: https://docs.miproyecto.com
39- **Repositorio**: https://github.com/usuario/mi-proyecto
40

Secciones Esenciales

1. Descripción y Contexto

Siempre comienza explicando qué hace tu proyecto y por qué existe. Esto ayuda a Claude a entender el objetivo general.

1## Descripción del Proyecto
2Esta es una aplicación de gestión de tareas para equipos remotos. 
3Permite crear proyectos, asignar tareas, trackear tiempo, y generar reportes.
4El objetivo es reemplazar el uso de múltiples herramientas dispersas.
5

2. Stack Tecnológico

Lista las tecnologías principales con versiones específicas cuando sea relevante:

1## Stack Tecnológico
2- **Frontend**: Next.js 14, React 18, TypeScript 5.x
3- **Styling**: Tailwind CSS 3.x
4- **Estado**: Zustand para estado global
5- **Base de datos**: MongoDB con Mongoose
6- **Autenticación**: NextAuth.js
7- **Deployment**: Vercel
8

3. Convenciones Específicas

Documenta las reglas y patrones únicos de tu proyecto:

1## Convenciones de Código
2- Componentes siempre con TypeScript interfaces
3- Usar barrel exports en cada carpeta (index.ts)
4- Estados de loading siempre llamados `isLoading`
5- Errores siempre en formato `{ message: string, code?: string }`
6- APIs responses en formato `{ data: T, error?: string }`
7

4. Comandos y Scripts

Lista los comandos más útiles para desarrollo:

1## Comandos Útiles
2- `npm run dev` - Servidor de desarrollo
3- `npm run build` - Build de producción  
4- `npm run test` - Tests con Jest
5- `npm run test:watch` - Tests en modo watch
6- `npm run db:migrate` - Ejecutar migraciones
7- `npm run db:seed` - Sembrar datos de prueba
8

5. Configuraciones Importantes

Incluye configuraciones específicas o variables de entorno:

1## Configuración
2### Variables de Entorno Requeridas
3- `DATABASE_URL` - URL de la base de datos
4- `NEXTAUTH_SECRET` - Secret para NextAuth
5- `STRIPE_SECRET_KEY` - API key de Stripe
6
7### Puertos por Defecto
8- Frontend: 3000
9- Backend API: 3001
10- Database: 5432
11

Mejores Prácticas para CLAUDE.md

1. Mantén la Información Actualizada

CLAUDE.md solo es útil si refleja el estado actual del proyecto. Actualízalo cuando:

  • Cambies tecnologías o dependencias principales
  • Modifiques convenciones de naming o estructura
  • Agregues nuevos scripts o comandos importantes
  • Changes en la arquitectura o patrones

2. Sé Específico, No Genérico

En lugar de escribir "usamos buenas prácticas", especifica:

1❌ Malo:
2- Seguimos buenas prácticas de React
3
4✅ Mejor:
5- Componentes funcionales con TypeScript
6- Props destructuring en la función
7- Custom hooks para lógica compartida
8- React.memo para componentes que rerenderean frecuentemente
9

3. Incluye Contexto de Decisiones

Explica por qué tomas ciertas decisiones, no solo qué haces:

1## Decisiones Arquitectónicas
2
3### Por qué Zustand sobre Redux
4- Menor boilerplate para nuestro caso de uso simple
5- TypeScript support nativo
6- Bundle size más pequeño
7- API más intuitiva para el equipo
8
9### Por qué MongoDB sobre PostgreSQL
10- Esquemas flexibles para datos de usuario variables
11- Mejor performance para nuestros queries de lectura
12- Experiencia previa del equipo
13

4. Organiza por Frecuencia de Uso

Pon la información más usada al principio:

1# Mi Proyecto
2
3## Stack Principal (lo más importante)
4...
5
6## Comandos Diarios (muy frecuente)
7...
8
9## Configuración Avanzada (menos frecuente)
10...
11
12## Información Histórica (raramente necesaria)
13...
14

Ejemplos por Tipo de Proyecto

Para una API REST

1## Endpoints Principales
2- `GET /api/users` - Listar usuarios
3- `POST /api/users` - Crear usuario
4- `PUT /api/users/:id` - Actualizar usuario
5- `DELETE /api/users/:id` - Eliminar usuario
6
7## Autenticación
8- Header: `Authorization: Bearer <token>`
9- Tokens válidos por 24 horas
10- Refresh tokens en cookie httpOnly
11
12## Manejo de Errores
13- Status codes estándar HTTP
14- Formato: `{ error: string, details?: object }`
15- Logging con Winston en producción
16

Para una App React

1## Estructura de Componentes
2- Componentes de UI en `/src/components/ui/`
3- Componentes de página en `/src/components/pages/`
4- Layouts en `/src/components/layouts/`
5
6## Manejo de Estado
7- Estado local con useState/useReducer
8- Estado global con Context API en `/src/context/`
9- Estado de servidor con React Query
10
11## Routing
12- React Router v6
13- Rutas protegidas con ProtectedRoute component
14- Lazy loading para páginas con React.lazy()
15

Para un Proyecto Full-Stack

1## Arquitectura
2- Frontend: Next.js con API routes
3- Database: PostgreSQL con Prisma
4- Authentication: NextAuth.js con GitHub provider
5- File storage: AWS S3 para imágenes
6
7## Flujo de Datos
81. Frontend hace request a `/api/...`
92. API route valida autenticación
103. Prisma query a PostgreSQL
114. Response en formato JSON estándar
12
13## Deployment
14- Frontend y API en Vercel
15- Database en Railway
16- Variables de entorno en Vercel dashboard
17

Integrando CLAUDE.md en tu Workflow

1. Creación Inicial

Al empezar un proyecto, crea CLAUDE.md inmediatamente:

1# En la raíz de tu proyecto
2touch CLAUDE.md
3echo "# Mi Proyecto - Contexto para Claude" > CLAUDE.md
4

2. Actualización Regular

Agrega una tarea recurrente para revisar CLAUDE.md:

  • Cada sprint/milestone importante
  • Cuando onboardees nuevos desarrolladores
  • Después de cambios arquitectónicos significativos

3. Colaboración en Equipo

Si trabajas en equipo, considera:

  • Hacer CLAUDE.md parte del code review
  • Documentar decisiones importantes inmediatamente
  • Usar como referencia en onboarding

Comandos Útiles para Mantener CLAUDE.md

1## Scripts de Mantenimiento
2- `npm run docs:update` - Actualizar documentación
3- `npm run analyze` - Analizar dependencias
4- `npm run audit` - Revisar seguridad
5- `npm run clean` - Limpiar cache y node_modules
6

Conclusión

CLAUDE.md transforma cómo Claude Code entiende y trabaja con tu proyecto. Es la diferencia entre tener un asistente que necesita explicaciones constantes versus uno que "conoce" tu codebase y puede trabajar de manera autónoma y consistente.

La inversión de tiempo en crear y mantener un CLAUDE.md completo se paga inmediatamente en productividad aumentada y menos fricción en cada interacción con Claude Code.

En el próximo capítulo exploraremos todos los comandos disponibles en Claude Code, desde los básicos hasta los más avanzados, proporcionándote una referencia completa de la caja de herramientas.

Un CLAUDE.md bien estructurado es la base de una colaboración efectiva con AI. Cada minuto invertido en documentar tu contexto se multiplica en horas de productividad ganadas.