Nota del editor: Para muchos usuarios de Claude Code, el mayor problema no es que el modelo sea débil, sino empezar desde cero cada vez.

Tienes que explicarle repetidamente el contexto del proyecto, el stack tecnológico, las convenciones de código, qué archivos no tocar, qué soluciones ya se probaron. Si esta información no está fijada, Claude trabajará adivinando. El resultado puede ser que modifique archivos que no debía, refactorice código que no se pidió, o incluso recomiende herramientas inadecuadas para el proyecto.

El archivo CLAUDE.md que presenta este artículo es, precisamente, un manual de instrucciones para Claude Code. Basta con colocarlo en la raíz del proyecto para que Claude lo lea automáticamente al iniciar cada sesión. Le indica de antemano a Claude: cómo responder, cómo escribir código, cuándo debe preguntar antes de actuar, qué operaciones no debe ejecutar por iniciativa propia, qué stack tecnológico usa el proyecto, y qué decisiones importantes se tomaron en el pasado.

En resumen, la función de CLAUDE.md es: reducir las explicaciones repetitivas, limitar las acciones fuera de alcance del modelo, y hacer que la programación con IA sea más estable y controlable.

Si usas Claude Code, puedes empezar con las 4 reglas que resume Karpathy: preguntar ante la duda, implementar primero la solución más simple, no tocar código irrelevante, y declarar explícitamente la incertidumbre. Introduce estas reglas en CLAUDE.md, y luego complementa el archivo gradualmente según tu proyecto. Notarás una mejora significativa en la experiencia de uso.

A continuación, el artículo original:

Un archivo llamado CLAUDE.md alcanzó el primer lugar en GitHub Trending.

8.2 mil stars, 7800 forks.

Todo comenzó con Andrej Karpathy. Exdirector de IA en Tesla y miembro fundador de OpenAI. Él resumió 4 comportamientos que hacen que Claude Code falle, y los escribió en un archivo.

Posteriormente, un desarrollador amplió estas 4 reglas y publicó el archivo. Su popularidad fue inmediata.

La razón es directa: la precisión de codificación aumentó del 65% al 94%.

Sin embargo, la mayoría de los desarrolladores que usan Claude Code a diario nunca han hecho esta configuración. Comienzan cada sesión desde cero: reexplican el mismo contexto, limpian cambios de alcance innecesarios, revierten refactorizaciones no solicitadas.

A continuación, el archivo completo.

La configuración que la mayoría de los desarrolladores se pierde

Cada vez que abres Claude Code, por defecto no sabe nada.

No conoce tu stack tecnológico, tus convenciones de código, el contexto de tu proyecto, lo que ya has intentado, ni las decisiones que tomaste explícitamente tres sesiones atrás.

Así que solo puede adivinar. Y una vez que empieza a adivinar, puede refactorizar código que no le pediste modificar, recomendar frameworks que romperían la arquitectura existente, eliminar archivos sin confirmación, o incluso revertir decisiones que ya habías tomado.

CLAUDE.md es un archivo de texto plano ubicado en la raíz del proyecto. Claude Code lo leerá automáticamente al inicio de cada sesión.

Una configuración única, sin explicaciones repetitivas, que corrige tres tipos de errores costosos.

Configuración por defecto: gastas 375 dólares semanales solo en repetirte

Un desarrollador promedio dedica unos 30 minutos diarios a reexplicar el contexto a Claude.

Stack tecnológico, convenciones de código, contexto del proyecto, métodos ya probados—a menos que escribas esta información de una vez y hagas que Claude la lea automáticamente cada vez, no se conservará entre sesiones.

Calculando un salario por hora de 150 dólares para el desarrollador:

· 30 minutos diarios = 75 dólares;

· Semanalmente = 375 dólares.

· Para un equipo de 5 personas = 1875 dólares de coste oculto semanal.

Las siguientes 7 reglas deben ir al principio del archivo CLAUDE.md.

→ Elimina las frases vacías

No empieces las respuestas con "Buena pregunta", "Claro que sí", "No hay problema" o preámbulos similares. Da la respuesta directamente. Sin saludos, sin reformular la pregunta.

