CLAUDE.md: el archivo que hace a Claude Code 10x más útil (con plantilla y ejemplos reales)

CLAUDE.md es el archivo que le dice a Claude Code cómo funciona tu proyecto antes de que toques una sola tecla. Es la diferencia entre empezar cada sesión explicando lo mismo y empezar directamente a trabajar. Un buen CLAUDE.md puede ahorrar 10–15 minutos por sesión y evitar los errores más comunes. Esta guía te dice qué poner, con ejemplos reales.

Si aún estás en tus primeras sesiones con Claude Code, lee primero la guía de primer proyecto. Si ya entiendes el flujo básico, este artículo es el siguiente paso.

Qué es CLAUDE.md y por qué existe

Cada vez que abres Claude Code en modo interactivo, el agente lee automáticamente el archivo CLAUDE.md si existe en la raíz del proyecto. También lee los CLAUDE.md que estén en subcarpetas cuando trabaja en esas partes del código.

El propósito es simple: darle a Claude el "onboarding" que le darías a un desarrollador nuevo. Qué hace el proyecto, cómo está organizado, qué tecnologías usa, qué convenciones seguimos, qué no debe tocar, cómo correr los tests. Todo eso en un archivo que se lee una sola vez y aplica en cada sesión.

Sin CLAUDE.md: repites contexto en cada sesión, Claude puede hacer suposiciones equivocadas sobre el stack y tienes más errores.

Con CLAUDE.md bien hecho: Claude arranca con contexto real, hace menos preguntas obvias y los resultados son más precisos desde el primer mensaje.

Dónde van los archivos CLAUDE.md

Hay tres niveles:

• Global (~/.claude/CLAUDE.md): aplica a todos tus proyectos. Bueno para tus preferencias personales (idioma de los comentarios, estilo de commits, herramientas que siempre usas).
• Raíz del proyecto (CLAUDE.md en la carpeta principal): el más importante. Aplica a toda la sesión. Compártelo con tu equipo metiéndolo al repositorio.
• Subdirectorios (src/api/CLAUDE.md, etc.): Claude lo lee cuando trabaja en esa parte del código. Útil para módulos complejos con lógica propia o restricciones específicas.

Empieza con el de la raíz del proyecto. Los demás son optimizaciones para cuando el proyecto crece.

Qué poner en tu CLAUDE.md

1. De qué trata el proyecto

Una o dos frases. Claude ya puede leer el código, pero saber el propósito orienta las decisiones cuando hay ambigüedad.

# Proyecto: Panel de administración de inventario

Sistema web interno para gestionar el inventario de una cadena de tiendas.
Los usuarios son administradores de bodega, no técnicos. La simplicidad
de la UI es más importante que las funciones avanzadas.

2. Stack tecnológico

Qué lenguajes, frameworks, bases de datos y servicios usa el proyecto. Esto evita que Claude sugiera soluciones incompatibles.

## Stack
- Backend: Node.js 20 con Express
- Base de datos: PostgreSQL 15 con Prisma ORM
- Frontend: React 18 con Vite y TailwindCSS
- Autenticación: Supabase Auth
- Deploy: Vercel (frontend) + Railway (backend)

3. Comandos que se usan siempre

Los comandos de desarrollo, testing y build. Así Claude puede correrlos cuando necesita verificar su trabajo.

## Comandos
- Desarrollo: `npm run dev` (puerto 3000 frontend, 4000 backend)
- Tests: `npm test` (Jest, todos los archivos *.test.ts)
- Tests de un archivo: `npm test -- src/auth/login.test.ts`
- Build: `npm run build`
- Linting: `npm run lint` (ESLint + Prettier)

4. Estructura de carpetas importante

No necesitas documentar cada carpeta — solo las que no son obvias o las que tienen lógica especial.

## Estructura relevante
- `src/services/`: lógica de negocio, sin dependencias de HTTP
- `src/routes/`: solo reciben requests y llaman a services
- `src/db/migrations/`: NO editar manualmente, usar Prisma migrate
- `scripts/`: utilidades de CLI internas, no son parte de la app

5. Convenciones del equipo

Lo que no está en ningún linter pero el equipo siempre hace. Aquí es donde más tiempo se ahorra, porque Claude evita los "eso no va así" durante las revisiones.

