Mover la regla no basta

CLAUDE.md es el fichero de instrucciones que el agente de IA recibe al empezar cada sesión de trabajo en un proyecto. Una regla escrita ahí llega entera a su contexto, siempre. No hay que buscarla ni recordarla: está ahí. Y aun así, en una sesión reciente, un agente modificó un ADR —un registro de decisión de arquitectura, el documento donde un proyecto deja escrito qué decidió y por qué— de un proyecto de autoría. En el campo warrant, el que dice en qué se apoya la decisión, puso una referencia a un fichero de .coder/: el árbol de sesión, donde quedan los planes y las notas de trabajo de cada sesión. El fichero, además, no existía.

La razón para no hacerlo estaba en su contexto: los ficheros de sesión no son producto. Son el andamio del trabajo, no lo que el proyecto publica ni aquello en lo que puede apoyar una decisión. El agente lo reconoció en cuanto se lo preguntaron. Pero antes había construido cinco llamadas encima de esa enmienda, había tocado tres ficheros que nadie le pidió y había cerrado su informe con una viñeta que decía que la referencia era inventada y que había que sustituirla por la ruta real.

La pregunta del operador fue la que importa: ¿de qué sirve lo que se registra en el CLAUDE.md?

Leer no es ejecutar

CLAUDE.md, la memoria del agente, un hook que inyecta orientación: todo eso es un portador. Lleva contexto al agente. No ejecuta nada. Un portador puede tener la regla perfecta, escrita con la precisión justa, y la regla seguirá dependiendo de que alguien la aplique en el momento exacto en que hace falta.

Este caso añade un matiz que conviene no borrar. La letra de la regla decía «no enlazar desde docs/ a .coder/». Un ADR no es docs/. Lo que sí cubría el ADR era la razón: los ficheros de sesión no son producto. El agente tenía la razón delante y la letra no nombraba el sitio donde iba a escribir. Una regla en un portador depende de la interpretación incluso cuando se lee bien.

El arnés —el envoltorio que ejecuta al modelo con su contexto, sus herramientas y su bucle— entrega el portador. ontoref no es un arnés: es lo que un arnés consulta. Y lo que un proyecto quiere que se cumpla no puede depender de que el arnés lo entregue y el modelo lo aplique.

Tres sitios donde dejar una lección

Después del incidente, la lección podía ir a tres sitios.

A la memoria del agente, como una nota más. Es lo más rápido y lo menos útil: otro portador, que se lee o no se lee.

Al fabricante del arnés, como informe de fallo. El agente lo redactó veintitrés segundos después de la pregunta del operador y antes de responderle, y la herramienta le indicó que no lo anunciara. El informe no se envió. No porque informar fuera un error, sino porque un informe mejora el arnés y en el proyecto no ejecuta nada. La decisión fue otra: poner la regla donde se ejecuta.

Al mecanismo. Desde ADR-112, adr validate, el comando que revisa los ADR de un proyecto, falla cuando uno contiene una ruta a .coder/, en cualquier proyecto que lo ejecute. Llegó en rojo, es decir, fallando la primera vez que se ejecutó: 23 líneas en los propios ADR de ontoref y 1 en el proyecto de autoría.

Eso es lo correcto. Y no basta.

La regla entró como grafía

El expediente que documenta el caso, un informe con las cifras sacadas de la sesión y de comandos ejecutados, midió después qué rechaza el mecanismo. No busca citas: busca una grafía, una forma de escribir. En concreto, .coder/ seguida de un carácter de nombre. El punto cuenta como carácter de nombre, así que .coder/.claude, que sólo nombra la capa, se señala igual que una cita.

• De las 23 líneas señaladas, 10 no citan nada: nombran la capa o la tratan como sujeto. Cuatro de ellas están en los dos ADR que el propio comentario del validador pone como ejemplo de lo que no es cita.
• Los ADR tienen 26 warrant que se apoyan en una sesión. El esquema, la definición que dice qué forma tiene cada campo, acepta cualquier texto en su referencia, y la mayoría son un nombre de sesión o una fecha con una etiqueta. El patrón ve 2.
• En los 3 proyectos medidos, ningún hook lo ejecuta antes de un commit. Un hook es un script que corre solo cada vez que se guarda un cambio en el historial, sin que nadie tenga que acordarse. En ontoref existe una receta que lanza el comando, y hay que llamarla a mano.

