Dejé de programar con IA y empecé a dirigirla

Todos hemos tenido ese momento con la inteligencia artificial en el que piensas: esto es magia. Le pides una pantalla y aparece la pantalla. Le pides las pruebas automáticas y aparecen las pruebas. La primera semana sientes que acabas de contratar a 3 personas.

A mí me pasó, y me duró varios meses. Yo pedía, la IA escribía, yo revisaba, yo corregía, yo volvía a pedir. Sí avanzaba más rápido que solo, no lo voy a negar. Pero mucho menos de lo que esa primera semana prometía, porque tenía que estar encima todo el rato.

Porque en realidad yo no estaba dirigiendo a nadie. Estaba programando en pareja con una máquina muy veloz, y la mitad lenta de esa pareja seguía siendo yo.

La etapa en la que la IA era un copiloto rápido

Yo usaba la IA como copiloto: programar conversando, pedirle lo siguiente que se me ocurría y revisar lo que escribía. Era entretenido y funcionaba bastante bien. Pero tenía un techo, y el techo era yo.

Como cada pedido necesitaba mi atención completa, solo podía tener una conversación viva a la vez. Si me paraba a almorzar, el trabajo se paraba conmigo. Eso no es delegar. Es escribir el código con las manos de otro.

Y había un segundo problema, menos obvio. Las preguntas que de verdad frenaban el trabajo no eran preguntas de programación:

• ¿Esto contradice alguna decisión que ya tomamos antes?
• ¿Lo que estoy construyendo cumple de verdad el objetivo que nos planteamos, o solo cumple el pedido tal como me llegó?
• ¿Este cambio puede romper algo que otra persona está construyendo en paralelo, o dejar un efecto secundario que nadie pidió?
• Esto ya se resolvió antes en otra parte del producto. ¿Por qué se hizo así y no de la otra forma?

Ninguna de esas preguntas la podía responder la IA con el contexto que yo le daba. Y en muchos casos yo tampoco, porque la respuesta no estaba escrita en ningún lado: estaba en la cabeza de alguien de otro equipo, o en un hilo de chat que nadie iba a volver a encontrar. Así que tenía que ir a buscar a esa persona, explicarle el caso y esperar. Mientras tanto, la IA seguía ahí, lista para ejecutar, sin nada que ejecutar.

La IA no fallaba por falta de capacidad. Fallaba por falta de contexto, que es una cosa muy distinta.

Para darle ese contexto, tenía que hacer algo más que mejorar la instrucción que le escribía. Poner la información en archivos permitía compartirla con la IA, con la persona nueva que entrara al equipo y conmigo mismo dentro de 6 meses.

¿Por qué documentamos antes de empezar a programar?

Porque escribir el contexto le permite a la IA consultar nuestras decisiones antes de programar. Un documento convierte una decisión que vivía en la cabeza de una persona en algo que cualquiera puede leer: la IA antes de programar, quien entre al equipo el mes que viene, y yo mismo dentro de 6 meses.

Dicho así suena a burocracia, y lo entiendo. La diferencia está en qué escribes y dónde. No es un documento enorme que nadie abre: es una cadena de documentos cortos, cada uno con un responsable y una sola pregunta que responder, y ninguno repite lo que ya dijo el anterior. En JobLeap, la empresa donde trabajo hoy, y también en mis proyectos personales, la cadena es esta:

• PRD · lo escribe producto. Define el producto completo: qué es, a quién le sirve, qué problema le resuelve y cómo vamos a medir si funcionó.
• PDD · lo escribe diseño. El diseño a nivel de producto: el sistema visual y los patrones de interacción que todas las pantallas heredan, para que cada funcionalidad no se invente su propio lenguaje.
• FRD · lo escribe producto. Una funcionalidad concreta, contada desde el usuario, con criterios de aceptación: las condiciones que debe cumplir para darla por terminada, verificables una por una.
• FDD · lo escribe diseño. Cómo se ve y cómo se comporta esa funcionalidad, incluidos los estados vacíos, de carga y de error. No es un mural de referencias: es una especificación.
• Blueprint · lo escribe ingeniería. El plan técnico: componentes, modelo de datos, contratos entre las piezas y en qué orden se construye cada cosa.
• Órdenes de trabajo · las escribe ingeniería. El pedido ejecutable: qué archivos se tocan, qué criterio de aceptación cumple cada uno y cómo se valida.

