CLAUDE.md: el archivo que hace mejores a los agentes de código

Un buen CLAUDE.md no hace más inteligente al modelo. Hace menos ambigua la tarea cada vez que el agente entra en tu repositorio.

Este mecanismo modesto explica por qué un repositorio construido alrededor de cuatro reglas codificadas en lenguaje simple se convirtió en uno de los proyectos de agentes más visibles de 2026. Las instrucciones le dicen al agente que exponga supuestos, prefiera implementaciones simples, mantenga los cambios quirúrgicos y defina éxito verificable. Ninguno es software engineering novedoso. Poner los cuatro en contexto antes de cada tarea es la parte útil.

El titular viral dijo que un archivo alcanzó 91,000 estrellas en GitHub. Para el 2 de agosto de 2026, el repositorio se había movido de forrestchang a multica-ai, crecido en plugins y reglas del editor, y alcanzado 198,529 estrellas según la API de GitHub.^[1] El número seguirá cambiando. La lección duradera es cómo las instrucciones pequeñas y persistentes cambian el comportamiento del agente.

TL;DR

• CLAUDE.md es un archivo Markdown que contiene instrucciones persistentes que Claude Code carga como contexto.^[2]
• El repositorio viral condensó fallos comunes de agentes en cuatro reglas: piensa antes de codificar, simplicidad primero, cambios quirúrgicos y ejecución orientada a objetivos.^[3]
• El archivo funciona mejor cuando contiene hechos y reglas necesarias en casi toda sesión: comandos, arquitectura, convenciones, límites y verificación.
• CLAUDE.md es contexto, no cumplimiento. Usa permisos u hooks para acciones que deben estar técnicamente bloqueadas.^[2]
• Mantén procedimientos específicos de tarea en skills y orientación específica de archivo en .claude/rules/; cargar todo globalmente desperdicia contexto.
• Un archivo útil es lo suficientemente corto para mantener, lo suficientemente específico para probar y revisado cada vez que el agente repite un error.

¿Qué es CLAUDE.md?

CLAUDE.md es el archivo de instrucciones de proyecto de Claude Code. Es Markdown ordinario, generalmente confirmado en la raíz del repositorio, que proporciona al agente contexto duradero como:

• cómo instalar, probar, compilar y formatear el proyecto;
• las partes de la arquitectura que no son obvias en los nombres de archivo;
• convenciones de nombres y estilo de código;
• qué archivos generados no deben editarse manualmente;
• qué verificaciones deben pasar antes de que una tarea sea completa;
• límites de seguridad específicos del repositorio.

Claude Code lee el archivo al principio de una sesión. Anthropic lo describe como uno de dos mecanismos de memoria: las personas escriben instrucciones en CLAUDE.md, mientras que la memoria automática de Claude almacena patrones que aprende de correcciones.^[2]

Suena como configuración, pero Anthropic hace una distinción importante. Estas instrucciones entran en el contexto del modelo; no son controles duros. Si "nunca desplegar producción" debe estar garantizado, un hook PreToolUse o un límite de permiso es la capa apropiada. Una oración en Markdown puede guiar el comportamiento. No puede proporcionar una garantía de seguridad.

Por qué el archivo de cuatro reglas se volvió viral

El repositorio ahora llamado multica-ai/andrej-karpathy-skills dice que sus directrices se derivaron de las observaciones públicas de Andrej Karpathy sobre modos de fallo de modelos de código.^[3] Su popularidad es fácil de exagerar. Cada regla mapea una frustración familiar a un comportamiento que el agente puede realizar.

Estas reglas no enseñan TypeScript, diseño de bases de datos o depuración. Forman cómo el modelo aborda la incertidumbre y el alcance. Eso las hace reutilizables en repositorios.

La simplicidad también es social. Un equipo puede leer cuatro principios en dos minutos, estar en desacuerdo con uno, editarlo y revisar el cambio en Git. No hay plataforma de prompt oculta que administrar.

Los cuatro principios, traducidos al comportamiento del proyecto

1. Piensa antes de codificar

La directriz original pide al agente que exponga supuestos, presente múltiples interpretaciones cuando sea necesario, cuestione la complejidad innecesaria y se detenga cuando esté genuinamente confundido.^[3]