→ Adapta la longitud de la respuesta a la tarea

La longitud de la respuesta debe coincidir con la complejidad de la tarea. Para preguntas simples, respuestas directas y breves; para tareas complejas, explicaciones completas y detalladas. No rellenes espacio con frases de conclusión que repitan la pregunta o el resultado.

→ Plantea antes de actuar

Antes de comenzar cualquier tarea importante, propón 2-3 caminos viables. Espera a que elija uno antes de continuar con la ejecución.

→ Ante la incertidumbre, admítelo antes de causar daño

Si no estás seguro de algún hecho, dato, fecha o información técnica, decláralo explícitamente antes de citarla. No rellenes huecos de conocimiento con información aparentemente razonable. Si no lo sabes, simplemente di que no estás seguro.

→ Quién soy yo, qué sé yo

Sobre mí: [Nombre] / Rol: [Tu rol] / Antecedentes: [Área].

Soy experto en: [Lo que dominas].

Aún estoy aprendiendo: [Lagunas de conocimiento].

Adapta la profundidad de cada respuesta según esta información. No expliques en exceso lo que ya sé, ni omitas el contexto que necesito.

→ Contexto del proyecto actual

Estoy trabajando en: [Nombre del proyecto] / Objetivo: [Resultado concreto] / Audiencia: [Quién lo usará] / Contexto del stack tecnológico: [Restricciones relevantes] / Qué evitar: [Lista].

Aplica este contexto a cada tarea. Si algún requerimiento no coincide con el contexto, señálalo antes de ejecutar.

→ Define tu estilo de expresión

Mi estilo de escritura es: [Describe tu estilo de expresión].

Longitud de las oraciones: [Preferencia].

Palabras que uso comúnmente: [Ejemplo].

Palabras que nunca uso: [Ejemplo].

Formato: [Prosa o estructurado].

Cuando escribas cualquier contenido en mi nombre, debes ajustarte estrictamente a este estilo. No uses tu modo de expresión por defecto.

Tiempo diario de reexplicar contexto: 30 minutos

Calculando salario por hora de 150 dólares: 75 dólares / día

Semanalmente: 375 dólares por desarrollador

Equipo de 5 personas: 1875 dólares semanales

Tiempo de configuración de esta sección de CLAUDE.md: 45 minutos en total

Error a evitar: No escribas CLAUDE.md desde cero. Usa primero este prompt y luego edita el resultado:

Basándote en lo que te he contado sobre mí, mi proyecto y cómo quiero que trabajes, escríbeme un archivo CLAUDE.md completo. Incluye: quién soy, mi experiencia técnica, mis preferencias de comunicación y los comportamientos por defecto que deben seguirse en cada sesión. Sé específico, texto plano, menos de 500 palabras.

Restricciones de comportamiento: Esos cambios de "150 dólares la hora" que no autorizaste

Le pides a Claude que arregle una función.

Resultado: refactoriza tres archivos, renombra variables, reorganiza los imports y reescribe los comentarios que te tomó tiempo escribir.

Y todo esto sin tu confirmación.

Revisar y revertir estos cambios innecesarios puede tomar 1 hora, es decir, 150 dólares. Si ocurre tres veces por semana, son 450 dólares. Para un equipo de 5 personas, son 2250 dólares semanales solo para limpiar cambios no autorizados.

Las siguientes 7 reglas deben ir en la sección de restricciones de comportamiento de CLAUDE.md.

→ Control estricto del alcance

Modifica solo los archivos, funciones y líneas de código directamente relacionados con la tarea actual. No refactorices, renombres, reestructures, reformatees ni "optimices" nada que no te haya pedido modificar explícitamente.

Si encuentras algo más que merezca una corrección, menciónalo al final en una nota. No lo toques. Nunca.

→ Preguntar antes de cambios importantes

Antes de realizar cambios significativos en contenido que ya he creado—incluyendo reescribir secciones, eliminar párrafos, refactorizar estructuras, cambiar el tono—debes detenerte, explicar exactamente qué planeas cambiar y por qué. Espera mi confirmación para continuar.

