En una consultoría revisé un sistema que un equipo nuevo estaba migrando a otra tecnología.
Nota: cuento esta historia con autorización del cliente. No lo nombro, a pedido suyo: la comparto como experiencia, no como caso de estudio.
Lo primero que hice fue leer lo que había antes de ellos, lo existente. Y había mucho. El equipo anterior había sido muy bueno y muy ordenado: ADRs, RFCs, commits con pruebas de concepto, código documentado y con tests, páginas de Confluence con las decisiones y hasta los garabatos del análisis. Enlaces a los hilos de Slack y a los tickets de Jira. Se notaba que pensaron en quien viniera después.
Después abrí la migración.
En la parte que revisé, no encontré documentadas las razones de las decisiones nuevas.
Lo irónico es que el sistema viejo, el que iban a reemplazar, era el que dejaba más contexto para cambiarlo. Si la migración se entregaba así, quien viniera después iba a encontrar el código, pero no esas razones.
Mientras quienes tomaron las decisiones sigan disponibles, se les puede preguntar. ¿Y cuando ya no estén?
Puedes entender el código y aun así no tener suficiente información para cambiarlo.
#.¿Dónde quedó la decisión?
El PR puede explicar qué cambió, y ayuda mucho si es pequeño y está ligado a un ticket.
El ticket puede decir qué había que entregar. ¿Y por qué descartamos la otra opción?
Para eso existen los Architecture Decision Records, o ADRs: documentos cortos donde dejamos escrita una decisión importante, su contexto y sus consecuencias.
Michael Nygard, que popularizó la idea en 2011, lo explicaba así: quien llega a un proyecto y no entiende el porqué de una decisión tiene dos opciones. Aceptarla a ciegas o cambiarla a ciegas.
Hace unas semanas escribí sobre lo que pasa cuando el equipo deja de hablarse y cada quien conversa con su IA: decisiones que nadie puede explicar seis meses después, porque nunca se discutieron. Esa consultoría me dejó pensando en lo que viene después, cuando además nadie las escribió y confiamos en un “después le preguntamos a la IA”. Como si explicar el sistema fuera lo mismo que recordar cómo llegamos a él.
#.Lo que una auditoría no garantiza
Si tu empresa pasa por una auditoría SOC 2, podrías pensar que esto ya está cubierto: los controles de cambios dejan rastro. SOC 2 es un informe de auditoría sobre los controles de una empresa, con los Trust Services Criteria del AICPA como base.
Uno de esos criterios, el de gestión de cambios (CC8.1), pide, entre otras cosas, que los cambios al software, la infraestructura, los datos y los procedimientos se autoricen, documenten, prueben y aprueben. Ese rastro no tiene que vivir en el repositorio. CC8.1 no exige tests automatizados ni un ticket por PR, aunque una empresa puede haberlos definido como parte de sus propios controles.
Un equipo puede tener cada cambio con su ticket, su PR revisado, sus pruebas y su aprobación. Una aprobación registrada demuestra que alguien aprobó el cambio. No que alguien sabía por qué.
SOC 2 no prescribe ADRs. La evidencia de cumplimiento puede conservar también las razones, pero cumplir el criterio no garantiza que queden escritas donde las necesita quien vaya a cambiar el sistema.
#.Una explicación convincente no es una razón
Una IA puede encontrar pistas en tickets y commits. Si las razones quedaron ahí, puede ayudar a recuperarlas. También puede proponer argumentos que no habíamos considerado, o reconocer que le falta información.
El problema empieza cuando tratamos esos argumentos como la historia real de la decisión. Que una cola absorba picos de tráfico no demuestra que por eso la elegimos.
“Mejor escalabilidad”. “Menor acoplamiento”. Todo suena bien. Pero ¿fueron esas las razones? ¿O teníamos tres semanas, una integración heredada y nadie disponible para mantener otro servicio?
Y la IA solo puede leer lo que dejamos. Si el porqué no quedó escrito, la IA puede proponer uno que suene razonable. Eso no confirma que esa fue la razón.
Si usamos la IA para justificar después lo que nunca discutimos antes, el documento puede quedar mejor escrito que la decisión que representa.
#.Escribir también es decidir
Martin Fowler lo dice en su artículo sobre ADRs: escribirlos ayuda a aclarar el pensamiento, sobre todo en grupo, y saca a la luz los puntos de vista distintos dentro del equipo. Al intentar explicar una decisión aparece lo que no sabíamos y en qué no estábamos de acuerdo.
Ahí la IA sí ayuda: a ordenar notas, a encontrar contradicciones, a decirte qué falta. Pero si le delegamos las razones y aprobamos lo que suena convincente, nos saltamos justo la parte en la que decidimos. Es la misma rendición cognitiva de la que escribí hace dos semanas.
La crítica seria a los ADR tiene razón en algo: una persona también puede escribir la razón presentable en vez de la real. Escribirlo no lo vuelve cierto. Por eso importa que quede cerca del momento de decidir, con quienes decidieron y con la restricción real, aunque no luzca bien.
Si toca reconstruir una decisión vieja, pregúntale a quienes estuvieron mientras se pueda y deja claro que es una reconstrucción. Lo que nadie pueda confirmar queda como hipótesis, lo haya propuesto una persona o una IA.
Si el porqué ya quedó claro en un PR o un ticket fácil de encontrar, no hace falta copiarlo en otro documento. Yo reservaría un ADR para decisiones que afectan a varias partes del sistema o que sería caro revertir.
Un ADR tiene su costo: hay que escribirlo, dejarlo donde se encuentre y marcarlo cuando lo reemplace otro. Por eso no hacen falta documentos enormes que nadie lee. Un registro breve puede bastar. Por ejemplo:
Procesamos estas solicitudes en segundo plano porque el proveedor puede tardar más que el límite de nuestra petición HTTP. No subimos ese límite porque dejaría conexiones abiertas mientras esperamos al proveedor. Aceptamos que el usuario reciba el resultado después. Lo vamos a revisar si el proveedor ofrece una respuesta inmediata y confiable.
Para empezar, yo dejaría tres preguntas:
- ¿Qué decidimos y por qué descartamos la otra opción? La restricción real, no la ideal.
- ¿Qué aceptamos a cambio?
- ¿Cuándo lo revisaríamos?
#.Para poder cambiar de opinión
Una decisión escrita no es una orden eterna. Puede haber sido un error, o haber dejado de tener sentido. Pero si sabes por qué se tomó, puedes discutirla en serio. Y cuando la reemplazas, Fowler recomienda no reescribir el registro viejo, sino marcarlo como reemplazado y enlazarlo con el nuevo.
Eso es lo que encontré en aquel sistema viejo: un rastro de por qué tomaron esas decisiones. Con eso, cambiarlo no requería adivinar.
Piensa en la última decisión grande de tu equipo. ¿Dónde está escrito por qué?
La IA le puede explicar el código a quien venga después. El porqué se lo tenemos que dejar nosotros.