Inicio / Artículos

Deje de dar deseos a los agentes de IA: un proceso basado en especificaciones para equipos pequeños.

Dejen de hacerle deseos a los agentes de IA: un proceso centrado en las especificaciones para equipos pequeños con revisión por parte de dos familias de modelos, pruebas en tiempo de ejecución, fusión por parte de humanos y gestión de la memoria.

Editor: REACTAPP.TOP7 min de lectura1708 palabras

Fuentes: *A small dev team, a stack of AI agents, and the spec-first process that keeps them honest.*

Imagínese un agente de IA que crea una función en veinte minutos. La solicitud de integración se ve excelente: diferencias ordenadas, pruebas exitosas y un resumen amable. Sin embargo, también está equivocada, de una manera que requiere a un equipo tres días para resolverla.

El modelo en esa historia no era malo; hacía lo que se le indicaba. El problema estaba en la instrucción, que era en realidad un deseo. “Crea una página que muestre X” es un deseo, y un contratista rápido y literal intentará satisfacerlo adivinando todo lo que no se mencionó. Esas conjeturas parecerán plausibles, porque la plausibilidad es lo que producen estos sistemas.

Un pequeño equipo se niega ahora a desarrollar cualquier cosa hasta que todo esté descrito por escrito y esa descripción haya resistido pruebas rigurosas antes de que exista siquiera una línea de código. La gente denomina a este enfoque desarrollo guiado por especificaciones. Es lo que hace que los agentes sean fiables en grupos donde hay más software que personas para desarrollarlo. Los humanos deciden, revisan y fusionan los cambios. Los agentes se encargan de escribir el código. Este arreglo solo funciona cuando los agentes reciben algo más que una simple indicación.

Qué contiene una especificación

Nada se desarrolla hasta que exista un breve documento en Markdown que establezca tres cosas, en este orden:

  1. El problema actual y la razón por la que merece atención.
  2. Qué será cierto después, descrito de manera que un usuario pueda verificarlo.
  3. Qué debe permanecer exactamente igual mientras se realiza el trabajo.

El último punto tiene una importancia sorprendente. Una gran parte de cualquier especificación sólida consiste simplemente en delimitar la zona que no debe ser afectada por los cambios. El resto se refiere a escenarios, es decir, a cada caso límite que el autor pueda imaginar, cada uno redactado en forma de “si esto, entonces aquello”.

Las especificaciones se escriben como cambios diferenciales, nunca como documentos universales. Aquí está el comportamiento actual, aquí está exactamente lo que cambiará. Una especificación que intenta describirlo todo termina por no describir nada.

Dos IA atacan primero la especificación

Una vez terminado el borrador, dos revisores basados en IA lo reciben. Proceden de proveedores y líneas de modelos diferentes, y su única tarea es encontrar formas en las que el plan podría fallar. El equipo apodó a esta sesión “pow-wow”. Mezclar diferentes líneas de modelos es intencional: los revisores de una misma familia tienden a pasar por alto las mismas cosas, al igual que los hermanos que se complementan mutuamente en sus relatos. Lo que se busca es el desacuerdo.

Los hallazgos se incorporan nuevamente a la especificación. Una objeción se convierte en un requisito. Solo cuando la especificación deja de tener errores se envía a un desarrollador.

Ese orden tiene una historia detrás. En una ocasión, se envió a un desarrollador mientras aún se realizaba una revisión. La revisión arrojó hallazgos que invalidaron la mitad del código, y el equipo tuvo que pagar por ese código dos veces. Desde entonces, la regla es estricta: un desarrollador debe esperar hasta que ambos revisores hayan informado y cada hallazgo aceptado haya sido incluido en la especificación, incluso cuando parezca que saltarse ciertos pasos no causará problemas.

El encuentro ha dado frutos de maneras inesperadas. Un documento de especificaciones llegó a nombrar a un helper de permisos existente y asumió, solo por su nombre, qué era lo que verificaba. Un revisor abrió el código y descubrió algo mucho más limitado: solo se aplicaba al solicitante original y únicamente en un estado específico. Los nombres de las funciones pueden engañar. De ahí una costumbre firme: leer la implementación antes de que la especificación la mencione. Esa costumbre ha salvado más fines de semana que cualquier regla de análisis de código.