Sueltos, esos 6 tipos de documentos serían 6 opiniones sobre el mismo proyecto. Lo que los convierte en algo útil es que están enlazados entre ellos: cada uno apunta a los de arriba, y cuando 2 se contradicen hay un orden escrito de quién manda. Un criterio de aceptación se puede seguir desde el documento donde se pidió, hasta la pieza técnica que lo resuelve, hasta la orden de trabajo que lo construye.

Eso es lo que de verdad cambia para una IA. Cuando abre una orden de trabajo, ya tiene adentro la decisión de producto tomada, el diseño aprobado, el modelo de datos definido y los criterios con los que se va a medir. Y si algo no está ahí, no tiene que preguntarle a nadie ni adivinar: sube por las referencias hasta encontrarlo, o hasta descubrir que nadie lo decidió todavía, que también es una respuesta.

Por eso puede tomar decisiones de implementación apoyándose en lo que ya decidimos, y construir algo que se parece a lo que queríamos construir. Aun así, sigue haciendo falta revisar que el código cumpla el plan.

Una orden de trabajo es un pedido que reúne el contexto necesario para construir y validar una parte del producto. Las órdenes que no dependen unas de otras se pueden ejecutar en paralelo.

Eso me permite avanzar con varias órdenes a la vez. Cuando empiezo a construir una funcionalidad, lo primero es el plan: qué órdenes dependen de otras y cuáles no. Ese análisis me da el número que puedo lanzar en paralelo, que cambia en cada funcionalidad, y cada una arranca con su propia sesión de IA trabajando por su cuenta. Después paro a propósito: reviso el código, corro las pruebas, confirmo que las piezas encajan entre ellas, y recién ahí suelto el siguiente grupo. Yo decido dónde va cada punto de espera. Esa es la diferencia real entre tener un asistente y tener un equipo de IA.

Ese encadenamiento no lo inventamos nosotros. Lo tomamos de 8090, una plataforma que ordena el ciclo de desarrollo en requisitos, blueprints y órdenes de trabajo. Nos quedamos con el modelo de trabajo, no con sus herramientas: nuestros documentos son archivos de texto en un repositorio, y se aprueban con pull requests, solicitudes de cambio que otra persona revisa antes de incorporarlas, igual que el código.

Reglas, comentarios y notas de entrega

Los documentos dicen qué construir. Falta la otra mitad: cómo queremos que se construya.

Eso vive en un conjunto de reglas de ingeniería que la IA lee antes de escribir la primera línea. Cómo se nombran las cosas, qué tiene que tener pruebas, qué datos hay que validar antes de confiar en ellos, qué está prohibido, y en qué casos tiene que frenar y preguntarme. En mi fábrica personal son 122 criterios que decidí una sola vez y que heredan todos mis proyectos. Gracias a eso, cada sesión escribe con el mismo estilo y el código se mantiene parejo, en vez de parecer escrito por 6 personas que nunca se hablaron entre ellas.

Después están los comentarios en el código. Yo venía de la escuela del "buen código no necesita comentarios" y la cambié. No escribo comentarios que narran lo que hace la línea de abajo. Escribo los que explican el porqué y los límites: por qué este orden importa, qué se rompe si alguien cambia este valor, qué caso raro me obligó a hacerlo así. Ese comentario es contexto que sobrevive a la conversación donde se decidió.

Y al final está la nota de entrega. Cuando una IA termina una orden de trabajo, escribe qué construyó, qué decidió en el camino, qué dejó pendiente y qué debería saber el que siga. Esa nota se queda en el repositorio, al lado del código.

La nota de entrega registra qué construyó una sesión de IA, qué decidió y qué dejó pendiente. Así, la siguiente sesión puede continuar con ese contexto escrito.

