CLAUDE.md
Fichero markdown en la raíz del proyecto que da a Claude instrucciones, convenciones y restricciones a nivel de proyecto.
CLAUDE.md es a Claude lo que README.md es a los humanos, pero optimizado para un lector LLM. Claude Code lo lee automáticamente al arrancar la sesión; todo lo que esté dentro pasa a formar parte del system prompt para ese proyecto. Sin él, Claude tiene que reinferir tus convenciones cada sesión, lo que gasta tokens y produce resultados inconsistentes.
Qué meter en un CLAUDE.md excelente: resumen del stack (frameworks, librerías clave), convenciones (naming, testing, manejo de errores), tour de estructura de ficheros, anti-patrones a evitar, env vars, particularidades de deploy y una lista de skills/agentes/MCP servers configurados para este repo. Sé directo, conciso y explícito con las restricciones. Mantenlo bajo 500 líneas, Claude lo lee cada sesión y los ficheros largos erosionan su presupuesto de atención.
Trata el CLAUDE.md como código: revísalo en cada PR, actualízalo cuando añadas una convención nueva, elimina secciones cuando quites una librería. Un CLAUDE.md desactualizado confunde activamente a Claude.