La redacción específica del proyecto lo fortalece:

Antes de cambiar un contrato de API, identifica todos los consumidores en el repositorio y establece
si el cambio es compatible con versiones anteriores. Si el comportamiento del producto es ambiguo,
detente y pregunta; no elijas un comportamiento silenciosamente.

El principio genérico establece postura. La adición concreta le dice al agente dónde los supuestos incorrectos son costosos.

2. Simplicidad primero

"No sobreenginierice" es direccionalmente útil pero difícil de verificar. Añade la definición local de simple del repositorio:

Prefiere una utilidad existente sobre una nueva abstracción. No introduzcas un servicio,
factory o flag de configuración para una única ubicación de llamada. Implementa solo el comportamiento solicitado;
enumera seguimientos opcionales en lugar de construirlos.

Esto reduce una tendencia predecible del modelo: resolver una familia hipotética de problemas futuros en lugar del actual.

3. Cambios quirúrgicos

Los agentes ven oportunidades de limpieza cercanas porque leen ampliamente. Eso no significa que una tarea autorice toda limpieza.

Cada línea cambiada debe rastrearse hasta la solicitud. Preserva el formato y nombre circundantes.
Elimina importaciones inutilizadas por tu edición, pero reporta código muerto no relacionado en lugar de eliminarlo.

Los diffs pequeños son más fáciles de revisar, probar, revertir y asignar. También reducen la posibilidad de que un agente rompa algo cuyo propósito no entendió.

4. Ejecución orientada a objetivos

Una instrucción como "hazlo funcionar" deja el estado final indefinido. Traduce la tarea en un resultado que el agente puede verificar:

Para correcciones de errores, reproduce el fallo con una prueba antes de cambiar el código de producción.
Ejecuta las verificaciones más estrechas relevantes durante la iteración y las verificaciones requeridas del proyecto antes de la finalización. Reporta comandos y resultados.

Aquí es donde la autonomía se vuelve útil. Cuando el éxito es observable, el agente puede iterar sobre fallos en lugar de detenerse después de la primera edición plausible.

Qué pertenece en CLAUDE.md

Anthropic recomienda mantener hechos en CLAUDE.md que Claude debe retener en cada sesión, y mover procedimientos de múltiples pasos o estrechos a mecanismos más dirigidos.^[2] Una prueba útil es: "¿Repetiría esto durante la incorporación para casi toda tarea?"

Pon estos en el archivo raíz

• descripción de proyecto y arquitectura de un párrafo;
• gestor de paquetes y comandos canónicos de instalar, dev, test, type-check y build;
• propiedad de directorio y límites de archivos generados;
• reglas que aplican en lenguajes o paquetes;
• definición de hecho;
• errores de alta frecuencia y su corrección;
• dónde encontrar instrucciones más profundas.

Pon estos en otro lugar

Una plantilla CLAUDE.md concisa

Cópiala como punto de partida, luego reemplaza cada elemento entre corchetes. Elimina secciones que no constriñan tu proyecto.

# Instrucciones de proyecto

## Proyecto

[Un párrafo: qué envía este repositorio, su tiempo de ejecución principal y el límite
arquitectónico más importante.]

## Comandos

- Instalar: `[comando]`
- Desarrollar: `[comando]`
- Prueba enfocada: `[comando con archivo o patrón]`
- Prueba completa: `[comando]`
- Verificación de tipo: `[comando]`
- Compilar: `[comando]`

## Antes de editar

- Lee la implementación existente más cercana y pruebas antes de proponer un cambio.
- Expón supuestos que afecten el comportamiento público, datos, seguridad o compatibilidad.
- Si la solicitud tiene múltiples interpretaciones materialmente diferentes, pregunta.

## Alcance

- Implementa solo el comportamiento solicitado.
- Prefiere patrones y utilidades existentes sobre nuevas abstracciones.
- Mantén diffs quirúrgicos; no refactoricez código adyacente a menos que sea necesario.
- Elimina solo código muerto creado por tu cambio.

## Límites del proyecto

- `[ruta]` se genera; cambia `[ruta de fuente o comando]` en su lugar.
- `[paquete]` posee `[responsabilidad]`; no lo dupliques en `[otro paquete]`.
- Nunca expongas `[categoría de datos secretos o privados]` en logs o fixtures.

