CLAUDE.md explicado:el archivo que evita errores de IA

CLAUDE.md explicado: es un archivo de texto plano en la raíz de tu proyecto que tu herramienta de programación con IA lee antes de cada respuesta, y evita alrededor del 90 % de los errores que la IA comete en tu código. No es código. Es el libro de reglas: los patrones de tu proyecto, tus innegociables, los errores que la IA nunca debe repetir.

La mayoría de quienes construyen con IA ni sabe que existe. Esto es lo que es, por qué lo cambia todo y qué poner exactamente en el tuyo.

CLAUDE.md explicado: la analogía del manual del empleado

Imagina que contratas a un colaborador brillante que sufre amnesia total entre reuniones. Cada mañana llega sin saber nada de cómo funciona tu empresa: tus estándares, tu sistema de archivo, tus decisiones pasadas. Cada mañana vuelves a explicarlo todo, y cada mañana comete los mismos errores hasta que lo haces.

Ahora imagina que le entregas un manual del empleado que relee al inicio de cada reunión. De pronto se presenta ya conociendo tus reglas.

Eso es CLAUDE.md. Las herramientas de programación con IA empiezan cada conversación desde cero: no recuerdan las correcciones de ayer. CLAUDE.md es el manual que leen automáticamente antes de responder a nada. Piensa en él como la constitución de tu código: las reglas que la IA debe seguir, los patrones que debe usar, los errores que nunca debe cometer.

Por qué la IA repite los mismos errores sin él

Esto es lo que me pasó. Estaba construyendo un sistema de revisión de solicitudes para mi plataforma: lógica de puntuación compleja, flujos de varios pasos, decenas de tablas de base de datos. Le dije a Claude: "Construye el servicio de revisión de solicitudes."

Claude generó código. Funcionaba. Y estaba mal de cinco maneras:

• Ignoraba la estructura que sigue el resto de mi código
• Inventaba definiciones de datos que no coincidían con mi base de datos real
• Añadía un manejo de errores que chocaba con el sistema que ya tenía
• Usaba salidas de depuración improvisadas en lugar de mi sistema de registro
• Olvidaba la multi-tenancy: la etiqueta del cliente que debe ir en cada consulta

Lo arreglé todo a mano. ¿Y el siguiente archivo que le pedí? Los mismos errores. Otra vez. Peleaba con Claude en cada archivo, no porque Claude sea malo, sino porque tenía amnesia sobre las reglas de mi proyecto. Sin CLAUDE.md, reentrenas a tu IA desde cero en cada conversación.

El libroThe Solopreneur RevolutionLuis Gonçalves sobre cómo crear un negocio de solopreneur con IA sin dejar tu empleo.Consigue el libro →

Qué contiene un archivo CLAUDE.md

Un buen CLAUDE.md tiene siete secciones. Ninguna exige que escribas código: exigen que expreses decisiones, que es exactamente el trabajo del arquitecto:

Las secciones más potentes son las dos últimas. La IA es una máquina de reconocer patrones: muéstrale un ejemplo real de código bien hecho y lo imitará en todas partes. Muéstrale el error exacto que cometió la semana pasada, etiquetado como "nunca hagas esto", y el error desaparece.

Qué cambió después de escribir el mío

La misma petición, "Construye el servicio de revisión de solicitudes", tras añadir CLAUDE.md. Claude leyó primero las reglas y luego generó código que seguía mi estructura, coincidía exactamente con mi base de datos, etiquetaba cada consulta para la multi-tenancy, gestionaba los errores a mi manera y ponía cada archivo en su sitio. A la primera. Cero correcciones.

El momento en que supe que era magia: necesitaba una funcionalidad de emparejamiento de mentores, con lógica compleja y varias tablas. Antes de CLAUDE.md, eso eran horas arreglando lo que generaba la IA. Después, dije "construye el emparejamiento de mentores con los mismos patrones que la revisión de solicitudes". Claude leyó el libro de reglas, estudió la funcionalidad anterior y construyó todo siguiendo cada patrón. Tardó 15 minutos y funcionó a la perfección.

Sin el archivo, calcula unos 30 minutos de arreglos por cada archivo generado: patrones erróneos, salvaguardas ausentes, archivos mal colocados. Multiplícalo por cientos de archivos y CLAUDE.md es la diferencia entre entregar y ahogarse.

Cómo empezar el tuyo hoy

No escribas una obra maestra. Empieza con cinco reglas, los cinco errores que tu IA repite en tu proyecto, más una línea que describa qué estás construyendo y tu stack tecnológico. Eso es todo.

Después trátalo como un documento vivo. Cada vez que la IA cometa un error nuevo, añade una regla. Cada vez que genere algo estupendo, copia ese código en la sección de ejemplos. El punto óptimo son 200–400 líneas: con menos de 100 hay poco contexto; con más de 500 la IA se ahoga.

Un límite que conviene conocer: CLAUDE.md contiene tus reglas globales, siempre ciertas. Para funcionalidades grandes y puntuales querrás además un briefing específico de la tarea con los requisitos y el contexto exactos de esa funcionalidad; es otra herramienta, el método PRP, y las dos trabajan juntas: constitución para el día a día, plano para cada construcción.

12 semanasTu carrera corporativa nunca fue el planSolicita plaza en el Solopreneur Accelerator.Solicitar ahora →

Preguntas frecuentes

¿Qué es un archivo CLAUDE.md?

Un archivo markdown (texto plano) en la raíz de tu proyecto que Claude Code lee antes de cada respuesta. Contiene las reglas, los patrones, el stack tecnológico, los ejemplos de código real y los antipatrones de tu proyecto, para que la IA siga tus estándares a la primera en lugar de ser reentrenada en cada conversación.

¿Necesito saber programar para escribir uno?

No. El archivo se escribe en lenguaje llano: qué es el producto, las reglas que siempre deben cumplirse, lo que nunca debe pasar. Para la sección de ejemplos, pegas código que la propia IA generó cuando acertó. Expresar las decisiones es trabajo del fundador; implementarlas es trabajo de la IA.

¿Cuánto debe medir un archivo CLAUDE.md?

Empieza hoy con cinco reglas. Hazlo crecer hacia las 200–400 líneas: lo bastante largo para llevar tus patrones, lo bastante corto para que la IA use todo. Menos de 100 líneas es poco; pasadas las 500, recorta. Revísalo cada semana: añade patrones nuevos, borra reglas obsoletas.

¿Basta CLAUDE.md por sí solo para construir funcionalidades?

Cubre las reglas globales: los errores que de otro modo se repetirían en cada archivo. Para una funcionalidad compleja quieres además una especificación de la tarea con los requisitos, los datos y los pasos de validación exactos de esa funcionalidad. Eso es el método PRP; CLAUDE.md más un PRP es como se construyen bien las funcionalidades a la primera.