## Convenciones
- Commits en español, en imperativo: "Agrega validación", "Corrige bug en login"
- Nombres de variables y funciones en inglés
- Archivos de componentes: PascalCase.tsx
- Archivos de utilidades: camelCase.ts
- No usar `any` en TypeScript. Si no sabes el tipo, preguntar antes de poner any.
- Siempre agregar JSDoc a funciones públicas de services
- Los errores se loguean con el logger de `src/utils/logger.ts`, no con console.log

6. Lo que NO debe tocar

Archivos o carpetas críticos, generados automáticamente o con restricciones especiales. Este bloque evita errores graves.

## No modificar sin consultar
- `src/db/schema.prisma`: cambios requieren migración y aprobación
- `src/config/permissions.ts`: lógica de permisos crítica, revisar con el equipo
- `public/`: archivos estáticos generados, no editar a mano
- `.env.example`: plantilla compartida, no agregar valores reales

7. Contexto de negocio que cambia el código

Decisiones de arquitectura con "por qué" detrás. Sin este contexto, Claude puede "mejorar" algo que en realidad tiene una razón para ser como es.

## Decisiones de arquitectura
- No usamos Redux ni estado global: la app es pequeña y el contexto de React es suficiente
- Los IDs de productos son strings UUID, no integers: compatibilidad con sistema legacy
- Autenticación por JWT sin refresh tokens: los usuarios son internos, la sesión dura 8h
- No hay soft delete: los registros eliminados se archivan en tablas _archived

Plantilla base para copiar

Copia este esqueleto y rellena con tu proyecto:

# [Nombre del proyecto]

[1-2 frases de qué hace y para quién]

## Stack
- [Lenguaje y versión]
- [Framework principal]
- [Base de datos]
- [Otros servicios relevantes]

## Comandos
- Desarrollo: `[comando]`
- Tests: `[comando]`
- Build: `[comando]`
- Linting: `[comando]`

## Estructura relevante
- [carpeta]: [qué hay ahí]
- [carpeta]: [qué hay ahí]

## Convenciones
- [Convención 1]
- [Convención 2]
- [Convención 3]

## No modificar sin consultar
- [archivo o carpeta]: [por qué]

## Contexto importante
- [Decisión de arquitectura con su razón]
- [Restricción del negocio que afecta el código]

Lo que NO poner en CLAUDE.md

• Secretos o credenciales. CLAUDE.md va al repositorio. Las variables de entorno, API keys y contraseñas van en .env, nunca aquí.
• Documentación que ya existe. Si tienes un README detallado, un CONTRIBUTING.md o documentación en otro archivo, no copies su contenido — solo referencia dónde está.
• Demasiado texto. CLAUDE.md muy largo (más de 200 líneas) ocupa contexto y diluye lo importante. Si crece mucho, divide en CLAUDE.md por subdirectorio o usa el global para preferencias personales.
• Instrucciones obvias. "Escribe código limpio" o "sé preciso" no sirven. Todo lo que Claude puede inferir del código, sobra en CLAUDE.md.

Cómo mantenerlo actualizado

El mejor momento para actualizar CLAUDE.md es durante una sesión con Claude Code, justo después de que le tuviste que corregir algo. Le pides:

Agrega al CLAUDE.md que en este proyecto los IDs siempre son UUID strings, no integers. Eso lo vas a necesitar en cualquier función que maneje IDs.

Otra táctica: al terminar una sesión larga, pídele que revise si aprendió algo que valga guardar:

¿Hay algo que descubriste hoy sobre este proyecto que debería estar en el CLAUDE.md y no está?

En resumen

CLAUDE.md es la inversión de 30 minutos que mejora todas las sesiones siguientes. La estructura que funciona: qué hace el proyecto, el stack, los comandos, la estructura relevante, las convenciones del equipo, qué no tocar y el contexto de negocio que afecta el código. Corto, específico y actualizado.

En Aldama tenemos CLAUDE.md en todos nuestros proyectos de desarrollo. Es una de las razones por las que podemos onboardear contexto nuevo rápidamente y mantener consistencia entre sesiones. Si quieres que un equipo con estas prácticas construya algo para ti, lo conversamos. Sin humo.