Desarrollo medido con agentes de código LLM
Día 1 — Fundamentos + Discovery (proyecto nuevo)
Día 2 — Reverse-Discovery + Migración + Adopción (sistema existente)
Instructor: Andrés Massello · uscha.dev
La mayoría de los equipos que usan agentes de código todavía operan en un loop abierto:
Humano: "Revisá los errores de QA."
El agente diagnosticó, editó tests y código de producción en el mismo turno, corrió el build y declaró "diseño cerrado" — con cero puntos de decisión humana.
La ejecución fue competente.
La gobernanza falló.
Ese es exactamente el agujero que uscha cierra.
"Los gates que leen HECHOS bloquean.
Los que ADIVINAN sobre prosa, avisan."
Mecanismo central: un ledger determinístico que separa
lo que fue medido de lo que fue narrado.
No negociables. Todo lo demás se deriva de estas.
El agente no tiene permitido inventar la definición de "terminado".
Qué y por qué. Restricciones, no-objetivos, interfaces.
Criterios concretos y testeables de "hecho".
Si no está en el repositorio, el método no lo trata como verdadero.
El pipeline frena en el gate de merge. Sin excepciones. El agente prepara y mide; el humano decide.
Un test que no aserta algo no es un test. El gate nunca se debilita para que el agente pase.
El comportamiento actual se captura mecánicamente antes de cambiar. El agente jamás authorea archivos .approved.
SPEC.md · ACCEPTANCE.mdADR/ — decisionesRUBRIC.mdRegistro determinístico de mediciones, nunca de afirmaciones. Cero dependencias runtime. 11 stacks de lenguaje.
El chat es efímero. El ledger es la fuente de verdad.
Los loops existen pero están acotados. Escalan cuando no pueden converger.
Convierte una idea vaga en un paquete completo y versionado de SPEC + ACCEPTANCE mediante interrogación estructurada.
Un servicio chico y realista en contexto retail/pagos.
Punto de partida (idea vaga):
"Necesitamos algo que decida si un reembolso está permitido según fecha de compra, categoría de producto y nivel del cliente."
Vamos a caminar el recorrido medido completo desde esta idea hasta la primera implementación con compuertas.
Invocar /uscha-discovery con la idea vaga.
El agente interroga: ¿ventanas de tiempo? ¿categorías? ¿reglas por nivel? ¿casos borde? ¿no-objetivos?
El humano responde (o corrige).
El agente escribe SPEC.md + ACCEPTANCE.md en el repositorio.
El humano revisa y aprueba el paquete antes de cualquier código.
Todavía no se escribió código. La definición de "hecho" ya está cerrada.
# Motor de política de reembolsos
Objetivo: Decidir elegibilidad de reembolso de una orden completada.
Entradas: order_id, request_timestamp
Reglas (iniciales):
- Estándar: ≤ 30 días desde la compra
- Nivel Premium: ≤ 60 días
- Categoría "Digital": nunca reembolsable después de la descarga
No-objetivos: ejecución de pago, restock de inventario, UI
Restricciones: función pura de decisión, determinística, sin efectos secundarios
1. Dado un cliente estándar con orden de 15 días → eligible = true
2. Dado un cliente estándar con orden de 35 días → eligible = false
3. Dado un cliente premium con orden de 45 días → eligible = true
4. Dada cualquier orden de categoría Digital después del flag de descarga → eligible = false
5. La función es pura: mismas entradas siempre producen la misma salida
6. Todos los casos de aceptación se expresan como tests automatizados que asertan
Estos se convierten en las primeras compuertas reales del ledger.
El agente nunca puede cerrar la historia solo. Se requieren evidencia + humano.
Convertimos una idea vaga en SPEC + ACCEPTANCE versionados,
y después corrimos el primer loop de desarrollo medido
que no puede cerrarse sin evidencia y aprobación humana.
Mañana: el mismo rigor aplicado a sistemas existentes.
Compuertas medidas aplicadas a sistemas que ya existen
y que ya importan.
Congela el comportamiento actual como una suite golden antes de cualquier modificación.
.received)La skill emite .received y FRENA. El agente tiene prohibido authorear archivos .approved — solo el humano promueve el golden.
Extrae hechos de un sistema existente cuando la documentación falta, está vieja o es incorrecta.
Realidad de partida:
Un módulo existente usado en producción durante años. Tests escasos. Las reglas de negocio viven en parte en comentarios de código y conocimiento tribal. El equipo quiere permitir que los agentes de código lo mejoren de forma segura.
Vamos a caracterizar → reverse-discovery → agregar una mejora medida → mantener el golden intacto.
Seleccionar el módulo (o un conjunto crítico de funciones).
Correr /uscha-characterize.
La suite golden se genera a partir del comportamiento observado (.received).
El humano revisa y promueve el golden (o ajusta las entradas).
A partir de este momento, cualquier desviación del golden se convierte en evidencia visible en el ledger.
Ahora extraemos las reglas reales que el código implementa.
Hechos observados (ejemplo):
- 10% de descuento si el carrito > $100
- Extra 5% si el cliente es "gold"
- Los productos Digitales nunca reciben el descuento por valor de carrito
- El descuento se aplica antes del impuesto
- Redondeo: banker's rounding a 2 decimales
Con estos hechos, el humano escribe el nuevo SPEC si decidimos evolucionar el módulo.
.approvedAsí es como dejás que los agentes toquen sistemas de producción sin perder el control.
El cambio cultural > la instalación de la herramienta.
/uscha-characterize → producir el .received y promover el golden/uscha-reverse-discovery → extraer las reglas reales/uscha-devloopnpx --yes @andresmassello/uscha@latest install --target claude
Lo medido le gana a lo narrado.
Los hechos bloquean. Las conjeturas avisan.
Los humanos aprueban.
Día 1 — Discovery convirtió una idea en compuertas medidas.
Día 2 — Reverse-discovery + caracterización nos dejaron evolucionar sistemas existentes sin perder el control.
Andrés Massello · uscha.dev · info@uscha.dev
Preguntas y discusión