Escribimos el criterio para cambiar de opinión antes de necesitarlo, y se cumplió

Cuando se arrancó Carmela Cartonera, una editorial cartonera con catálogo, pedidos y un panel, la primera decisión de arquitectura fue la más aburrida posible: todo el contenido en el repositorio, sin CMS y sin base de datos. El ADR-0002 la defiende bien. El catálogo inicial son entre 6 y 12 obras, el único editor es el propio desarrollador, y cada alta de obra lleva de todas formas trabajo manual (texto, fotografías, maquetación del interior) que un CMS no iba a quitar de en medio.

Hasta aquí, una decisión sensata de las de "no construyas lo que no necesitas". Lo interesante está en la última línea de sus consecuencias:

Publicar exige saber hacer un commit — aceptable mientras el editor sea el desarrollador; es el criterio explícito de reversión de esta decisión.

Y en la alternativa del CMS headless: "se reconsiderará solo si el catálogo supera ~50 obras o si alguien no técnico pasa a editarlo".

Dos condiciones, escritas junto a la decisión. Una de ellas se cumplió antes de que acabara el día.

Una cláusula, no un viraje

El ADR-0002 es del 19 de julio. Ese mismo día aparece el ADR-0006, cuyo contexto empieza así: "Ese supuesto ha cambiado: entra a editar una persona no técnica. El criterio de reversión se cumple, así que se adelanta la pieza. No es un cambio de rumbo, es la condición que habíamos escrito."

Esa frase es el motivo de este post. Cambiar de arquitectura a los pocos días de elegirla suele vivirse como un pequeño fracaso: "¿no lo habíamos pensado bien?". Con la condición escrita de antemano, la conversación es otra. No hay que decidir si el cambio está justificado ni defenderlo ante uno mismo: la pregunta era "¿ha entrado alguien no técnico a editar?", y la respuesta era que sí.

Lo que habría pasado sin la cláusula es fácil de imaginar, porque es lo habitual: la persona nueva empieza a pedir cosas, el repositorio empieza a parecer un obstáculo, y cada queja se discute como un gusto ("a mí me gustaría un panel") en vez de como el cumplimiento de una condición que ya se había aceptado.

La respuesta rápida fue la equivocada

Que el criterio se cumpliera no significa que la respuesta fuera acertada, y el historial lo deja claro. La primera reacción, el ADR-0006, fue un CMS ligero ya hecho (Decap), con el contenido en el repo y una pull request por edición. Sobre el papel era casi gratis y resolvía el problema.

Se descartó el mismo día, sin llegar a desplegarlo. Al montarlo, la "fricción de alta única" que el propio ADR había anotado en sus consecuencias resultó ser otra cosa: el editor necesitaba una cuenta de GitHub con permiso de escritura en el repo. Para un perfil no técnico eso no es una fricción de alta, es una barrera.

Lo que me parece útil es lo que se hizo con ese ADR fallido: se conserva, con una nota de cabecera que explica por qué se descartó, "porque la alternativa vuelve a evaluarse cada vez que alguien propone «un CMS ligero ya hecho»". Es un ADR que existe para ahorrar una discusión futura. Lo reemplaza el ADR-0007, un panel propio en Next.js en el que se publica sin ver git ni GitHub.

Y el ADR-0007 vuelve a hacer lo mismo: trae su propio criterio de reversión. Si el panel se convierte en una carga de mantenimiento mayor que el valor que aporta, se retira sin perder contenido, porque los ficheros del repositorio siguen siendo la fuente de verdad. Asume además, sin disimular, el coste: código propio que mantener, la "segunda pieza dinámica" que el ADR-0002 evitaba.

Lo que el criterio no vio venir

Aquí es donde conviene no vender el patrón mejor de lo que es. La cláusula del ADR-0002 anticipó un cambio: quién edita. No anticipó el siguiente, y el que acabó reemplazando al ADR-0002 no fue ese.

Al día siguiente, el 20 de julio, el ADR-0010 lo sustituye por completo. Su motivo declarado no es la persona no técnica, que ya estaba resuelta con el panel. Es que "el objetivo del proyecto se ha hecho explícito": un CMS de comercio propio donde editar y publicar sea inmediato. Y el diagnóstico más honesto del documento es este:

Hay además un quinto acoplamiento que ningún ADR nombraba: el modelo de publicación. Mientras publicar sea «un commit que dispara un build estático», ningún cambio puede llegar a la web en menos de lo que tarda un build.

Ahí no había ninguna condición de reversión escrita. Guardar una ficha costaba alrededor de un segundo más entre uno y tres minutos hasta verla en la web; publicar o retirar una obra, minutos, porque cambiar un booleano disparaba un build entero. El ADR-0010 deja esa tabla medida, que es lo que hace discutible la decisión en vez de opinable.

Por eso no cuento esto como "escribimos el criterio y todo salió bien". Cuento que el criterio escrito sirvió para el cambio que alguien supo imaginar, y que el cambio más grande vino de un lugar que ninguna cláusula cubría: un objetivo de producto que todavía no se había puesto en palabras. Escribir condiciones de reversión no sustituye a preguntarse qué quiere ser el proyecto; solo evita pelear por lo que ya habías previsto.

Lo que se conserva cuando se cambia

El ADR-0010 tampoco rompe con lo anterior, y eso también es parte del método. Reemplaza al ADR-0002, pero en su cabecera lo dice, y el 0002 lleva una nota que explica por qué se reemplazó, sin reescribir el cuerpo. El propio README de los ADRs fija la regla: "Los ADRs no se editan al cambiar de opinión: se marcan como reemplazados y se escribe uno nuevo que los referencia".

Y el nuevo también trae su criterio de reversión: el espejo en git se mantiene siempre completo y en el formato MDX original, de modo que, si la plataforma resultara una carga desproporcionada, se puede volver al modelo de repositorio sin perder contenido ni historial. Otra decisión más que nace con su propia salida escrita.

El coste de este método

Escribir las condiciones de reversión no es gratis, y conviene decirlo.

Las referencias se pudren. El ADR-0002 remite a "criterios en arquitectura.md §6" para los umbrales de cambio; hoy esa sección del documento de arquitectura habla de los trabajos largos. Una condición que apunta a un sitio que ya no la contiene tiene menos valor del que parece, y lo único que la sostiene es la disciplina de mantenerla.

Además, un criterio solo funciona si es observable. "Alguien no técnico pasa a editar" lo es. "Cuando el panel sea una carga" es bastante más vago, y nadie va a notar el momento exacto en que se cumple. Las condiciones buenas son las que se pueden contestar mirando algo, no las que piden juzgar.

Lo que me llevo

Una decisión sin su condición de muerte es una creencia. Escribir qué tendría que pasar para deshacerla convierte el cambio futuro en una comprobación y no en una discusión.

Cumplir el criterio no certifica la respuesta. El criterio dijo "ha llegado el momento" y la primera solución, la gratis, era equivocada. Hay que dejar también registrado lo que se probó y falló.

Los criterios cubren los cambios que sabes imaginar. El más caro vino de un objetivo que aún no estaba en ningún documento. Lo que los ADRs no pueden hacer por ti es obligarte a decir qué quieres que sea el producto.

Si estás eligiendo una arquitectura "mínima" para empezar y quieres dejar escrito cuándo dejará de serlo, escríbeme: es una conversación de una hora que suele ahorrar la discusión de dentro de tres meses.