## Estilo

- [Dos a cinco reglas que difieren de los defaults del formateador o son fáciles de perder.]
- Coincide con el archivo circundante cuando no hay regla explícita.

## Verificación

- Para una corrección de error, añade o actualiza una prueba que falle antes de la corrección.
- Durante la iteración, ejecuta la verificación más estrechamente relevante.
- Antes de completar, ejecuta: `[comandos requeridos]`.
- Reporta archivos cambiados, comandos ejecutados, resultados y cualquier riesgo no verificado.

## Instrucciones más profundas

- Trabajo de API: `.claude/rules/api.md`
- Cambios de base de datos: `[ruta de skill o documentación]`
- Lanzamientos: `[ruta de skill o documentación]`

La plantilla es intencionalmente simple. Un CLAUDE.md no debería leerse como un manifiesto motivacional. Debería reducir decisiones que el agente tendría que adivinar de otro modo.

Cómo Claude Code carga múltiples archivos de instrucciones

Claude Code camina hacia arriba el árbol de directorios desde el directorio de trabajo actual y carga los archivos CLAUDE.md y CLAUDE.local.md que encuentra. Las instrucciones más cercanas al directorio de lanzamiento aparecen más tarde en contexto. Los archivos anidados debajo del directorio de trabajo se cargan cuando Claude lee archivos en esos subdirectorios.^[2]

Para un monorepo, eso permite una jerarquía útil:

repo/
├── CLAUDE.md                 # Hechos de proyecto amplios de la organización
├── .claude/
│   └── rules/
│       ├── testing.md        # Regla compartida sin alcance
│       └── api.md            # paths: packages/api/**
├── packages/
│   ├── web/
│   │   └── CLAUDE.md         # Arquitectura y verificaciones específicas de web
│   └── worker/
│       └── CLAUDE.md         # Restricciones de tiempo de ejecución de worker
└── CLAUDE.local.md           # Notas locales solo para desarrollador

Los archivos se concatenan como contexto en lugar de comportarse como un override estricto de configuración. Las reglas contradictorias pueden, por lo tanto, producir comportamiento inconsistente. Revisa la jerarquía periódicamente y elimina instrucciones obsoletas.

Cómo mejorar el archivo a partir de fallos reales

No intentes predecir cada posible error el primer día. Comienza pequeño y usa la fricción repetida como tu backlog.

1. Registra el fallo. ¿Qué hizo el agente y qué esperabas?
2. Encuentra la capa correcta. ¿Es esto una instrucción universal, regla específica de ruta, procedimiento de tarea o control de seguridad duro?
3. Escribe una regla observable. Reemplaza "sé cuidadoso" con la acción y condición.
4. Pruébalo en una tarea similar. Confirma que el comportamiento mejora sin bloquear trabajo trivial.
5. Elimina reglas obsoletas. El contexto tiene un costo; una instrucción anticuada puede ser peor que ninguna instrucción.

El activador práctico de Anthropic es memorable: añade algo cuando Claude comete el mismo error una segunda vez, cuando la revisión de código detecta conocimiento que el agente debería haber tenido, o cuando repites la misma corrección en todas las sesiones.^[2]

Cinco errores de CLAUDE.md a evitar

Escribir aspiraciones en lugar de instrucciones

"Escribe código excelente y robusto" no da información nueva. "Ejecuta pnpm test --filter api después de cambios bajo packages/api" puede seguirse y verificarse.

Copiar un rulebook genérico gigante

Una plantilla pública puede proporcionar ideas, pero cada línea incondicional consume contexto y puede entrar en conflicto con el proyecto. Mantén los cuatro principios de comportamiento generales si ayudan; reemplaza consejo de tecnología genérico con hechos locales.

Codificar hechos que el agente puede descubrir barato

Raramente necesitas listar cada directorio. Explica límites que los nombres de archivo no revelan, como qué paquete posee autorización o qué fuente genera un cliente verificado.

Tratar instrucciones como controles de seguridad

Nunca confíes en "no leas secretos" o "no despliegues" como la única protección. Usa credenciales con alcance, permisos, sandboxing y hooks para límites duros.