→ Confirmación obligatoria antes de cualquier operación destructiva

Antes de eliminar cualquier archivo, sobrescribir código existente, borrar registros de base de datos o eliminar dependencias, debes detenerte, listar qué se vería afectado específicamente y pedirme una confirmación explícita. Solo si en el mensaje actual digo "sí", puedes continuar.

"Lo mencionaste antes" no cuenta como confirmación.

→ Pausa obligatoria para operaciones en entorno de producción

Las siguientes operaciones requieren confirmación explícita en la sesión actual, sin excepciones:

· Desplegar o hacer push a cualquier entorno;

· Ejecutar migraciones o cambios en la estructura de la base de datos;

· Enviar cualquier llamada a API externa;

· Ejecutar cualquier comando con efectos secundarios irreversibles.

· Debo decir explícitamente "sí" en el mensaje actual.

→ Siempre muestra qué cambiaste

Al finalizar cualquier tarea de codificación, el mensaje debe incluir:

Archivos modificados: lista de todos los archivos tocados;

Qué se modificó: una frase por archivo;

Archivos intencionalmente no modificados;

Temas pendientes para después.

→ Sin confirmación explícita, no actúes en mi nombre

Sin una confirmación explícita mía en el mensaje actual, no envíes, publiques, compartas o programes nada en mi nombre. Esto incluye correos, invitaciones de calendario, compartir documentos o cualquier acción fuera de esta conversación. Debo decir explícitamente "sí" en el mensaje actual.

→ Piensa antes de escribir código

Para tareas que involucren decisiones de arquitectura, depuración de problemas complejos o desarrollo de funciones no simples, analiza el problema paso a paso antes de escribir código. Muestra tu proceso de razonamiento, señala las incertidumbres y luego ejecuta.

Revertir cambios de alcance innecesarios semanalmente: 150 dólares

Revisiones manuales de diff semanales: 75 dólares

Desperdicio relacionado con el comportamiento por desarrollador: 225 dólares / semana

Equipo de 5 personas: 1125 dólares / semana

Tiempo de configuración de la sección de comportamiento en CLAUDE.md: 30 minutos

Memoria y stack tecnológico: La configuración que hace a Claude Code realmente fiable

Claude olvida todo entre sesiones.

Cada decisión que tomaste, cada enfoque que falló, por qué elegiste Prisma en lugar de Drizzle hace seis meses, y por qué cierta restricción viene de un requerimiento de un cliente específico—todo lo olvida.

Luego, vuelve a sugerir enfoques que ya descartaste.

Esta sección equivale a proporcionar a Claude el mecanismo más cercano a una "memoria real" disponible, y a la vez fijar tu stack tecnológico para evitar que siga recomendando herramientas que romperían la arquitectura existente.

→ Bitácora de decisiones en MEMORY.md

Mantén un archivo llamado MEMORY.md en el proyecto. Tras cada decisión importante, añade una entrada:

· Qué se decidió;

· Por qué se tomó esa decisión;

· Qué se descartó y por qué.

Al inicio de cada sesión, lee primero MEMORY.md. Sin recordatorio, no propongas nada que entre en conflicto con decisiones ya registradas.

→ Resumen al final de la sesión

Cuando diga "fin de sesión", "terminemos aquí" o similar, escribe un resumen de la sesión en MEMORY.md, incluyendo:

· Qué se trató en esta sesión;

· Qué se completó;

· Qué sigue en progreso;

· Qué decisiones se tomaron;

· Prioridades para la próxima sesión.

→ Bitácora de fallos en ERRORS.md

Mantén un archivo llamado ERRORS.md. Cuando un enfoque se intente más de dos veces sin éxito, regístralo:

· Qué no funcionó;

· Qué enfoque finalmente funcionó;

· En qué fijarse la próxima vez.

Antes de proponer un enfoque para una tarea similar, revisa ERRORS.md.

→ Lista de hechos permanentes

Los siguientes hechos son siempre ciertos para este proyecto y deben aplicarse sin excepción en cada sesión:

