CLAUDE.md: la documentación que tu agente lee

Si tu repo no tiene un `CLAUDE.md`, en 2026 estás perdiendo horas cada semana. No porque la IA no funcione: funciona. Sino porque cada sesión empiezas desde cero explicando lo mismo. Esta guía explica qué es un `CLAUDE.md` útil, cómo estructurarlo y qué cosas NO meter (porque saturan el contexto y te tiran la calidad de las respuestas). ## Qué es CLAUDE.md Es un archivo en la raíz del proyecto (o por feature) que tu agente lee automáticamente al abrir el repo. Contiene las reglas, convenciones y prohibiciones que esperas que respete. No es un README. El README es para humanos que llegan al repo. CLAUDE.md es para el agente que va a escribir código en el repo. ## Estructura recomendada ```markdown # [Project Name] — Development Guide ## Core Stack - Lo mínimo imprescindible: framework, DB, auth, package manager ## Critical Rules (NON-NEGOTIABLE) ### 1. Directory Structure ### 2. Import Rules ### 3. Dependency Rules ### 4. Language & Code Style ### 5. No Comments Policy ### 6. No Business Logic in Page Components ## Project Structure ## Decision Tree: Where to Put New Code? ## Anti-Patterns (DO NOT DO THIS) ``` Cada sección tiene 5-15 líneas, no 5 párrafos. La idea no es enseñar; es recordar. ## Reglas que SÍ funcionan en CLAUDE.md - **Concretas y verificables**: "no `console.log`, usa `@/lib/errors/logger`". El agente puede comprobarlo. - **Con ejemplos cortos** del bien y del mal: ```ts // Wrong import { Button } from '@/shared/components/ui'; // Right import { Button } from '@/shared/components/ui/button'; ``` - **Prohibiciones explícitas** ("NEVER use npm/yarn") más fáciles de seguir que recomendaciones. ## Reglas que NO funcionan - **Filosofía abstracta**: "escribe código limpio". El agente no sabe qué es eso. - **Reglas que cambian**: si tu CLAUDE.md tiene una versión de cada librería, en 6 meses está desfasado y el agente confía. - **Documentación que duplica el README**: redundancia que no sirve para nada y consume tokens. ## CLAUDE.md por feature Además del CLAUDE.md raíz, conviene uno por feature en módulos sensibles: ``` src/features/auth/CLAUDE.md src/features/payments/CLAUDE.md src/features/blog/CLAUDE.md ``` Cada uno con: - Prohibiciones de seguridad ("NEVER trust user HTML", "ALWAYS sanitize") - Patrones específicos del módulo - Estados válidos (ej. `draft → published → archived`) - Errores comunes que ya hemos tenido Así, cuando el agente tocha `src/features/blog/`, lee también las reglas locales y no tiene que adivinar. ## Errores comunes al escribir CLAUDE.md **1. Demasiado largo**: si tu CLAUDE.md tiene 800 líneas, el agente lo procesa pero pierde prioridades. Apunta a 200-400 líneas máximo en el raíz. **2. Reglas contradictorias**: "siempre usa X" en un sitio, "evita X" en otro. Pasa cuando escribes en distintos momentos. Revísalo entero al añadir. **3. Sin "WHY" en las reglas raras**: si dices "no uses Edge runtime", explica brevemente: "Prisma no lo soporta". Sin el porqué, el agente puede saltárselo si parece que la situación es distinta. **4. Confundir `README` con `CLAUDE.md`**: el README explica qué es el proyecto. CLAUDE.md cómo trabajar dentro del proyecto. No los mezcles. ## Cómo iterar tu CLAUDE.md - **Cada vez que el agente comete el mismo error 3 veces**: la regla aún no está clara o no existe. Documéntala. - **Cada vez que tienes que repetir lo mismo en un prompt**: añádelo a CLAUDE.md. - **Cada release mayor**: revisa si las versiones, comandos o convenciones cambiaron. ## Conclusión `CLAUDE.md` es la diferencia entre un agente que "ayuda a teclear" y un agente que "trabaja en tu repo como si lo conociera de hace meses". 5 minutos al día escribiéndolo te ahorran 30 minutos al día de prompts repetidos. En un mes son horas. En seis, son una feature entera.