Cuando el PR se ve bien, pero igual algo no encaja
Si llevas más de unas pocas semanas sacando cambios con AI, probablemente ya conoces esta sensación.
Abres un pull request. El código está lo bastante limpio. Los nombres están bastante bien. Hay tests. Nada parece roto de forma obvia. Y aun así, algo no termina de cerrar.
Quizá la boundary está un poco borrosa. Quizá el contract está implícito en vez de estar dicho. Quizá el happy path está cubierto, pero la regla real del negocio sigue viviendo en la cabeza de alguien. Sientes el riesgo, aunque no puedas señalar una línea catastrófica.
Ese es el nuevo problema de revisión.
Muchos equipos siguen pasando el desarrollo asistido por AI por un flujo viejo: escriben un prompt, generan un diff, abren el PR y le piden a un ingeniero senior que inspeccione el código con el cuidado suficiente para detectar invariants rotos, casos límite omitidos, deriva arquitectónica y riesgo oculto.
Eso tenía sentido cuando los humanos escribían casi toda la implementación por sí mismos. Tiene mucho menos sentido cuando un modelo puede generar la implementación, la primera suite de tests, el schema e incluso el scaffolding de contracts de una sola pasada.
En ese punto, revisar código línea por línea deja de ser el lugar de mayor impacto donde poner la atención senior.
La pregunta de verdad ya no es: “¿Esta función parece razonable?”
La pregunta de verdad es: “¿Definimos correctamente el comportamiento, la boundary y el invariant antes de que existiera la función?”
Esa es la inversión del flujo de trabajo que introduce la AI. La revisión de código no desaparece. Pero el centro de gravedad se mueve aguas arriba. En la era de la AI, la revisión de código se convierte en revisión de especificaciones.
Por qué este cambio se siente tan distinto
Durante mucho tiempo, la mayoría de los equipos de ingeniería trataron las especificaciones como material de apoyo.
El código era lo importante de verdad. El doc comment era apenas una pista. El ADR era contexto, si te daba tiempo a leerlo. El schema era “solo validación”. El archivo de Gherkin era un extra útil, si alguien se tomaba la molestia de mantenerlo al día.
Esa jerarquía se está rompiendo.
Si un LLM puede convertir una especificación en artefactos de implementación de forma rápida y repetida, entonces la especificación deja de ser secundaria. Se convierte en el objeto fuente del que se deriva el resto del sistema.
Y eso cambia dónde es más barato detectar los errores.
Si la especificación es vaga, el modelo puede producir una implementación muy bien estructurada de la cosa equivocada. Puede darte código limpio, tests plausibles y una falsa sensación de confianza. Incluso una buena revisión de código puede pasar por alto el problema real porque el bug no está en la sintaxis. El bug está en la intención.
Eso es lo que hace este momento tan delicado e importante. La AI hace más fácil producir resultados convincentes. También hace mucho más peligroso ser descuidado con lo que pediste.
Si la especificación es precisa, acotada y comprobable, todo se vuelve más fácil. La implementación se vuelve más fácil. La validación se vuelve más fácil. La revisión se vuelve más fácil. El CI se fortalece.
Por eso el mejor esfuerzo humano de revisión se está moviendo lejos de auditar a mano cada branch y hacia endurecer el artefacto que define el comportamiento de esa branch desde el principio.
Una especificación no es un documento gigante de requisitos
Cuando la gente oye la palabra “especificación”, suele imaginarse un documento inflado que nadie quiere escribir y en el que nadie confía seis semanas después.
Eso no es lo importante aquí.
En un flujo práctico asistido por AI, una especificación es cualquier artefacto que define el comportamiento esperado con suficiente precisión como para habilitar generación y enforcement.
Eso puede ser:
- un ADR en Markdown que describe una boundary rule
- un schema de Zod que define la forma del input externo
- la firma de una función con un doc comment preciso
- un escenario de Gherkin que captura comportamiento observable
- un bloque de contract que define preconditions y postconditions
- un modelo de reducer o una tabla de transición de estado
Nada de esto tiene que ser pesado. Solo tiene que ser lo bastante claro como para que las herramientas puedan hacer algo útil con ello.
Ese es el umbral que importa. Una especificación útil no solo es legible para humanos. También es accionable por el sistema que rodea al codebase.
Cómo empieza a verse una revisión realmente buena
En el modelo viejo, un ingeniero senior gasta su energía en preguntas como:
- ¿esta implementación está limpia?
- ¿quién lo escribió dejó fuera algún caso límite?
- ¿estos tests son lo bastante sólidos?
- ¿este import rompe una boundary?
Esas preguntas siguen importando. Lo que pasa es que ya no son las primeras preguntas de mayor impacto.
En un flujo centrado en especificaciones, las preguntas más valiosas son:
- ¿el contract es realmente correcto?
- ¿el schema define la boundary real?
- ¿las reglas de negocio están completas?
- ¿el ADR es lo bastante preciso como para hacer enforcement?
- ¿las properties enumeradas expresan la semántica real?
Esas son mejores preguntas de revisión porque una buena respuesta mejora varios artefactos a la vez.
Si endureces un ADR vago, mejoras la regla de arquitectura, la guía de implementación y el enforcement en CI de un solo movimiento.
Si corriges un schema débil, mejoras la validación en runtime, la inferencia de tipos y la calidad de generación de código de una sola vez.
Si afilas un contract, mejoras la implementación, los tests y la resistencia a mutaciones de una sola vez.
Esa es la diferencia de apalancamiento. Ya no inspeccionas artefactos uno por uno. Estás revisando aquello que les da forma.
Por qué la revisión de código tradicional empieza a agrietarse
La revisión de código tradicional asume que los humanos son los autores principales y que quien revisa está comprobando la calidad de un proceso de pensamiento humano a partir del código terminado.
Con AI, ese supuesto se debilita cada semana.
Un modelo puede producir cincuenta líneas plausibles en segundos. Puede producir otras cincuenta igual de rápido. Y otras cincuenta después. Si todo tu proceso depende de que alguien detecte a mano deriva semántica enterrada dentro de ese flujo, la superficie de revisión crece más rápido de lo que la atención humana jamás va a crecer.
Eso crea un mal equilibrio:
- la generación de código se acelera
- los diffs se vuelven más grandes o más frecuentes
- sube la fatiga de revisión
- baja la confianza semántica
- los equipos empiezan a compensar con vibes, intuición y “looks good to me”
Esa no es una estrategia de escala. Es riesgo acumulado con buen formato.
La jugada inteligente es reducir desde el principio cuánta revisión subjetiva necesitas. Empuja más significado hacia especificaciones deterministas y revisables. Luego deja que la máquina compruebe si el código sigue alineado con ese significado.
El CI es lo que vuelve esto real
Esta inversión del flujo de trabajo solo funciona si la especificación está atada al enforcement.
Si no, solo le estás cambiando el nombre a la documentación y esperando que la gente la respete más.
El punto es volver operativa la especificación.
Eso significa:
- las decisiones de arquitectura se compilan en reglas de dependencias
- los schemas definen boundaries seguras en runtime y a nivel de tipos
- los contracts generan checks ejecutables
- las listas de properties impulsan la generación de tests
- la semántica crítica se convierte en merge gates
Cuando eso pasa, el CI deja de ser un sistema de build pasivo y se convierte en el mecanismo que mantiene la implementación alineada con la intención.
Esa es también la razón por la que las especificaciones vivas por fin se vuelven realistas para equipos normales. Históricamente, la documentación se pudría porque nadie tenía tiempo de mantener texto y código sincronizados a mano.
La AI cambia la economía de escribir y actualizar esos artefactos. El CI cambia la economía de hacer enforcement sobre ellos.
Necesitas ambas cosas. La AI sin enforcement te da deriva pulida. El enforcement sin buenas especificaciones te da confusión rígida.
Controles duros, revisiones suaves
Esta es también la parte de la filosofía de Autotomy que cada vez me parece más acertada.
La idea es simple: mete las reglas no negociables en controles duros y deja que la revisión humana se concentre en las partes que de verdad requieren criterio.
Eso significa que types, schemas, contracts, reglas de dependencias y deterministic checks se encargan de los modos de fallo conocidos. Corren cada vez. No se cansan. No se distraen por un diff bien formateado. No les importa si el código viene de un ingeniero staff o de un language model.
Entonces la capa de revisión se vuelve más pequeña y mejor.
En vez de gastar atención senior en cosas que el sistema podría haber rechazado automáticamente, la gastas en tradeoffs, semántica, interfaces y arquitectura. Preguntas si la boundary es correcta, si el contract es honesto, si el reemplazo realmente satisface la interface, si el sistema se está volviendo más fácil o más difícil de cambiar.
Esa última parte importa mucho.
Uno de los efectos secundarios más sanos del trabajo specification-first es que te empuja hacia puntos de corte más limpios. Si un module puede ser reemplazado mientras satisfaga el contract y pase los checks, dejas de tratar cada implementación como si fuera sagrada. Empiezas a diseñar para reemplazo seguro en vez de preservación dolorosa.
Es un cambio sutil, pero cambia la forma en que los equipos manejan el crecimiento. El codebase deja de sentirse como algo que solo puedes parchear con cuidado desde dentro. Empieza a sentirse como un sistema con costuras explícitas.
Esto en realidad son buenas noticias para los ingenieros senior
Este cambio no vuelve menos valioso el criterio de la ingeniería senior. Lo vuelve más enfocado y más importante.
El ingeniero senior ya no aporta más valor como un motor humano de diffs sintácticos. Aporta más valor donde se resuelve la ambigüedad, se eligen invariants, se moldean interfaces y se vuelven explícitos los tradeoffs.
Eso implica dedicar más tiempo a:
- escribir ADRs precisos
- definir contracts y schemas
- revisar cambios semánticos en vez de cambios estilísticos
- decidir qué properties merecen enforcement
- convertir la arquitectura en reglas aplicables en el merge
Es un uso mucho mejor de una atención cara.
La máquina es muy buena rellenando detalle de implementación. Los ingenieros senior siguen siendo mucho mejores para decidir qué debe seguir siendo verdad cuando el sistema se estresa, cambia y escala.
No necesitas reescribir el proceso entero
Esto puede sonar más grande de lo que realmente es.
No necesitas lanzar una iniciativa de métodos formales. No necesitas dejar de entregar cambios. No necesitas enterrar al equipo en proceso.
Empieza con un cambio acotado: trata una clase de especificación como un artefacto de primera clase que merece revisión.
Una secuencia práctica se ve así:
- exigir doc comments precisos y schemas en boundaries críticas
- tratar los cambios en ADRs como elementos de revisión senior
- generar tests y contracts a partir de esos artefactos
- hacer enforcement en CI sobre deriva de arquitectura y de contracts
- bajar de prioridad los comentarios de review solo de estilo a favor de revisión semántica
Eso basta para cambiar la cultura.
Una vez que los equipos sienten que mejores especificaciones reducen el churn de revisión aguas abajo, la dinámica empieza a reforzarse sola. Las revisiones se vuelven más nítidas. Los diffs dan menos miedo. La confianza mejora.
El cambio estratégico real
Los equipos que ganen con AI no serán los que simplemente generen código más rápido.
Serán los equipos que muevan la atención humana hacia la parte más estrecha y de mayor impacto del flujo.
Esa parte es la especificación.
Cuando la especificación se convierte en el artefacto primario, el código deja de ser lo único que vale la pena revisar línea por línea. Se convierte en uno de los resultados de un sistema más disciplinado.
Ese es el cambio real.
La implementación sigue importando. Mucho. Pero cada vez más, la decisión de revisión más importante ocurre antes de que la implementación exista.
Y por eso, en la era de la AI, la revisión de código se convierte en revisión de especificaciones.