Guía completa para escribir CLAUDE.md: Mejores prácticas de configuración de proyectos

¿Qué es CLAUDE.md?

CLAUDE.md es un archivo de contexto que ayuda a Claude Code a entender tu proyecto. Colócalo en la raíz de tu proyecto y Claude Code lo leerá automáticamente al inicio de cada sesión. Un CLAUDE.md bien escrito puede mejorar drásticamente la calidad de las respuestas de Claude Code.

Ubicaciones del archivo y prioridad

Puedes colocar archivos CLAUDE.md en múltiples ubicaciones, y todos se cargan:

~/.claude/CLAUDE.md          # Configuración global (compartida en todos los proyectos)
./CLAUDE.md                   # Raíz del proyecto (compartida con el equipo)
./CLAUDE.local.md             # Configuración local (agregar a .gitignore)
./src/CLAUDE.md               # Configuración a nivel de subdirectorio

• Global: Tus preferencias personales de estilo de código
• Raíz del proyecto: Reglas compartidas del equipo y stack tecnológico
• Local: Configuraciones personales que no se suben al repositorio
• Subdirectorio: Contexto adicional para módulos específicos

Plantilla inicial

Aquí tienes una plantilla práctica de CLAUDE.md:

# Descripción del proyecto

API backend de e-commerce. Maneja gestión de pedidos, inventario y autenticación de usuarios.

## Stack tecnológico

- Lenguaje: TypeScript 5.x
- Runtime: Node.js 22
- Framework: Fastify
- BD: PostgreSQL 16 + Prisma ORM
- Testing: Vitest
- CI: GitHub Actions

## Estructura de directorios

src/
  routes/       # Definiciones de endpoints de API
  services/     # Lógica de negocio
  repositories/ # Capa de acceso a datos
  middleware/   # Autenticación, logging, manejo de errores
  utils/        # Funciones utilitarias
  types/        # Definiciones de tipos

## Convenciones de código

- Usar funciones flecha
- Siempre usar try-catch para manejo de errores con clases de error personalizadas
- Nomenclatura: camelCase (variables/funciones), PascalCase (tipos/clases)
- Nombres de archivos: kebab-case
- Usar alias de ruta `@/` en lugar de importaciones relativas

## Comandos comunes

- Ejecutar tests: `npm test`
- Verificar tipos: `npx tsc --noEmit`
- Lint: `npm run lint`
- Migración de BD: `npx prisma migrate dev`
- Servidor de desarrollo: `npm run dev`

## Reglas importantes

- Siempre crear una migración después de cambiar prisma/schema.prisma
- Cada endpoint de API debe tener un schema de validación con Zod
- Registrar nuevas rutas en routes/index.ts

Consejos para escribir archivos CLAUDE.md efectivos

1. Sé conciso

CLAUDE.md consume tokens de la ventana de contexto. Evita explicaciones extensas y usa viñetas.

# Mal ejemplo
Este proyecto usa TypeScript. TypeScript es un lenguaje desarrollado
por Microsoft que agrega tipos a JavaScript...

# Buen ejemplo
- Lenguaje: TypeScript 5.x (modo estricto)

2. Documenta lo que no quieres

Listar explícitamente los anti-patrones es sorprendentemente efectivo.

## Prohibido

- No usar tipos `any`
- No usar exportaciones por defecto (solo exportaciones con nombre)
- No usar console.log para depuración (usar el logger)
- Nunca eliminar ni omitir tests existentes

3. Define flujos de trabajo

Guía a Claude Code sobre cómo abordar las tareas.

## Agregar una nueva funcionalidad

1. Crear definiciones de tipos en `src/types/`
2. Implementar la capa de acceso a datos en `src/repositories/`
3. Implementar la lógica de negocio en `src/services/`
4. Definir endpoints en `src/routes/`
5. Escribir tests unitarios para cada capa
6. Verificar que todos los tests pasen con `npm test`

4. Captura el conocimiento tribal

Documenta información importante que no está escrita en ningún otro lugar.

## Notas específicas del proyecto

- `user_id` usa UUID v7 (para ordenamiento temporal)
- Todos los cálculos de precios deben usar `Decimal.js` (para evitar errores de punto flotante)
- Las variables de entorno están centralizadas en `src/config.ts` — nunca acceder a process.env directamente

Uso en equipo

Configuración de .gitignore

Mantén las configuraciones personales fuera del control de versiones:

# .gitignore
CLAUDE.local.md

Incluir en revisiones de código

Trata CLAUDE.md como un documento importante del proyecto. Inclúyelo en las revisiones de PR y mantenlo actualizado como equipo.

Cuándo actualizar CLAUDE.md

• Cuando agregues una nueva librería
• Cuando cambies las convenciones de código
• Cuando reestructures directorios
• Cuando notes que Claude Code comete el mismo error repetidamente

Conclusión

CLAUDE.md convierte a Claude Code en un experto en tu proyecto específico. Comienza generando una estructura base con /init, y luego refínala mientras trabajas. Compártela con tu equipo para que todos se beneficien de interacciones optimizadas con Claude Code.