¿Qué poner en CLAUDE.md?
Tiempo de lectura: 7 minutosEl archivo CLAUDE.md le indica a Claude Code cómo comportarse en tu proyecto: qué tecnologías usas, qué convenciones seguir y qué errores evitar. Configurarlo bien desde el principio ahorra tiempo, reduce fricciones y hace que el asistente trabaje como si conociera tu proyecto de memoria.
¿Qué es CLAUDE.md y para qué sirve?
CLAUDE.md es un archivo de texto en formato Markdown que Claude Code lee automáticamente al iniciarse en un proyecto. Su función es darle contexto al asistente: qué tipo de proyecto es, cómo está organizado, qué convenciones de código se siguen y qué debe evitar hacer.
Piénsalo como el documento de incorporación que le entregarías a un desarrollador nuevo. Sin ese contexto, el asistente trabaja con suposiciones. Con un buen CLAUDE.md, trabaja con información concreta.
Esto es especialmente valioso en proyectos medianos o grandes, donde las decisiones de arquitectura no son evidentes a simple vista. En la práctica, la diferencia entre tener y no tener este archivo se nota desde la primera sesión de trabajo.
¿Dónde se coloca el archivo CLAUDE.md?
Claude Code admite múltiples ubicaciones para el archivo, y cada una tiene un alcance diferente:
- Raíz del proyecto (
./CLAUDE.md): es la ubicación más común. Se aplica a todo el repositorio. - Carpetas específicas (
./src/CLAUDE.md,./api/CLAUDE.md): útil cuando distintas partes del proyecto tienen lógicas o tecnologías diferentes. - Directorio home del usuario (
~/.claude/CLAUDE.md): instrucciones globales que aplican a todos los proyectos. Sirve para preferencias personales del desarrollador.
Cuando existen varios archivos, Claude Code los combina jerárquicamente: primero el global, luego el de la raíz, luego los de subcarpetas. Las instrucciones más específicas tienen más peso.
Qué poner en CLAUDE.md: estructura recomendada
No existe un formato oficial obligatorio, pero hay una estructura que funciona bien en la mayoría de los proyectos:
1. Descripción general del proyecto
Una o dos frases que explican qué hace el proyecto y para quién. No hace falta que sea literaria: tiene que ser precisa.
## Descripción del proyecto
API REST en Node.js para gestionar reservas de turnos médicos.
Usuarios principales: clínicas pequeñas y consultorios independientes.
2. Stack tecnológico
Listar las tecnologías principales con las versiones exactas cuando sea relevante. Esto evita que Claude Code sugiera soluciones incompatibles con tu entorno.
## Stack
- Node.js 20.x
- Express 4.x
- PostgreSQL 15 con Prisma ORM
- Jest para testing
- Docker para entornos locales
3. Convenciones de código
Este es uno de los bloques más importantes. Si tu equipo sigue reglas específicas, ponlas aquí de forma explícita.
## Convenciones
- Usar camelCase para variables y funciones
- Usar PascalCase para clases y componentes
- Siempre usar async/await en lugar de callbacks
- No usar `var`. Solo `const` y `let`
- Los archivos de test van en la misma carpeta que el módulo, con extensión `.test.js`
4. Estructura de directorios
Una descripción breve de cómo está organizado el proyecto. No hace falta detallar cada carpeta: basta con las que tienen lógica no evidente.
## Estructura principal
- /src/routes → definición de rutas HTTP
- /src/services → lógica de negocio
- /src/repositories → acceso a base de datos
- /src/middlewares → autenticación, validaciones, logs
- /tests → pruebas de integración
5. Comandos frecuentes
Los comandos que se usan durante el desarrollo. Tener esto en CLAUDE.md permite que Claude Code los ejecute directamente cuando corresponde.
# Instalar dependencias
npm install
# Iniciar en modo desarrollo
npm run dev
# Ejecutar tests
npm test
# Aplicar migraciones de base de datos
npx prisma migrate dev
6. Qué evitar
Esta sección es subestimada y muy útil. Indica comportamientos que no quieres que el asistente adopte.
## Qué evitar
- No modificar archivos en /config sin consultar primero
- No instalar dependencias nuevas sin mencionarlo explícitamente
- No refactorizar código que no esté directamente relacionado con la tarea actual
- No usar librerías de fecha distintas a date-fns (ya incluida en el proyecto)
7. Contexto adicional relevante
Cualquier información que ayude a entender decisiones de diseño ya tomadas. Por ejemplo: por qué se usa una librería en lugar de otra, qué módulos están en proceso de migración o qué partes del código son legacy y no deben tocarse.
Ejemplos reales de secciones útiles
Ejemplo 1: proyecto WordPress con Elementor
## Contexto
Sitio corporativo en WordPress 6.x con Elementor Pro 3.x.
No usar el editor de bloques de WordPress (Gutenberg) para páginas de contenido.
## Convenciones
- Los hooks personalizados van en /wp-content/themes/mi-tema/includes/
- No editar directamente el theme padre; usar el child theme
- Las traducciones están en /languages/ y usan la función __() de WordPress
## Qué evitar
- No agregar plugins sin verificar compatibilidad con Elementor
- No modificar funciones.php del theme padre
Ejemplo 2: proyecto de automatización con n8n
## Proyecto
Flujos de automatización para una empresa de e-commerce.
Se procesan pedidos, notificaciones y sincronización de stock con un ERP externo.
## Notas importantes
- La conexión con el ERP usa autenticación OAuth 2.0; las credenciales están en variables de entorno
- Los flujos críticos tienen versión de respaldo en /backups/n8n/
- No activar flujos en producción sin probar en el entorno de staging primero
Si quieres profundizar en cómo escribir instrucciones que realmente mejoren los resultados, la guía sobre buenos prompts para Claude Code ofrece ejemplos concretos que se complementan bien con lo que se puede definir en este archivo.
Errores comunes al escribir CLAUDE.md
1. Escribir demasiado o demasiado poco
Un archivo de 10 líneas no da suficiente contexto. Uno de 500 líneas diluve lo importante. Lo ideal es entre 50 y 150 líneas para la mayoría de los proyectos.
2. Usar lenguaje ambiguo
Frases como «seguir buenas prácticas» no significan nada sin contexto. Mejor especificar: «usar el patrón repositorio para acceso a datos» o «los errores deben lanzarse como instancias de la clase AppError».
3. No actualizar el archivoCLAUDE.md tiene que evolucionar con el proyecto. Si agregas una nueva dependencia importante, una nueva carpeta con lógica específica o un cambio de convención, actualizarlo es parte del flujo de trabajo.
4. Olvidar las restricciones
La sección «qué evitar» suele omitirse por considerar que el asistente «ya lo sabe». En la práctica, es una de las secciones que más previene errores costosos.
5. No probar el archivo
Después de escribir CLAUDE.md, vale la pena hacer algunas consultas de prueba para verificar que el asistente efectivamente toma en cuenta las instrucciones. Si no lo hace, es señal de que algo está mal formulado o el archivo no está en la ubicación correcta.
Consejos poco conocidos para usuarios avanzados
Usar secciones condicionales por entorno
Puedes incluir instrucciones específicas para producción o desarrollo dentro del mismo archivo usando encabezados claros:
## Solo para entorno de producción
- No ejecutar migraciones destructivas sin respaldo previo
- Verificar variables de entorno antes de hacer deploy
Referenciar documentación interna
Si tu proyecto tiene un wiki, un README extendido o una especificación de API, puedes mencionar dónde está. Claude Code puede pedirte que lo compartas si lo necesita.
Incluir ejemplos de código válido
En lugar de solo describir convenciones, incluir un pequeño fragmento de código que muestre el patrón esperado es más efectivo que cualquier descripción textual.
## Ejemplo de estructura de controlador esperada
```javascript
// Correcto
async function getUser(req, res, next) {
try {
const user = await userService.findById(req.params.id);
res.json(user);
} catch (error) {
next(error);
}
}
Definir el idioma de respuesta
Si trabajas en español y quieres que Claude Code responda en ese idioma, puedes indicarlo explícitamente. Parece obvio, pero en proyectos con código en inglés, el asistente a veces alterna entre idiomas.
## Idioma
Responder siempre en español, independientemente del idioma del código.
Para quienes están explorando todo lo que es posible construir con esta herramienta, puede resultar útil revisar qué se puede crear con Claude Code antes de definir las instrucciones del proyecto.
¿Qué hosting necesitas para trabajar con Claude Code?
Claude Code funciona en la terminal y necesita un entorno donde pueda ejecutar comandos, instalar dependencias y acceder a archivos del proyecto. En el desarrollo local esto funciona sin problemas, pero cuando el proyecto escala —o cuando se quiere tener un entorno persistente, compartido o automatizado— un servidor propio marca la diferencia.
¿Por qué un VPS y no un hosting compartido?
Un hosting compartido impone restricciones sobre los procesos que se pueden ejecutar, el tiempo de ejecución de scripts y el acceso SSH completo. Claude Code necesita precisamente ese acceso para funcionar de forma fluida: ejecutar comandos largos, instalar herramientas globales, gestionar entornos virtuales o mantener procesos activos.
Un hosting VPS resuelve todos estos límites. El usuario tiene acceso root, puede configurar el entorno a medida y mantener sesiones de trabajo activas sin que el servidor las interrumpa.
¿Qué especificaciones mínimas se recomiendan?
Para un proyecto de desarrollo individual o de equipo pequeño:
- RAM: 2 GB como mínimo; 4 GB si se ejecutan procesos simultáneos o se aloja también la base de datos
- CPU: 2 vCPUs suelen ser suficientes para desarrollo activo
- Almacenamiento: SSD NVMe para tiempos de respuesta más rápidos en operaciones de lectura/escritura
- Sistema operativo: Ubuntu 22.04 LTS es el entorno más documentado y compatible
Neolo ofrece hosting VPS con estas características, con soporte técnico real y tiempo de respuesta promedio inferior a una hora para el 80% de las consultas. Para quienes vienen del contexto de Claude Code, hay información específica sobre por qué Claude Code necesita un hosting VPS que explica los detalles técnicos con más profundidad.
Cursor vs Claude Code
Si todavía estás evaluando qué herramienta usar para tu flujo de trabajo, este video puede ayudarte a decidir:
Lo que dicen los clientes de Neolo
★★★★★ Mauro Lopreste
«Llevo muchos años alojando mis webs en Neolo. La atención siempre fue excelente.»★★★★★ Marcelo Lara
«Respuesta eficaz e inmediata. Siempre brindan un excelente servicio.»★★★★★ Alejandro Belmonte
«Cliente desde 2006. Siempre me brindaron muy buen servicio, con atención y respuesta rápida.»
Preguntas frecuentes
¿CLAUDE.md es obligatorio para usar Claude Code?
No. Claude Code funciona sin él. Pero sin ese archivo, el asistente no tiene contexto del proyecto y opera con suposiciones generales. En proyectos con más de unas pocas semanas de desarrollo, la diferencia de calidad en las respuestas es notable.
¿Puede haber más de un archivo CLAUDE.md en el mismo proyecto?
Sí. Se pueden tener archivos en subcarpetas con instrucciones específicas para esa parte del proyecto. Claude Code los combina según la jerarquía de directorios.
¿Cuánto texto debe tener el archivo CLAUDE.md?
No hay un límite estricto, pero entre 50 y 150 líneas suele ser el rango más efectivo. Un archivo demasiado largo puede diluir las instrucciones más importantes.
¿CLAUDE.md es compatible con otros asistentes como Cursor o Copilot?CLAUDE.md es específico de Claude Code. Cursor usa un archivo llamado .cursorrules. Copilot no tiene un equivalente directo. Si usas múltiples herramientas, tendrás que mantener archivos separados para cada una.
¿Puedo incluir secretos o credenciales en CLAUDE.md?
No. CLAUDE.md es un archivo de texto plano que suele estar en el repositorio. Las credenciales deben manejarse siempre con variables de entorno o un gestor de secretos, nunca en archivos de configuración de texto.
¿Qué pasa si CLAUDE.md tiene instrucciones contradictorias?
Claude Code intentará resolverlas según el contexto, pero puede dar resultados inconsistentes. Es recomendable revisar el archivo periódicamente para eliminar reglas redundantes o contradictorias.
¿Se puede usar CLAUDE.md para proyectos en español?
Sí, y es recomendable hacerlo si el equipo trabaja en español. Se puede indicar explícitamente el idioma de respuesta y documentar las convenciones directamente en español.
Conclusión
Un CLAUDE.md bien escrito es una inversión pequeña con retorno inmediato. Le da al asistente el contexto que necesita para trabajar de forma coherente con tu proyecto: las tecnologías que usas, las convenciones que seguís, las restricciones que importan.
La clave está en ser específico sin ser exhaustivo, y en mantener el archivo actualizado a medida que el proyecto evoluciona.
Si estás llevando tus proyectos con Claude Code a un entorno de servidor propio, un hosting VPS de Neolo ofrece el acceso completo que necesitas para trabajar sin restricciones, con más de 20 años de experiencia en infraestructura y soporte técnico disponible cuando realmente lo necesitas.