El proceso, de principio a fin

Para un cambio de verdadera envergadura, la secuencia es la siguiente:

spec → adversarial review → apply findings → build → diff review → runtime testing → human testing → human merge

Algunos pasos merecen comentario.

Al desarrollador se le proporciona la especificación y nada más. Nunca ve un registro de chat ni una solicitud casual de complemento. Todo lo que el desarrollador debe saber debe estar escrito en el documento, ya que cualquier cosa que falte puede ser objeto de conjeturas.

Las pruebas en tiempo de ejecución verifican qué hace el software, no cómo se ven los archivos. El simple hecho de superar las pruebas no dice mucho. En un incidente temprano, se suponía que debía aparecer un mensaje de validación en la pantalla, pero nunca lo hizo, ya que no se podía acceder al código que lo generaba. Tanto las diferencias como las pruebas estaban bien. Nadie había intentado hacer algo incorrecto como usuario, y una diferencia no puede mostrar un mensaje que no existe. Ahora se introducen fallos intencionadamente: se envía información no deseada, se confirma que el error es realmente visible y solo entonces se marca el trabajo como probado.

El paso humano consiste en que alguien navegue por la aplicación como un usuario impaciente, y ese es el objetivo. Existe un tipo de error que escapa a toda revisión automatizada: la función funciona, pero una persona no puede encontrarla. Pantallas de creación faltantes, navegación sin salida. Los clics realizados por frustración actúan como prueba de aceptación y generan más confianza que cualquier resumen.

La fusión de cambios sigue siendo tarea humana. Los agentes ni fusionan ni despliegan. La velocidad está bien, pero la solicitud de integración debe indicar con exactitud qué pruebas se ejecutaron y cuáles se omitieron, y el orquestador marca las pruebas omitidas como tales directamente. Cuando la mayor parte del equipo está formada por máquinas que verifican otras máquinas, los registros honestos son lo más importante.

La cantidad de procesos sigue el tamaño del cambio. Una pequeña corrección de texto se convierte en una PR directa. Los cambios relacionados con la seguridad, los permisos y el modelo de datos pasan por todos los procesos necesarios. Imponer procesos complejos a tareas triviales las arruina, y confiar en procesos simplificados para trabajos importantes destruye el proyecto.

Una vez que se envía un cambio, su especificación se archiva junto con el código. El repositorio va acumulando gradualmente un registro escrito de las decisiones tomadas, de modo que la pregunta de por qué algo funciona de cierta manera suele tener una respuesta fechada antes incluso que el propio código.

Revisión por parte de dos equipos que no escribieron el código

La reunión se centra en el plan. El código final pasa por un panel separado, y esta es la parte que otro equipo debería adoptar primero.

El constructor es una herramienta versátil, elegida porque sigue funcionando sin problemas y cuesta poco por token. El dinero destinado a inteligencia avanzada se reserva para la revisión, en forma de dos modelos de vanguardia provenientes de laboratorios distintos, ninguno relacionado con el constructor. Sus funciones difieren intencionadamente: uno ocupa el puesto de ingeniero senior, leyendo la diferencia entre el código y las especificaciones línea por línea y luego trabajando directamente con la compilación en ejecución para intentar encontrar fallos en la funcionalidad. El otro sirve como paso obligatorio, y no se fusionan cambios significativos sin su aprobación, por pequeños que parezcan.

¿Dos laboratorios en lugar de dos copias del modelo más potente? Los modelos relacionados comparten instintos. Un revisor tiende a perdonar el código escrito de forma similar a la suya y se tropieza con el código de alguien ajeno. Si ambos señalan la misma línea desde direcciones diferentes, casi con certeza se trata de un defecto. Si se contradicen, significa que había una laguna en las especificaciones, lo cual es mejor detectar con dos modelos que con un usuario.

