Cómo prevenir la degradación de CLAUDE.md: trata las reglas como código

Después de ejecutar Claude Code en proyectos de producción durante 18 meses, u/mm_cm_m_km identificó el punto de fallo más común: el archivo CLAUDE.md se pudre. No porque Claude lo ignore, sino porque los desarrolladores siguen añadiendo reglas sin limpiarlas nunca. El resultado es un archivo inflado de 500 líneas que cuesta tokens en cada turno y se desincroniza con el código base real.

1. CLAUDE.md como índice, no como manual

Mantén CLAUDE.md entre 30 y 50 líneas. Debe funcionar como una tabla de contenido que apunte a archivos específicos para temas concretos, no como un muro con todas las preferencias que hayas establecido. Claude relee el archivo en cada turno; los archivos cortos son baratos, los largos desperdician tokens y atención.

2. Cada sección responde a una de dos preguntas

• ¿Qué comportamiento deseas? (la regla) — va en CLAUDE.md.
• ¿Dónde encuentras la verdad actual? (la fuente) — va como una URL o ruta de archivo que Claude pueda releer en el momento de la tarea.

Mezclar reglas y fuentes es como los archivos crecen sin límite. Mantén la regla breve, la fuente externa.

3. Auditar antes de fusionar, no después

Las reglas se desvían silenciosamente al renombrar cosas, refactorizar hooks o eliminar funcionalidades. La solución no es "tener más cuidado" — es un paso en CI. El autor creó una aplicación de GitHub llamada agentlint (agentlint.net) que audita la superficie de reglas en cada PR: contradicciones entre archivos, referencias a rutas eliminadas, reglas que describen características de un entorno que tu versión no soporta.

4. Elimina más de lo que agregas

Casi todos los CLAUDE.md ganan una regla nueva por semana y eliminan cero. Después de seis meses tienes un Frankenstein. La disciplina: por cada regla nueva, encuentra una para eliminar. Esto ha mantenido el archivo del autor por debajo de 100 líneas.

El patrón central: trata tu superficie de reglas como código. El código tiene pruebas, revisión y detección de desviaciones. Las reglas necesitan lo mismo.