Un repositorio que funciona como el cerebro de la empresa

Todo eso junto vive en un solo lugar. En el trabajo tenemos un repositorio que funciona como el cerebro de la empresa: quiénes somos, a quién servimos, cómo ganamos dinero, cómo se escribe cada documento, los estándares de ingeniería y el registro de cada decisión que tomamos, con su porqué y con las opciones que descartamos. Lo escribimos entre todos los que trabajamos ahí, y se publica igual que el código: en una rama, en un pull request, revisado, y recién ahí pasa a ser verdad.

El efecto en mi día a día fue más grande de lo que esperaba. Dejé de depender de cazar a la persona correcta para poder avanzar. Si necesito saber por qué algo se llama así, está escrito. Si necesito tomar una decisión de producto, los criterios están escritos. Puedo decidir en ingeniería y también en producto, no porque me haya vuelto el más listo del salón, sino porque el criterio de todos está ahí y puedo leerlo a la hora que sea.

Y recién ahí la IA empezó a rendir de verdad. Con ese contexto disponible, cada pedido dejó de necesitar mi explicación y pasó a necesitar solo mi aprobación. Mi trabajo se movió de escribir a revisar.

Hago exactamente lo mismo en mis proyectos personales. Este blog que estás leyendo salió de ahí: tiene su especificación de producto, 8 documentos de requisitos, 20 órdenes de trabajo y un registro con más de 120 decisiones. Un sitio personal no necesita nada de eso. Pero yo no quería escribir el sitio: quería dirigirlo.

La IA hace el trabajo pesado, pero alguien tiene que firmar

Nada de esto significa que la IA quede suelta. Y acá te puede aparecer una duda razonable: si escribimos todos esos documentos y todas esas reglas justamente para que la IA no se pierda, ¿para qué haría falta que alguien revise al final?

Porque los documentos y las reglas le dan a la IA una base para decidir, y la revisión comprueba si de verdad la siguió.

Escribir el plan no hace que una IA deje de equivocarse. Le da el contexto para saber qué construir, cómo construirlo y por qué, que es lo que hace que el resultado se parezca a lo que pedimos.

Aun con esa base, he visto errores por 2 motivos:

• Algo que no escribimos. Un caso esquina, de esos raros que no se le ocurren a nadie mientras redacta los criterios de aceptación. La IA no tiene qué consultar, así que decide sola, y decide rápido.
• Algo que escribimos, pero que se perdió por el camino. Cuando una tarea se estira mucho, el modelo va perdiendo de vista lo que leyó al principio. El plan sigue escrito; la IA simplemente ya no lo está mirando.

El segundo caso me tocó en una funcionalidad del trabajo. El plan estaba escrito y aprobado desde antes de empezar, y aun así lo que salió hacía lo contrario de lo que ese plan decía, con sus pruebas pasando y todo. Boté el trabajo entero y volvimos a planificar. Lo conté completo en el post sobre cuándo descartar el código de una IA.

La revisión permite detectar tanto un caso que faltó documentar como una decisión escrita que el código contradice. Por eso hay puntos donde el trabajo para y espera a una persona, y no son negociables. Producto aprueba el FRD y el diseño antes de que exista una sola línea de código. Un ingeniero revisa el blueprint completo: el modelo de datos, los criterios de aceptación, la arquitectura, qué librerías entran y cuáles no. Y subir a producción siempre lo aprueba una persona.

Ese error que te conté lo encontró una persona, leyendo el plan contra el código, en una tarde. Revisarlo a tiempo nos permitió volver a planificar antes de que llegara a producción.

Si hoy estás en la etapa del copiloto, con la IA al costado tirándote código mientras tú manejas, no es que la estés usando mal. Yo estuve ahí un buen tiempo y aprendí un montón. Solo que en algún momento puedes chocar con el mismo techo con el que choqué yo. A mí, superarlo me pidió algo más que mejorar una instrucción: escribir lo que hasta entonces solo vivía en mi cabeza.

Gracias por leer hasta acá. 🙂