CLAUDE.md es el archivo de configuración que Claude Code lee automáticamente al iniciar en un proyecto. Es tu forma de decirle al agente cómo debe comportarse, qué convenciones seguir y qué contexto necesita para ser útil desde el primer mensaje.

Qué va en CLAUDE.md y qué no

CLAUDE.md no es documentación técnica del proyecto. Es un briefing para el agente. Incluye información que Claude necesita para operar bien pero que no puede inferir leyendo el código.

Sí incluir:

  • Stack tecnológico y versiones específicas
  • Convenciones de código del proyecto
  • Comandos de desarrollo, test y deploy
  • Restricciones y archivos que no debe tocar
  • Contexto del negocio o dominio no obvio

No incluir:

  • Documentación de funciones (eso va en el código)
  • Historiales de cambios
  • Documentación para usuarios humanos
  • Cosas que Claude puede inferir leyendo el código

Estructura recomendada

# Proyecto

[2-3 frases describiendo qué hace el proyecto y para quién]

## Stack

- Runtime: Node.js 20
- Framework: Next.js 14 App Router
- Base de datos: PostgreSQL vía Drizzle ORM
- Tests: Vitest + Testing Library

## Comandos

```bash
npm run dev          # servidor desarrollo en :3000
npm run test         # tests en modo watch
npm run test:ci      # tests sin watch (para CI)
npm run db:push      # sincronizar schema con BD

Convenciones

  • Componentes en PascalCase, hooks con prefijo use
  • Imports absolutos desde @/ (alias configurado en tsconfig)
  • No usar any en TypeScript — usa unknown si necesitas
  • Tests junto al archivo que testean, no en carpeta separada

Restricciones

  • No modificar src/migrations/ — las migraciones se generan automáticamente
  • No instalar dependencias sin confirmar primero
  • El directorio src/lib/vendor/ es código de terceros, no tocarlo

## El error más común: instrucciones vagas

Las instrucciones vagas no ayudan. "Escribe código limpio" o "sigue las mejores prácticas" no le dice nada útil al agente. Sé específico sobre qué significa limpio en tu proyecto.

En lugar de:

Usa buenas prácticas de seguridad.


Escribe:

Validación de inputs: usa Zod en todos los endpoints de API. Nunca construyas queries SQL con concatenación de strings — usa siempre parámetros preparados. Las claves de API van en variables de entorno, nunca hardcodeadas.


## CLAUDE.md en subdirectorios

Claude Code lee todos los CLAUDE.md en la jerarquía de directorios. Puedes tener uno raíz con configuración global y archivos adicionales en subdirectorios para contexto específico:

proyecto/ ├── CLAUDE.md # config global ├── frontend/ │ └── CLAUDE.md # convenciones específicas del frontend └── backend/ └── CLAUDE.md # convenciones del backend


El agente combina todos los contextos relevantes según el directorio donde esté trabajando.

## Actualiza CLAUDE.md cuando el proyecto cambia

CLAUDE.md es un documento vivo. Si cambias el stack, añades una nueva convención o descubres que el agente hace algo que no quieres consistentemente, actualiza el archivo. Es más eficiente que corregirle en cada sesión.

Un CLAUDE.md bien mantenido es la diferencia entre un agente que necesita orientación constante y uno que opera bien desde el inicio.