Usa un archivo de instrucciones para tu agente

# CLAUDE.md
- Proyecto: tienda online en Astro.
- Comandos: `npm run dev`, `npm run build`.
- Estilo: TypeScript estricto, sin dependencias nuevas sin avisar.
- No toques la carpeta /legacy.

Sin un archivo de instrucciones, cada sesión con tu agente arranca de cero: le repites cómo se llama el proyecto, qué comandos usar, qué carpetas no tocar, y aun así, en cuanto te despistas, instala una dependencia que no querías o reescribe un módulo del que no había que opinar. El problema no es el agente, es que la información que necesita vive solo en tu cabeza.

Un archivo como CLAUDE.md o AGENTS.md en la raíz del repo concentra las reglas del proyecto en un único sitio que el agente lee solo al empezar. Escribes las reglas una vez y se aplican en cada sesión, para ti y para cualquiera del equipo. Es la diferencia entre un agente que adivina tu forma de trabajar y uno que ya la conoce.

Encaja muy bien con la idea de montar tu biblioteca de prompts: el archivo de instrucciones es la “biblioteca” específica del repo, versionada con git. Si todavía no has elegido agente, mira la ficha de Claude Code o de Cursor.

Cómo aplicarlo

1. Crea el archivo en la raíz del repo. Usa CLAUDE.md si trabajas con Claude Code, AGENTS.md si tu agente lo soporta o si quieres un nombre más neutro para varias herramientas. Ahí lo busca solo, sin que tengas que apuntarlo.
2. Empieza por lo esencial. Qué es el proyecto en una frase, el stack técnico, los comandos clave (cómo levantar el entorno local, cómo correr los tests, cómo hacer el build). Si un nuevo colaborador necesitara esto para empezar, también el agente.
3. Escribe las reglas como órdenes cortas. “Usa TypeScript estricto”, “no añadas dependencias sin avisar”, “no toques /legacy”, “los commits van en español”. Frases imperativas y claras: el agente las trata como instrucciones, no como descripción.
4. Documenta decisiones, no solo estilo. Anota por qué algo es como es (“no migrar a la versión 5 porque rompe el plugin X”): así evitas que el agente “arregle” lo que en realidad es una decisión consciente.
5. Mantenlo corto y vivo. Si una regla deja de valer, bórrala. Un archivo de mil líneas que mezcla cosas obsoletas con vigentes acaba ignorándose. Uno preciso de cincuenta líneas se respeta.
6. Versiónalo con el repo. Al estar en git, el archivo evoluciona con el proyecto, queda en el historial y todo el equipo (y cada agente) trabaja con la misma versión. Cuando alguien cambia una regla, se ve en la pull request.
7. Reglas por carpeta si hace falta. Algunos agentes leen archivos de instrucciones anidados (por ejemplo, otro CLAUDE.md dentro de /api/). Útil cuando un módulo tiene convenciones distintas del resto del repo.

Ejemplos en contexto

Caso negocio. Una agencia mantiene cinco webs en Astro para clientes distintos. Cada repo tiene su CLAUDE.md con el nombre del cliente, la guía de estilo de su marca, los comandos de despliegue y la lista de plugins que no se pueden cambiar por contrato. Cuando un desarrollador salta de un repo a otro, el agente se reconfigura solo y deja de proponer cambios que romperían acuerdos con el cliente.

Caso estudio. Un estudiante está aprendiendo Python con varios proyectos en una misma carpeta. En cada uno pone un AGENTS.md con dos líneas: el nivel (“soy principiante, explícame cada cambio”) y la restricción (“no uses librerías externas, solo la librería estándar”). El agente deja de meter Pandas en un script de cuatro líneas y le explica lo que escribe, que es justo lo que el estudiante necesita.

Caso vida personal. Mantienes notas en un repo personal con Markdown. Tu CLAUDE.md dice: “Escribe siempre en castellano peninsular, sin emojis, encabezados con dos almohadillas máximo, no toques /borradores.” Cuando le pides al agente que reorganice una nota, respeta tu estilo sin que tengas que repetirlo cada vez, y el archivo borradores/ queda intacto.

Errores comunes

• Llenarlo de obviedades del lenguaje (“usa indentación”, “pon punto y coma”): ocupa atención y no aporta. Deja solo lo que es decisión del proyecto.
• Escribir las reglas como sugerencias (“estaría bien que…”): el agente las trata como blandas. Usa imperativo: “haz”, “no toques”, “evita”.
• Olvidarse de actualizarlo cuando cambia algo del proyecto: las reglas obsoletas hacen daño, porque el agente las sigue creyendo que valen.
• Meter secretos o tokens en el archivo: va a git. Los datos sensibles van en variables de entorno o en gestores de secretos, no aquí.
• Hacerlo gigantesco “por si acaso”: cuanto más largo, menos peso tiene cada regla. Si pasa de dos pantallas, divide por carpetas.
• Asumir que todos los agentes leen el mismo archivo: comprueba en la documentación de tu herramienta qué nombre busca y dónde.

Mini-ejercicio

Abre el repo en el que estés trabajando hoy y crea un CLAUDE.md o AGENTS.md con solo cinco líneas: nombre del proyecto, stack, comando para arrancarlo, comando para los tests y una regla que sabes que el agente suele saltarse. Lanza tu próxima petición y compara. Sabrás que está bien si el agente cumple esa regla sin que tengas que recordársela en el chat.

Siguiente paso

Una vez que tengas tu archivo base, échale un ojo al repositorio externo awesome-claude-code para ver ejemplos reales de CLAUDE.md en proyectos distintos. Y si quieres llevar la automatización un paso más allá, mira las skills de Claude Code para empaquetar instrucciones reutilizables entre proyectos.