English

La regla que tu agente sigue ignorando

Escribiste la regla. La pusiste cerca del inicio. Hasta la escribiste en mayúsculas. Tu agente la rompió igual, y mañana la volverá a romper. Antes de reescribir la frase por cuarta vez, considera que la redacción nunca fue el problema.

El énfasis no es un mecanismo

Cuando una instrucción se ignora, el instinto es subir el volumen: negritas, mayúsculas, un IMPORTANTE al inicio, un "DEBES". Se siente como que debería funcionar porque funciona con personas. Aquí casi nunca funciona, y vale la pena entender por qué.

Un archivo de reglas no es una imposición. Es contexto: texto que se carga en la ventana del modelo al inicio de la sesión y que compite por atención con todo lo demás. La documentación es directa al respecto: describe los archivos de reglas como contexto, no como configuración forzada, y aclara que no hay garantía de cumplimiento estricto. Darle formato más agresivo a una línea no cambia su naturaleza. Sigue siendo una línea entre los cientos que acumulaste.

Y ahí está la variable real. Si el archivo es corto, tu regla es una de treinta cosas compitiendo. Si es largo, es una de trescientas. La tasa de fallas que ves es función de esa proporción, y gritar ajusta el lado equivocado.

La meta documentada es menos de 200 líneas

Hay un número concreto al cual apuntar. La guía para archivos de reglas es mantenerse por debajo de 200 líneas por archivo, explícitamente porque los archivos más largos consumen más contexto y reducen la adherencia. Esa segunda mitad es la que casi todos pasan por alto. Todos saben que un archivo largo cuesta tokens. Pocos lo conectan con que el agente los desobedezca.

Así que el diagnóstico es simple, e invierte la reacción habitual:

• Si el agente ignora una regla claramente escrita, no reescribas la regla.
• Revisa la longitud del archivo donde vive.
• Si ese archivo pasa holgadamente las 200 líneas, la regla probablemente está bien y el archivo es el error.

Esto también explica un síntoma desconcertante: una regla funciona bien en un proyecto pequeño y se ignora en el grande, con la redacción idéntica. Misma instrucción, distinta cantidad de competencia.

Recorta, no comprimas

La solución equivocada es exprimir el mismo contenido en menos palabras. Conservas todos los temas y pierdes la claridad. La correcta es sacar temas del archivo que siempre se carga.

Deja en el archivo de reglas solo lo que cambia el comportamiento del agente en la mayoría de las tareas:

• Convenciones que de verdad aplicas: nombres, estructura, patrones
• Comandos: compilar, probar, revisar estilo, desplegar
• Trampas: eso no obvio que le pega a todos una vez

Saca lo que solo importa a veces. Existen dos mecanismos. Las reglas con alcance por ruta viven en .claude/rules/ con un campo paths: y se cargan solo cuando el agente toca archivos que coinciden, así tus convenciones de API llegan cuando abre ese directorio y no cuestan nada el resto del tiempo. Las skills van más lejos: se cargan solo al invocarlas o cuando el agente las juzga relevantes, lo que encaja mejor con procedimientos de varios pasos.

Nota: Una trampa que conviene conocer: dividir un archivo largo en importaciones @ruta parece que debería ayudar, pero los archivos importados se expanden y se cargan al inicio junto con el archivo que los referencia. Ganas orden y exactamente cero ahorro de contexto. Las reglas por ruta y las skills son los mecanismos que sí difieren la carga.

Deja que la herramienta haga el recorte

No tienes que decidir los recortes a mano. El chequeo /doctor incluye una pasada de recorte para archivos de reglas versionados, y su criterio es bueno: corta lo que el agente podría deducir del código de todos modos, como estructuras de carpetas, listas de dependencias y panoramas de arquitectura, y conserva lo que no podría deducir, que son las trampas, el porqué y las convenciones que se apartan de los valores por defecto.

Esa distinción es todo el juego. Un archivo de reglas que explica tu estructura de carpetas gasta contexto permanente en algo que el agente puede descubrir mirando. Un archivo que dice "este directorio se genera, nunca lo edites a mano" le dice algo que ninguna cantidad de lectura revelaría. Lo primero se puede borrar. Lo segundo es la razón de que el archivo exista.

/doctor también reporta qué skills, servidores y plugins te cuestan contexto sin que los uses, y muestra los hallazgos antes de cambiar nada, así que puedes correrlo sin comprometerte con sus sugerencias.

Dos fallas que parecen longitud pero no lo son

Antes de recortar, descarta dos explicaciones más baratas.

El archivo no se cargó. Corre /context y mira en la sección de archivos de memoria. Si el archivo que editas no aparece, el agente nunca lo vio y la longitud es irrelevante. Esto atrapa archivos de reglas ubicados en el directorio equivocado más seguido de lo que uno esperaría.

Dos reglas se contradicen. Si dos archivos dan indicaciones opuestas sobre el mismo comportamiento, el agente puede elegir una de forma arbitraria, y desde afuera esa elección arbitraria es indistinguible de que te ignore. Los archivos anidados en subdirectorios son una fuente común, porque es fácil olvidarlos. Revisar contradicciones vale la pena antes de concluir que el archivo solo es muy largo.

Para llevar

Una regla que nadie lee no es una regla, es decoración, y pasada cierta longitud de archivo es decoración lo que estás escribiendo. Lo que de verdad sube el cumplimiento es restar: baja de 200 líneas, empuja lo situacional a reglas por ruta y skills, y deja que /doctor proponga los cortes. Después, si una regla se sigue ignorando, por fin estarás viendo un problema de regla y no de longitud.