Los “asientos” no son permanentes. A un revisor se le retiró su puesto después de que su salida consistiera en repetir una sola conclusión más de cien veces. Los modelos de razonamiento de gran tamaño pueden entrar en bucle cuando reciben una instrucción de tamaño variable. Se cambió al revisor, pero la restricción se mantuvo.

El agente que lo mantiene unido

Nada de esto es exótico. Las especificaciones, las revisiones y las pruebas son ideas antiguas vestidas con nuevas formas. Lo que es más difícil de predecir es cuánto importa la orquestación y cuántos agentes se necesitan para mantener unido todo el proceso.

El equipo utiliza Hermes Agent, un marco de agentes de código abierto de Nous Research, como orquestador. No se dedica principalmente a escribir código, sino a ejecutar el proceso, que es la tarea más valiosa. Tres características hacen posible este funcionamiento.

Memoria. La mayoría de los asistentes inician cada conversación sin recordar nada anterior y con un tono amable. Hermes mantiene el contexto entre sesiones, por lo que las decisiones se mantienen. Conoce los niveles de riesgo, sabe que los creadores nunca evalúan su propio trabajo y entiende que siempre hay una reunión previa a cada tarea, ya que los errores anteriores quedan registrados. Si alguien apresurado quiere saltarse un paso, el agente se niega: el proceso es supervisado por quien lo recuerda perfectamente.

Aprendizaje. Un fallo se convierte en un análisis posterior, y ese análisis se transforma en una habilidad; en Hermes, esto significa un documento de procedimiento que se carga en sesiones posteriores cuando es aplicable. Después de seis meses, el agente cuenta con una cantidad de notas obtenidas con esfuerzo a partir de incidentes reales y lee primero las relevantes. El conocimiento que antes estaba en la mente de un ingeniero experimentado ahora se encuentra bajo control de versiones.

Delegación. Las tareas de construcción y revisión se asignan a subagentes. Dado que Hermes funciona con cualquier proveedor, los roles pueden asignarse libremente a modelos: un modelo económico se encarga de la construcción, mientras que los modelos avanzados y costosos se dedican a la revisión. Si un modelo tiene un mes difícil, basta con reemplazarlo y nada más cambia.

Qué aporta y cuál es su costo

No existe aquí un porcentaje de productividad. Esos números no pueden verificarse, y casi todos quienes los publican están vendiendo algo. Estas son las afirmaciones que se pueden defender:

  • Se realizan envíos semanales a pesar de que no hay personas dedicadas a ello a tiempo completo.
  • El radio de impacto se mantiene dentro de los parámetros especificados, antes de que su contención se vuelva costosa.
  • Cualquiera que pregunte por qué el software se comporta de cierta manera puede encontrar la respuesta escrita.
  • El trabajo de las personas cambia, pasando de trabajar con el teclado a tomar decisiones y hacer clics.

Es un rol mejor, pero también más difícil. Redactar especificaciones precisas implica saber qué se quiere antes incluso de verlo. Dado que la implementación es económica, la exactitud se ha convertido en la habilidad escasa.

Los inconvenientes son reales. Redactar especificaciones exige disciplina, y la tentación de tomar atajos en un cambio supuestamente pequeño es lo que hace que este tipo de proceso fracase. Los revisores basados en IA pueden abrumarte con quejas menores, por lo que saber clasificarlas es una habilidad que hay que desarrollar. En las semanas en que los requisitos ya son evidentes, el proceso se vuelve lento. Además, necesita atención: si se deja sin supervisión, se deteriora como cualquier proceso humano.

Ya no se trata de si la IA puede escribir el código, porque sí puede hacerlo. Lo importante ahora es si puedes definir con precisión qué debe hacer el software y seguir tu propio proceso cuando el tiempo es escaso. Sin eso, ningún modelo sirve de nada; simplemente acelera tu confusión.

Leer más

  • Fundamentos de TanStack Query: Consultas, caché, mutaciones e invalidación — Aprenda cómo useQuery, queryKey, staleTime, gcTime, useMutation e invalidation trabajan juntos para gestionar el estado del servidor en React sin necesidad de efectos fetch escritos a mano.