[Tus restricciones permanentes, decisiones de arquitectura y reglas]

Si alguna tarea entra en conflicto con estos hechos, señálalo antes de ejecutar.

→ Bloquea el stack tecnológico

El stack tecnológico de este proyecto es el siguiente. Usa siempre estas herramientas. A menos que lo pida explícitamente, no recomiendes alternativas:

Lenguaje: [Ej: TypeScript]

Framework: [Ej: Next.js 14]

Gestor de paquetes: [Ej: pnpm]

Base de datos: [Ej: PostgreSQL con Prisma]

Pruebas: [Ej: Vitest]

Estilos: [Ej: Tailwind CSS]

Si una herramienta parece inadecuada, puedes señalarlo. Pero, a menos que yo lo especifique, debes usar el stack tecnológico ya definido.

→ Activa el pensamiento extendido para decisiones difíciles

Para problemas que involucren arquitectura de sistemas, compromisos de rendimiento, diseño de bases de datos o decisiones técnicas a largo plazo, usa el modo de pensamiento extendido.

Analiza el problema paso a paso, señala compromisos que quizá no haya considerado, indica suposiciones que podrían no sostenerse al escalar, y luego da tu recomendación.

→ Las 4 reglas virales

Karpathy resumió 4 comportamientos que hacen que Claude Code falle. Un desarrollador los condensó en estas 4 líneas. La precisión de codificación pasó del 65% al 94%.

Pregunta, no asumas.
Si algo no está claro, pregunta antes de escribir la primera línea de código. No hagas suposiciones silenciosas sobre la intención, la arquitectura o los requerimientos.

Implementa primero la solución más simple.
Siempre implementa primero la solución más simple que funcione. No añadas capas de abstracción o flexibilidad no solicitadas explícitamente.

No toques código irrelevante.
Si un archivo o función no está directamente relacionado con la tarea actual, no lo modifiques. Incluso si piensas que podría optimizarse, no lo toques.

Marca claramente la incertidumbre.
Si no estás seguro de un enfoque o detalle técnico, decláralo antes de continuar. Actuar con confianza sin certeza causa más daño que admitir una laguna de conocimiento.

· Coste semanal de recuperación por decisiones olvidadas y sugerencias erróneas: 300 dólares por desarrollador

· Recomendaciones de stack tecnológico equivocado y herramientas incompatibles: 75 dólares semanales

· Desperdicio relacionado con la memoria por desarrollador: 375 dólares / semana

· Equipo de 5 personas: 1875 dólares / semana

· Tiempo de configuración de MEMORY.md + ERRORS.md + stack tecnológico: 20 minutos

Conclusión

El balance de costes completo es:

· Reexplicar contexto semanalmente: 375 dólares

· Revertir cambios no autorizados semanalmente: 225 dólares

· Gestionar problemas por decisiones olvidadas semanalmente: 375 dólares

· Desperdicio total semanal por desarrollador: 975 dólares.

Para un equipo de desarrollo de 5 personas: 4875 dólares semanales. 253,500 dólares anuales.

Configurar CLAUDE.md toma solo 2 horas en total.

Las 4 reglas de Karpathy por sí solas aumentaron la precisión de codificación del 65% al 94%.

Un archivo de texto plano, 21 reglas, dos horas de trabajo.

Los desarrolladores que completan esta configuración están usando, en efecto, un Claude más fiable: recuerda decisiones, controla el alcance de las tareas, pide confirmación antes de operaciones destructivas y no recomienda frameworks que rompan la arquitectura existente.

Y quienes aún no lo configuran siguen gastando 975 dólares semanales en repetirse.

Nota final: Empieza con las 4 reglas de Karpathy. Solo con esas 4. Pégualas ahora mismo en un nuevo archivo llamado CLAUDE.md en la raíz de tu proyecto. Solo te tomará 2 minutos. Luego, cada semana, complementa gradualmente según los vacíos que descubras.

Guárdalo antes de que lo entierre el flujo de información. Si te resulta útil, compártelo con alguien que realmente lo necesite.