El primer día que usé Claude Code en un proyecto real, le pedí que añadiera un endpoint de autenticación. Lo generó en treinta segundos. Perfecto.
El problema: lo metió en el módulo equivocado, usó una convención de nombres que nadie en el proyecto seguía, y no añadió los tests que el equipo tenía como regla no negociable.
El agente no era malo. Era que no sabía nada del proyecto. No era un problema del modelo — era un problema de contexto. Y CLAUDE.md es exactamente la solución para eso.
Estaba generando código de calidad para un proyecto imaginario que él mismo se había inventado.
Eso cambió cuando añadí el archivo CLAUDE.md en la raíz del repositorio.
Qué es CLAUDE.md y por qué importa
CLAUDE.md es el archivo de instrucciones persistentes que Claude Code lee automáticamente al arrancar en un directorio. Es, en la práctica, el system prompt de tu proyecto.
Sin él, el agente llega a tu codebase sin contexto. Sin saber que usas Bun en lugar de npm. Sin saber que los tests son obligatorios antes de mergear. Sin saber que tu arquitectura tiene capas que no se pueden mezclar.
Puedes consultar cómo funciona este mecanismo en la documentación oficial de Claude Code.
Con él, cada sesión empieza con el agente ya orientado. No tienes que repetir las mismas instrucciones en cada prompt. No tienes que corregir los mismos errores una y otra vez.
Los tres niveles de CLAUDE.md
Claude Code soporta tres ubicaciones para el archivo, y se aplican en cascada:
| Nivel | Ubicación | Alcance |
|---|---|---|
| Global | ~/.claude/CLAUDE.md |
Se aplica a todos los proyectos del usuario |
| Proyecto | CLAUDE.md en la raíz |
Se aplica a ese repositorio; se puede compartir vía git |
| Subdirectorio | src/CLAUDE.md, api/CLAUDE.md, etc. |
Instrucciones específicas de esa carpeta |
El global es para tus preferencias personales: idioma, estilo de commits, herramientas que siempre usas. El de proyecto es el que más importa — contiene la arquitectura, el stack, las restricciones y las convenciones de ese codebase concreto. El de subdirectorio es útil en monorepos donde cada paquete tiene reglas distintas.
Cuando Claude Code lee un archivo en un subdirectorio, aplica también el CLAUDE.md de la raíz. El contexto se acumula.
Qué va en un CLAUDE.md de proyecto
Estas son las secciones que no deberían faltar en ningún proyecto serio:
| Sección | Qué contiene | Por qué importa |
|---|---|---|
| Descripción del proyecto | Qué hace la app, stack principal, versiones clave | El agente necesita saber el dominio para tomar buenas decisiones |
| Comandos habituales | Build, test, lint, dev server — exactamente cómo se ejecutan | Evita que el agente proponga npm install cuando usas bun |
| Arquitectura y convenciones | Estructura de carpetas, patrones usados, capas y sus reglas | Sin esto genera código que no encaja en el diseño del proyecto |
| Reglas de nomenclatura | Cómo se nombran archivos, clases, variables, branches y commits | Consistencia automática sin revisión manual |
| Restricciones explícitas | Qué NO debe hacer el agente — tecnologías prohibidas, capas que no se pueden mezclar | Las restricciones son tan importantes como las instrucciones positivas |
| Contexto de negocio | Decisiones de diseño no obvias y el porqué detrás de ellas | El agente que entiende el “por qué” toma mejores decisiones cuando hay ambigüedad |
Cómo crear tu primer CLAUDE.md: plantilla lista para TypeScript
Este es el mínimo viable que funciona para cualquier proyecto TypeScript. Crea un archivo CLAUDE.md en la raíz del repositorio con esta estructura:
# CLAUDE.md — Nombre del Proyecto
## Descripción
Aplicación [tipo] construida con [stack principal].
Estado: [desarrollo activo / mantenimiento / producción].
## Stack y versiones
- Runtime: Bun 1.2+
- Framework: [Angular 22 / React 19 / NestJS 11]
- Lenguaje: TypeScript 5.5 strict mode
- Testing: Jest + Testing Library
- Linting: ESLint + Prettier
## Convenciones de código
- Usar funciones puras cuando sea posible — evitar efectos secundarios implícitos
- Todos los tipos deben ser explícitos — prohibido `any`
- Los imports se ordenan: externos → internos → relativos
- Archivos: kebab-case. Clases: PascalCase. Variables/funciones: camelCase
## Reglas de commits
- Formato: feat|fix|chore|refactor|test|docs: descripción corta
- En español, imperativo, máximo 72 caracteres
- Ejemplo: feat: añadir validación de email en registro
## Tests
- Todo código nuevo requiere tests — sin excepción
- Los tests van junto al archivo que prueban: product.service.spec.ts
- Mocks en __mocks__/ solo para dependencias externas
## Lo que NO debes hacer
- No usar `any` — si el tipo es desconocido, usa `unknown` y narrowing
- No instalar dependencias sin mencionarlo primero
- No modificar archivos de configuración (.env, tsconfig) sin confirmación
- No generar código comentado — si no va al PR, no lo escribasLa sección de comandos va en un bloque separado para que Claude Code los ejecute directamente:
bun install # instalar dependencias
bun run dev # servidor de desarrollo
bun run test # ejecutar tests
bun run test:watch # tests en modo watch
bun run build # build de producción
bun run lint # lint + format checkEste archivo le da al agente orientación suficiente para trabajar sin supervisión constante en tareas rutinarias.
Un CLAUDE.md específico para un proyecto NestJS
Cuando el proyecto tiene arquitectura definida, las instrucciones tienen que ser más precisas:
# CLAUDE.md — API de Pagos (NestJS)
## Descripción
API REST para procesamiento de pagos. Backend crítico — cada cambio
requiere revisión cuidadosa. En producción desde enero 2025.
## Stack
- NestJS 11 + TypeScript 5.5 strict
- Bun como runtime y gestor de paquetes
- PostgreSQL 16 vía TypeORM 0.3
- Autenticación: JWT + Passport
- Tests: Jest con cobertura mínima del 80%
## Arquitectura — Módulos por dominio
src/
payments/
payments.module.ts
payments.controller.ts (solo routing y validación de input)
payments.service.ts (lógica de negocio)
payments.repository.ts (acceso a base de datos)
dto/create-payment.dto.ts
entities/payment.entity.ts
## Reglas de arquitectura (OBLIGATORIAS)
1. Los controllers NO contienen lógica de negocio — solo validan el input y llaman al service
2. Los services NO acceden directamente a la base de datos — usan el repository
3. Toda comunicación con servicios externos va en providers dedicados, nunca inline
4. Las entidades TypeORM y los DTOs son tipos distintos — nunca mezclarlos
5. Los errores de negocio se lanzan como HttpException con código de error semántico
## Nomenclatura de archivos
- Módulos: payments.module.ts
- Controllers: payments.controller.ts
- Services: payments.service.ts
- DTOs: create-payment.dto.ts (verbo + entidad + .dto.ts)
- Entidades: payment.entity.ts
- Tests: payments.service.spec.ts
## Variables de entorno
- Están en .env.example — usa siempre ese archivo como referencia
- NUNCA hardcodees secrets ni connection strings en el código
- Para acceder a env vars, usa el ConfigService de NestJS, no process.env directamente
## Restricciones críticas
- NO modificar migraciones ya aplicadas — solo crear nuevas
- NO cambiar el schema de pagos sin revisión explícita — tiene impacto en contabilidad
- NO instalar dependencias nuevas sin confirmar primero — hay un proceso de aprobación de seguridadLos comandos habituales en bloque separado:
bun run start:dev # servidor con hot reload
bun run test # unit tests
bun run test:e2e # tests end-to-end
bun run migration:generate # genera migración desde cambio en entidad
bun run migration:run # aplica migraciones pendientesLa diferencia con el archivo básico es la especificidad. Cuanto más específico sea el contexto, menos decisiones ambiguas toma el agente.
Los errores que convierten un CLAUDE.md en ruido
Un CLAUDE.md mal escrito es peor que no tenerlo — el agente lo lee, extrae instrucciones contradictorias o vagas, y actúa con falsa confianza.
Demasiado genérico. “Escribe código limpio y mantenible” no le dice nada al agente que ya no sepa. Las instrucciones tienen que ser concretas: “Los servicios no acceden directamente a la base de datos” es una regla. “Buenas prácticas” no lo es.
Desactualizado. Si migras de npm a Bun y no actualizas el CLAUDE.md, el agente seguirá proponiendo npm run para todo. El archivo es documentación viva — tiene que evolucionar con el proyecto. Una revisión mensual es suficiente en la mayoría de los casos.
Sin restricciones explícitas. El 90% de los CLAUDE.md que he visto dicen qué hacer. Muy pocos dicen qué no hacer. Las restricciones son las que evitan los errores más costosos: “no modifiques migraciones ya aplicadas”, “no instales dependencias sin confirmación”, “no uses any“. Sin esta sección, el agente optimiza para completar la tarea por el camino más corto, que no siempre es el correcto.
Instrucciones que contradicen el código existente. Si el CLAUDE.md dice “usamos Clean Architecture” pero el codebase tiene lógica de negocio en los componentes, el agente entra en conflicto entre seguir las instrucciones o seguir el patrón del código existente.
Casi siempre gana el código existente. El CLAUDE.md tiene que reflejar la realidad del proyecto, no los deseos del developer.
CLAUDE.md + SDD: la combinación que multiplica la calidad
CLAUDE.md da al agente contexto de proyecto. Pero hay algo que va un nivel más arriba: la especificación de cada feature antes de escribir código.
Cuando combinas un buen CLAUDE.md con Spec-Driven Development — escribir la spec de la feature (qué hace, qué tipos maneja, qué contratos define) antes de pedir al agente que genere código — el resultado es cualitativamente distinto.
El agente no adivina la arquitectura porque está en el CLAUDE.md. No adivina el comportamiento de la feature porque está en la spec. El espacio de decisión se reduce al mínimo. Y cuanto menor es el espacio de decisión, más predecible y correcto es el output.
Este es el flujo que aplico en todos los proyectos:
1. CLAUDE.md en la raíz → contexto permanente del proyecto
2. Spec de la feature → descripción de entidades, contratos, flujos
3. Prompt al agente con referencia explícita a la spec
4. Review del código generado contra la spec
5. Tests que validan los contratos de la specEl libro de Spec-Driven Development documenta todo este proceso con las plantillas, los patrones y los ejemplos concretos que uso en producción. Si buscas el marco metodológico detrás de trabajar con agentes de forma estructurada, es el punto de partida más directo.
Dónde encaja esto con el resto de tu flujo con Claude Code
El CLAUDE.md no es el único elemento que necesitas configurar — es el primero.
En el post sobre Clean Architecture en frontend con IA vimos cómo el CLAUDE.md es la pieza que hace que el agente respete las capas de arquitectura en lugar de generar spaghetti. Y en la guía sobre qué es un Agentic Engineer está el contexto profesional más amplio: por qué dar contexto estructurado al agente es una competencia de ingeniería, no un truco de productividad.
Si quieres ver todo esto aplicado en proyectos reales — desde el CLAUDE.md inicial hasta el producto funcionando, con SDD, arquitectura limpia y Claude Code — el curso Construye con IA cubre exactamente ese flujo completo.
El developer que dejó de repetirse
Hay una forma de saber si tu CLAUDE.md funciona: si dejas de decirle al agente las mismas cosas en cada sesión.
“No uses any.” “Pon el test junto al archivo.” “Sigue la estructura de módulos del proyecto.” Si lo estás repitiendo en cada prompt, esa instrucción no está en el CLAUDE.md — o está pero de forma demasiado vaga para que el agente la aplique.
El objetivo del archivo no es documentación. Es eliminar fricción. Cada instrucción que pasa del prompt al CLAUDE.md es tiempo que dejas de invertir en corregir el comportamiento del agente y empiezas a invertir en construir.
Abre tu proyecto. Crea el CLAUDE.md. Empieza con cinco secciones: descripción, comandos, arquitectura, nomenclatura, restricciones. Puedes tenerlo listo en quince minutos.
Si quieres ir más allá — aplicar esto junto con SDD, agentes subagentes y el flujo completo de desarrollo con IA — en Dominicode Labs tenemos los proyectos y los recursos que usamos en producción, con análisis y revisión de código en comunidad.
FAQ — Preguntas frecuentes sobre CLAUDE.md
¿Qué es CLAUDE.md en Claude Code?
CLAUDE.md es un archivo de texto en formato Markdown que Claude Code lee automáticamente al iniciarse en un directorio. Actúa como el system prompt persistente del agente para ese proyecto: define el stack, la arquitectura, las convenciones de código y las restricciones que el agente debe respetar en todas las sesiones, sin necesidad de repetir esas instrucciones en cada prompt.
¿Dónde debe estar el archivo CLAUDE.md?
Puede estar en tres ubicaciones con alcance diferente. En ~/.claude/CLAUDE.md aplica a todos los proyectos del usuario (preferencias globales). En la raíz del repositorio aplica a ese proyecto y se puede compartir con el equipo vía git. En subdirectorios aplica solo a esa carpeta — útil en monorepos. Claude Code aplica todos los que encuentra en la ruta, acumulando el contexto.
¿Cuál es la diferencia entre CLAUDE.md y un prompt de sistema en la API?
Son el mismo concepto en distintos niveles. Un system prompt en la API se configura por llamada o por aplicación. El CLAUDE.md es el system prompt que Claude Code inyecta automáticamente en cada sesión basándose en el directorio de trabajo. La ventaja de CLAUDE.md es que vive en el repositorio, se versiona con git y está disponible para cualquier developer del equipo sin configuración adicional.
¿CLAUDE.md funciona también con Cursor o GitHub Copilot?
El nombre CLAUDE.md es específico de Claude Code (Anthropic). Cursor tiene su propio mecanismo equivalente: archivos .cursor/rules/*.mdc para reglas de proyecto. GitHub Copilot usa copilot-instructions.md en la carpeta .github/. El principio es idéntico en los tres: un archivo de instrucciones persistentes que el agente lee automáticamente antes de actuar. Si usas Claude Code, CLAUDE.md es el estándar.
¿Con qué frecuencia debo actualizar el CLAUDE.md?
Siempre que cambie algo relevante del proyecto: cuando migras de runtime, cuando adoptas una nueva convención, cuando añades una restricción que no estaba. En proyectos activos, una revisión mensual es suficiente para detectar instrucciones obsoletas. El indicador más claro de que el CLAUDE.md está desactualizado es que el agente empieza a proponer patrones que el equipo ya abandonó.
¿Puede un CLAUDE.md ser demasiado largo?
Sí. Un CLAUDE.md de 500 líneas con instrucciones exhaustivas sobre cada posible situación introduce dos problemas: el agente puede no aplicar instrucciones que están enterradas en el archivo, y el mantenimiento se vuelve costoso. La guía práctica: si una instrucción no ha evitado ningún error en los últimos dos meses, probablemente no necesita estar ahí. Menos, mejor — pero con precisión.
Por Bezael Pérez — Developer senior con más de 15 años de experiencia y fundador de Dominicode.