Nunca revisar el archivo

Los comandos cambian, los paquetes se mueven y las excepciones antiguas se vuelven comportamiento predeterminado. Asigna propiedad y revisa CLAUDE.md como código.

Cómo saber si funciona

Evita juzgar el archivo por si una demostración se ve impresionante. Mide el trabajo que el equipo ya revisa:

• líneas promedio cambiadas por tarea completada;
• archivos no relacionados tocados;
• comentarios de revisión causados por violaciones de convención del repositorio;
• éxito de prueba de primer pase;
• tareas reabiertos después de una finalización reclamada;
• aclaraciones repetidas que deberían convertirse en contexto persistente.

El repositorio viral sugiere las mismas pruebas a nivel de resultado: menos cambios de diff innecesarios, menos reescrituras causadas por sobrecomplicación y aclaración antes de implementación en lugar de después de errores.^[3]

FAQ

¿Dónde debe ir CLAUDE.md?

Para instrucciones de proyecto compartidas por equipo, colócalo en ./CLAUDE.md o ./.claude/CLAUDE.md y confírmalo. Usa ~/.claude/CLAUDE.md para instrucciones personales en todos los proyectos y CLAUDE.local.md para notas personales en un proyecto.^[2]

¿CLAUDE.md funciona con Cursor u otros agentes de código?

CLAUDE.md es una convención de Claude Code. El repositorio viral también envía reglas de Cursor y un plugin, mientras que otros agentes pueden usar archivos como AGENTS.md o directorios de reglas específicos del producto. Mantén una fuente canónica y adáptala deliberadamente en lugar de asumir que cada herramienta carga el mismo archivo.

¿Cuánto tiempo debería tener CLAUDE.md?

No hay conteo de línea universal. Debería contener solo información valiosa en casi cada sesión. Si una sección aplica a un directorio o un flujo de trabajo, muévela a una regla con alcance de ruta o skill.

¿Puede CLAUDE.md detener comandos destructivos?

Puede instruir a Claude que no los ejecute, pero Anthropic describe explícitamente el archivo como contexto en lugar de configuración de cumplimiento. Usa permisos u hooks para prevención confiable.^[2]

¿Cómo creo el primer archivo?

Ejecuta /init en Claude Code para generar un CLAUDE.md inicial, o crea el archivo Markdown manualmente. Luego ejecuta /context para confirmar que se cargó y /memory para inspeccionar o editar archivos de memoria.^[4]

El archivo es simple porque el problema es repetitivo

Los agentes de código no necesitan una constitución de 500 líneas antes de poder arreglar un error. Necesitan algunos hechos de proyecto que no pueden inferir, un límite claro alrededor del cambio solicitado y una verificación que distinga finalización de confianza.

Por eso cuatro reglas ordinarias llegaron tan lejos. Aborden errores que los desarrolladores ven todos los días, viven en un formato que todo el equipo puede editar y se cargan antes de que el agente comience a tomar decisiones. Comienza allí. Añade conocimiento de proyecto solo cuando previene un fallo real, e implementa límites críticos fuera del prompt.

Si eres nuevo en la herramienta en sí, comienza con la guía más amplia para usar Claude Code. Usa este artículo cuando la instalación esté terminada y la siguiente pregunta sea qué debería saber tu agente cada vez que entra en el repositorio.

References

1. GitHub REST API. multica-ai/andrej-karpathy-skills repository metadata. Retrieved August 2, 2026. api.github.com
2. Anthropic. How Claude remembers your project. Claude Code Docs. Retrieved August 2026. code.claude.com
3. multica-ai. Karpathy-Inspired Claude Code Guidelines. GitHub. Retrieved August 2026. github.com
4. Anthropic. Claude Code commands. Retrieved August 2026. code.claude.com
5. Sumit Pandey. A Single CLAUDE.md File Went Viral. The Reason Is Embarrassingly Simple. Towards Deep Learning, May 2026. towardsdeeplearning.com

Further reading

• reAPI. How to use Claude Code. reapi.ai/blog/how-to-use-claude-code
• reAPI. How to get a Claude API key. reapi.ai/blog/how-to-get-claude-api-key
• reAPI. Claude model catalog. reapi.ai/models