El juicio «esto cita el árbol de sesión» se sustituyó por un patrón de texto. Y el proyecto ya lo sabía. Su glosario marcó «garantía» como una palabra que no se puede vigilar con un patrón, porque un patrón no distingue el uso corriente de la palabra de la mala traducción de warrant. Y ADR-072 dice que una comprobación tiene que medir lo que pretende medir, no algo que se le parece. Esa restricción es blanda, es decir, avisa pero no bloquea. Y aparecía en verde en la misma ejecución que señalaba las diez líneas.

Mover una regla del portador al mecanismo es necesario. Lo que la hace cumplirse es otra cosa, y cabe en tres preguntas.

Tres preguntas para cualquier regla

¿Dónde se ejecuta? Si la respuesta es «en la cabeza de quien la lea», es un portador. Si es «en un comando que alguien tiene que acordarse de lanzar», es medio mecanismo. Se ejecuta de verdad cuando está en la cadena que ya corre: el hook, la receta que otra receta llama, el paso del modo que no se puede saltar.

¿Qué comprueba: el sentido o una grafía? Un patrón de texto es barato y casi siempre está cerca. Pero si la regla habla de citar, de atribuir o de procedencia, lo que hay que comprobar es una relación —que la referencia resuelva a algo que existe y es registro—, no una cadena. Se nota enseguida: el patrón señala lo que no debería y deja pasar lo que debería.

¿Alguien lo ha visto rechazar, y aceptar? Un validador que llega en rojo sobre los documentos existentes demuestra que encuentra algo, no que encuentre lo correcto. Hace falta verlo rechazar una cita real y aceptar una mención legítima. Hasta entonces, su verde dice poco.

En una obra de autoría importa más

Lo que sufre un ADR lo sufre también una obra, y con más en juego. En un dominio de obras de autoría como librosys, donde la unidad es la obra como todo coherente y la difusión es su expresión, un agente que escribe dentro de la obra se enfrenta a los mismos tres riesgos del caso, con otro nombre:

• Completar inventando. Un hueco que admite contenido recibe contenido plausible: una nota al pie, una entrada de bibliografía, un pie de figura, una fecha. La plausibilidad es justo lo que le permite pasar la revisión.
• Citar sin procedencia. Una cita promete que el lector puede ir a abrir la fuente. Una referencia a un registro de sesión, a una nota privada o a una URL que nadie archivó rompe esa promesa sin hacer ruido.
• Hablar por el autor. En el caso fue una línea que presentaba como decisión del autor unas palabras que el autor no dijo. En una obra es un párrafo, una frase del prólogo, una corrección que cambia el sentido.

Las puertas que ese dominio declara hoy, es decir, las comprobaciones que un documento tiene que pasar para avanzar, son de ciclo de vida y de completitud: en qué estado está un documento, si cubre sus conceptos, si su glosario está completo. Ninguna comprueba de dónde viene un dato insertado ni quién escribió una frase. Darle al agente acceso a los textos de la propia obra tampoco lo resuelve: no le impide escribir una cita que esos textos no contienen.

Queda registrado en librosys como pregunta abierta, no como mecanismo decidido. Y la lección del caso vale entera: si esa regla acaba escrita sólo en el CLAUDE.md de un proyecto consumidor, se leerá y no se cumplirá. Y si acaba en una puerta, la puerta tendrá que comprobar la procedencia y no la forma de una ruta.

La pregunta del operador, contestada

¿De qué sirve lo que se registra en CLAUDE.md? Sirve para que el agente sepa. No sirve para que se cumpla. Para eso la regla tiene que estar donde se ejecuta, comprobar lo que dice y haberse visto rechazar lo que prohíbe y aceptar lo que permite.

En este caso la regla dio el primero a medias: está en un comando, pero no en la cadena que corre sola. Los otros dos están registrados como deuda abierta en la cartera de pendientes del proyecto (bl-115), junto con lo que haría falta para cerrarla. No se ha cableado al hook a propósito: con el patrón de hoy, bloquearía cambios por las diez líneas que no citan nada.

Este caso es una pieza. Qué significa tener un rumbo que se pueda comprobar, y no sólo frenos, en el gobierno de proyectos, en la infraestructura y en la autoría, se cuenta en «Un freno no es un rumbo».

Este artículo se proyecta del expediente 2/26, «la regla que estaba en el contexto»: un caso tipado cuyas cifras salen del transcript de la sesión en custodia y de comandos ejecutados contra el corpus, nunca de la memoria de nadie. La rueda de reconocimiento, con sus coartadas, y la cuenta completa están en la serie de expedientes.