El mes pasado me pasé cuarenta minutos depurando por qué un agente insistía en meter los endpoints nuevos en una carpeta que abandonamos hace dos refactors. El código estaba bien. Los tests estaban bien. El agente hacía justo lo que le mandaban, porque la instrucción seguía ahí en el fichero de reglas, y el fichero de reglas estaba mal.
Eso es lo que nadie te avisa. Una regla obsoleta no da error. Una dependencia borrada da error. Una función renombrada da error. Pero una línea en CLAUDE.md que dice “registra siempre los handlers en routes/legacy.js” funciona perfectamente hasta el momento en que produce un resultado seguro, bien formado y completamente equivocado. El agente se fía del fichero. Tú escribiste el fichero. Así que te fías del output. Así se propaga una mentira con una marca verde.
Por qué las reglas se pudren más rápido de lo que crees
Hay una frase vieja, la invalidación de caché y nombrar cosas, que Martin Fowler recoge entre las dos cosas difíciles de la informática. Un fichero de reglas es una caché. Es una foto cacheada de cómo funcionaba tu repo el día en que escribiste cada línea, y como toda caché, no tiene ni idea de cuándo cambió lo que hay debajo.
El código tiene una función forzadora que lo mantiene al día: se ejecuta, y si está mal, peta. El fichero de reglas no tiene ninguna. Nadie ejecuta CLAUDE.md. Ningún test falla cuando una regla deja de ser verdad. Deriva en silencio mientras estás ocupado entregando, y cada agente que lo lee hereda la deriva con plena confianza. Cuanto mejor siguen tus agentes las instrucciones, más daño hace una instrucción equivocada, porque no la van a cuestionar.
Y estos ficheros se pudren más rápido de lo que jamás se pudrió la documentación, por una razón simple: los agentes mueven el código más rápido de lo que tú actualizas la prosa sobre él. Fusionas seis cambios escritos por agentes en una mañana. Actualizas el fichero de reglas una vez por semana como mucho. El hueco entre lo que hace el repo y lo que afirma el fichero se ensancha cada día que no lo miras.
el código
- se ejecuta
- peta cuando está mal
- se mantiene veraz
el fichero de reglas
- nunca se ejecuta
- sin error cuando está mal
- deriva en silencio
Las tres formas en que una regla se vuelve mentira
No todas las reglas obsoletas son iguales, y necesitan detección distinta.
La referencia colgante. La regla apunta a un fichero, carpeta, script o comando que ya no existe o que renombraste. “Corre ./scripts/deploy.sh” después de pasarte a un Makefile. Estas son las fáciles, porque son comprobables de forma mecánica. Si una regla nombra una ruta, la ruta debería resolver.
La convención abandonada. La regla describe cómo hacías algo antes. “Usamos componentes de clase.” “El estado va en Redux.” Sigue siendo gramaticalmente válida, sigue obedeciéndola el agente dócil, y está completamente a contramano de los últimos treinta merges. Estas son las peligrosas, porque nada en la regla parece roto. Solo el código la contradice.
La decisión que se revirtió. La más fea. “Nunca añadas un índice de base de datos sin revisión” tenía sentido cuando una persona era dueña del esquema. Ahora es un cuello de botella, y el equipo dejó de aplicarlo en silencio, pero nadie borró la línea. El agente aplica una política que los humanos ya abandonaron. Esta es la razón por la que las decisiones no deberían vivir en ficheros de reglas, que es el argumento de dónde deberían vivir tus decisiones.
Cómo detectar la deriva antes de que te cueste
No puedes corregir un fichero de reglas a ojo. Necesitas comprobaciones baratas y repetibles.
Empieza por la capa mecánica. Toda ruta, nombre de fichero y comando del fichero debería resolver contra el repo actual. Esto es un script que puedes correr en CI: haz grep en el fichero de reglas de cualquier cosa que parezca una ruta o un comando, y falla el build si no existe. Pilla toda la clase de referencias colgantes por casi nada de esfuerzo, y convierte “el fichero de reglas está mal” de una sorpresa de depuración en una pipeline en rojo.
Para las convenciones, la comprobación es distinta: usa a los propios agentes. De vez en cuando, dale a un agente el fichero de reglas y el código actual y hazle una pregunta estrecha. “¿Cuál de estas instrucciones contradice el código de verdad?” No “mejora mis reglas”, que produce slop, sino una auditoría concreta contra evidencia. El agente leyendo en fresco pillará la regla de componentes de clase contra un código lleno de hooks más rápido que tú, porque tú dejaste de ver esa línea hace meses. Esto es verificación apuntada a las instrucciones en vez de al output, y pertenece a la misma familia que todo lo de context engineering para agentes de código: el fichero que lee el agente es contexto, y un contexto que miente es peor que un contexto que falta.
Para las decisiones revertidas, ningún script ayuda, porque el código y la regla pueden ser los dos internamente coherentes mientras el motivo está muerto. La única detección real es la procedencia: una regla que no puedes rastrear hasta una decisión con fecha y motivo es una regla en la que no puedes confiar. Si no sabes por qué está ahí una línea, no puedes saber si debería seguir estando.
Mantenerlas vivas sin un segundo trabajo
El objetivo no es un fichero de reglas perfecto. Es un fichero de reglas que falle a gritos en vez de mentir en silencio. Unos pocos hábitos te llevan casi todo el camino:
- Pon fecha a las reglas que sostienen el edificio. Un motivo de una línea y una fecha al lado de una restricción real. Cuando alguien la encuentre después, distinguirá una decisión viva de un fósil.
- Mete la comprobación mecánica en la pipeline. Las rutas rotas y los comandos muertos deberían fallar en CI, no aparecer a las 2 de la mañana cuando un agente los sigue contra un muro. Ese modo de fallo conecta directo con la recuperación como flujo de primera clase, porque una regla obsoleta es una de las formas más silenciosas en que un run largo se sale del carril.
- Poda con calendario. Los ficheros de reglas solo crecen si les dejas. Cada regla que borras es una cosa menos que un agente puede aplicar mal.
- Deja las decisiones fuera. Los hechos operativos van aquí. Las decisiones de producto van en un artefacto que persiste fuera del chat y carga su motivo. Una convención que deriva es molesta. Una decisión que deriva es una reescritura.
Dónde encaja PaellaDoc
Un fichero de reglas se pudre porque nada lo obliga a seguir siendo verdad, y la cosa que lo lee no lo distingue. Ese es el mismo fallo que la documentación pudriéndose, y el arreglo es el mismo: instrucciones que viven cerca del código que gobiernan y se vuelven a derivar de la evidencia en vez de teclearse una vez y creerse para siempre, la idea detrás de el cerebro de producto que se mantiene solo. PaellaDoc guarda el contrato operativo y las decisiones de producto como artefactos comprobados, no texto libre que un agente lee por fe, así que una regla que deja de coincidir con la realidad aparece como un gate fallido y no como una respuesta segura y equivocada. Porque la persona que sostiene todo esto en la cabeza es el runtime hasta que otra cosa hace la comprobación.
FAQ
¿Cada cuánto debería actualizar CLAUDE.md o AGENTS.md?
Continuamente para las partes mecánicas y con calendario para el resto. Monta una comprobación que falle tu build cuando una ruta o comando del fichero ya no resuelva, para que las referencias colgantes se pillen el día que aparecen. Luego haz una auditoría deliberada de las convenciones cada pocas semanas, idealmente haciendo que un agente compare las reglas contra el código actual.
¿Cómo sé si una regla está desactualizada?
Tres señales: referencia una ruta o comando que ya no existe, describe una convención que los commits recientes contradicen, o no sabes decir por qué está ahí. La primera es scriptable, la segunda la puede auditar un agente contra el código, y la tercera significa que la regla no tiene procedencia y no debería creerse hasta que la tenga.
¿No debería dejar que el agente mantenga su propio fichero de reglas?
Usa al agente para detectar la deriva, no para reescribir el fichero sin supervisión. “¿Qué instrucciones contradice el código?” es una buena pregunta con respuesta comprobable. “Reescribe mis reglas para que sean mejores” produce slop plausible. Deja que el humano decida qué se queda; deja que el agente haga la búsqueda.