Urazuke, el método de la evidencia — la escalera metodológica (versión 4)

Autor: Pablo Kuschniroff, asistido por Claude Code. Versión 4, iniciada el 18 de octubre de 2026 y actualizada con cada decisión posterior del registro (docs/DECISIONES.md); la fecha de arranque queda fija a propósito, para no reescribir la historia de versiones cada vez que una decisión nueva toca este documento. Este es un documento de trabajo que voy a seguir puliendo con cada proyecto que lo use; nada de lo que dice es doctrina cerrada todavía, aunque sí es, hasta donde yo sé, el primer destilado honesto de un método que ya tiene tres sistemas en producción a sus espaldas.

Antes de entrar en materia, una advertencia sobre cómo está escrito, porque importa. Lo escribí para personas que no vivieron estos proyectos conmigo: gente que quiere construir software con inteligencia artificial y que ese software dure, no gente que quiere aprender a programar ni coleccionar trucos de prompts. Por eso me tomo el tiempo de explicar, repito cuando hace falta, uso el lenguaje de todos los días, y dejo al final un glosario con cada sigla y cada expresión coloquial que se me escapa. Si en algún momento te topás con una palabra rara —"trinquete", "candado", "fail-closed", "PND"—, andá al glosario; está todo ahí. Y cuando leas una marca como Ref. 26, sabé que es un atajo a un caso real que cuento en el documento de referencias, con su fecha y su evidencia; podés ignorarla sin perder el hilo o seguirla si te interesa el detalle.

El repositorio público del método es github.com/pkuschnirof/urazuke. Ahí están este documento, los contratos de cada peldaño, el manual del curso y las referencias, en los ocho idiomas de NAC3.

El nombre

Urazuke (裏付け) es una palabra japonesa que nombra el respaldo que tiene una afirmación: lo que la sostiene por detrás (literalmente, "el forro de atrás"). El verbo urazukeru es "respaldar con pruebas". La elegí el 17 de octubre de 2026, después de descartar varios nombres por colisiones con empresas y proyectos existentes, y la elegí porque dice exactamente lo que el método pide: que cada afirmación del modelo venga con su respaldo, y que el respaldo se pueda verificar sin leer el código. El nombre no se traduce; el subtítulo, "el método de la evidencia", sí: the evidence method, o método da evidência, la méthode de la preuve, die Nachweis-Methode, il metodo del riscontro, 裏付けの方法, 验证方法. En este documento, "la escalera" es la estructura del método —sus veinticuatro peldaños— y "Urazuke" es el método entero.

De qué se trata

Quiero ser claro sobre lo que estoy enseñando y lo que no. No estoy enseñando una herramienta. Estoy enseñando un método: qué hacer en qué orden, qué pedirle al modelo en cada momento, qué tiene que entregarte, y cómo saber —sin leer código— que lo que te entregó está completo. La apuesta es que cualquier persona, con cualquier herramienta de inteligencia artificial que sirva para programar, pueda construir software conversando con un modelo en vez de tipear el código a mano, y que lo que salga sea robusto, esté listo para producción y, esto es lo importante, no requiera que el dueño del proyecto revise una sola línea de código. Y quiero ser igual de claro sobre lo que no es: no es un proceso para hacer sistemas más rápido. Es un proceso para hacer sistemas operables y mantenibles sin que nadie necesite comprender un solo bit de su código, porque el código lo comprende y lo mantiene el marco agéntico que lo escribe. La velocidad, cuando aparece, es una consecuencia, y por eso en este documento no hay plazos: el tamaño y la complejidad de cada sistema los pone, y el método solo pone el orden.

Una aclaración que me pidieron que deje por escrito, porque la frase anterior se presta a una lectura que no es la mía: "no requiere que el dueño revise una sola línea de código" no es lo mismo que "está pensado para que programe gente sin conocimientos de sistemas". No lo está. El objetivo primario de este método no es bajar la vara técnica para que cualquiera pueda construir software sin saber nada de cómo se construye software: es darle a quien tiene que responder por un sistema un anclaje metodológico para que lo que un modelo construye salga con la solvencia de la ingeniería de sistemas de siempre, contrarrestando las debilidades con las que los modelos aplican esos mismos principios cuando nadie se los exige por escrito. Que el dueño no lea código es una consecuencia de dónde puse las compuertas y de qué puede verificar un humano sin leer una implementación, no la promesa de que cualquiera, sepa lo que sepa, puede dirigir un proyecto de software sin entender nada de lo que está dirigiendo. El perfil que en realidad piden los contratos está en el medio: alguien que corre un comando, maneja una credencial, restaura un respaldo, entiende lo que le dice la cuota de CI, y sabe reconocer cuándo lo que el modelo le entregó no alcanza — no un lego puro, y tampoco alguien que ya sabe programar.

Y otra aclaración, sobre el costo. Seguir esta escalera gasta más tokens que pedirle al modelo que resuelva todo de una sola pasada: cada peldaño agrega un prompt, una verificación propia, un artefacto que el modelo también tiene que sostener. Lo que no se ve a simple vista es lo que ahorra. Un sistema construido sin estas compuertas tiende, antes o después, a necesitar reingeniería: volver atrás sobre un dimensionamiento que no se hizo, perseguir un error que un test en rojo hubiera atrapado en el peldaño 8, reescribir lo que nadie auditó a tiempo. Esa reingeniería, en tokens, en tiempo y en plata, sale sobradamente más cara que el prompt de más que cuesta cada peldaño. Lo gasto adelante, con cabeza, para no gastarlo el doble atrás, a ciegas.

Suena ambicioso, y lo es. Pero tengo algo que casi nadie tiene: tres sistemas reales que construí exactamente así, que hoy funcionan con clientes de verdad, y de los que extraje cada regla que sigue. Así que la pregunta que me hago no es "¿se podrá?", porque ya se pudo. La pregunta es "¿qué hice, en qué orden, y qué de todo eso es lo que realmente hizo la diferencia?". Esta escalera es mi respuesta, y es la base de tres cosas: la documentación del método, la práctica que van a hacer los alumnos del curso, y los manuales. Más adelante la voy a exportar como un flujo de ejecución dentro de mi herramienta, para que sea la herramienta la que guíe el método y no la memoria de uno.

De dónde sale el método, y qué no quiero que se malinterprete

Hay una lectura fácil de todo esto que quiero desarmar antes de que se instale: la de que el método es una colección de parches que fui poniendo después de cada golpe. No es así, y me importa decirlo con precisión porque cambia cómo hay que leer cada peldaño.

El método sale de dos factores que se combinaron, y ninguno de los dos alcanza solo. El primero es mi propio conocimiento de la ingeniería de sistemas. Llevo muchos años aplicando lo que cualquiera que venga de sistemas reconoce enseguida: relevamiento antes de diseñar, requisitos escritos, dimensionamiento con números, diseño, construcción, pruebas como evidencia, despliegue reproducible, operación, auditoría periódica, documentación como parte del producto. La mayor parte de lo que exijo en los veinticuatro peldaños es lo que siempre exigí en un proyecto bien llevado. No lo inventé para los modelos; lo traje de antes.

El segundo factor es lo que los incidentes de estos cinco meses me mostraron, uno tras otro: dónde los modelos aplican esos principios de manera frágil. Un modelo sabe perfectamente qué es un test, qué es una causa raíz, qué es un dimensionamiento; si le preguntás, te lo explica mejor que muchos ingenieros. Pero en la práctica dice que probó y no probó, estima con cara de seguro un dato que solo el negocio tiene, llena un hueco en las reglas de negocio con lo que le pareció razonable, reporta de más porque fue entrenado para ser útil, y construye un medidor que miente sin darse cuenta. Cada uno de esos casos, que cuento en las referencias, me dijo exactamente dónde había que apretar: dónde un principio que para mí era obvio necesitaba convertirse en una cláusula explícita del prompt, en una compuerta, en una verificación que yo hago sin leer código.

Entonces, cuando en un peldaño digo "esto lo impuse después de tal incidente", no estoy diciendo que el principio nació ahí. Estoy diciendo que ahí comprobé que el modelo no lo aplicaba solo, y que había que exigírselo por escrito. El método es ingeniería de sistemas de siempre, aplicada con la rigidez que hace falta para un constructor que no se cansa y al que no se le puede creer sin evidencia. Las cicatrices son la prueba de dónde hace falta la rigidez, no el origen de los principios.

Los tres casos de uso del método

Antes de seguir, una bifurcación que en las primeras versiones no estaba y que un lector me pidió con razón. Este documento describe la escalera mirando una carpeta vacía: el peldaño 0 decide si el proyecto se encara, el 4 despliega el esqueleto sin funcionalidad, el 5 abre el primer bloque. Es el caso más claro para aprender, y no es el más frecuente. El método tiene tres casos de uso, y conviene saber en cuál estás antes de abrir el agente, porque cambia por dónde se entra:

1. Proyecto nuevo. Carpeta vacía y un dueño con un pedido. Se entra por el peldaño 0 y se suben los veinticuatro en orden. Es lo que describe este documento, con sus contratos y el manual del curso.
2. Evolutivo-correctivo sobre un sistema hecho con el método. El sistema ya subió la escalera: tiene contrato, mapa, pendientes cerrados con evidencia, batería, despliegue y manuales. Se entra por el peldaño 5, abriendo un bloque, y se sigue el bucle; el 13 periódico; el 23 al cierre de cada etapa. Es la fase 4 de la línea de tiempo (Parte B).
3. Evolutivo-correctivo sobre un sistema hecho sin el método. Un sistema que corre, con usuarios, hecho por otro o por uno mismo sin evidencia, al que hay que corregir o hacer crecer. No se entra por el 0 ni por el 5: se entra por un tramo de normalización de ocho estaciones (N0 a N7) que recupera, por autodescubrimiento y con marcas de fuente, todos los insumos que los peldaños del arranque producen, arma un cinturón de seguridad alrededor del sistema sin reescribirlo, y recién después abre el bucle en modo correctivo o evolutivo. Ese camino está en una página propia, el camino evolutivo-correctivo, y tiene su parte del curso con un segundo proyecto guía.

Lo que queda afuera, nombrado: la migración tecnológica no es un caso de uso del método; es otro proyecto, y en general cae en los criterios excluyentes del peldaño 0.

La IA no interrumpe el método: lo continúa

Esta es la tesis que abre todo, y la pongo primero porque desarma la objeción más común antes de que aparezca: "¿cómo vas a confiar en código que escribió una máquina?".

Mi respuesta es que la industria ya dejó de confiar en el autor del código hace veinte años. Cuando el grueso de la escritura pasó a equipos junior, tercerizados o rotativos, la revisión línea por línea se volvió imposible de sostener. Y lo que creció en su lugar fue todo lo que hoy damos por sentado: los tests automatizados, la integración continua, los criterios de aceptación, los pipelines que no dejan pasar nada sin verde, el "shift left" de las pruebas, el control de calidad como función independiente. Esa fue la respuesta de la ingeniería de sistemas a "el que escribe no es confiable": no leerle el código, exigirle evidencia.

Poner a un modelo a escribir, entonces, no es un salto al vacío. Es cambiar un autor en el que ya no confiábamos por otro en el que tampoco, y para el cual ya teníamos armado el aparato de verificación. Eso debería tranquilizar, no inquietar. Y encima el nuevo autor es más barato, más rápido, y —a diferencia del junior— no se ofende cuando le pedís que pruebe en rojo.

Por eso este método se apoya, sin disimulo, en la ingeniería de sistemas clásica. El esqueleto es el de siempre. No podía ser de otra manera, porque los problemas son los de siempre: no saber cuántos datos va a haber, no saber qué quiere el cliente, no saber si lo que se construyó es lo que se pidió. La IA no cambió los problemas; cambió quién hace cada parte y a qué costo. Hasta el criterio de elegibilidad X2 del peldaño 0 es ingeniería clásica: testeabilidad como condición de contrato.

Qué es viejo y qué es nuevo en esto

Lo viejo, y conviene decir que es viejo: el esqueleto de etapas, la independencia del que verifica respecto del que construye, los tests como evidencia, la documentación como parte del producto, el relevamiento antes del diseño.

Lo que sí cambia, y es donde está mi aporte, son tres cosas:

1. Dónde va el esfuerzo del humano. En el método clásico el humano escribe la especificación, escribe el código, y otro humano lo revisa. Acá el humano hace dos cosas solamente: decide, y verifica artefactos. Todo lo demás —redactar, construir, probar, medir, documentar— lo hace el modelo. Por eso cada peldaño termina en una "verificación de completitud sin leer código": es el lugar exacto donde el humano sigue siendo imprescindible, y ninguno más.

2. El autor también fabrica la evidencia. Este es el único punto genuinamente nuevo, y es el matiz que justifica tres peldaños enteros. El junior escribía código dudoso, pero no fabricaba la evidencia: los tests y las mediciones los armaba otro, o al menos otro los miraba. El modelo, en cambio, produce el código y el test y el medidor y el reporte, en la misma sesión, con la misma seguridad en la voz cuando está bien y cuando está mal. Lo vi: el medidor que mintió dos veces Ref. 36, el error de autenticación reportado como "éxito" Ref. 43, las tres de cuatro aseveraciones que estaban mal. Entonces "revisar evidencia en vez de código" sigue siendo el principio correcto, pero la evidencia tiene que probarse a sí misma: el test visto en rojo (peldaño 8), el instrumento con su guarda (peldaño 7), el reporte que separa lo verificado de lo creído (peldaño 12), el auditor distinto del constructor (peldaño 13). No es una inquietud nueva: es la misma disciplina de independencia del control de calidad, llevada un paso más adentro.

3. El costo de los artefactos. En el método clásico la documentación era cara, entonces se hacía una vez y envejecía. Acá regenerarla es gratis, entonces la regla pasa a ser "en el mismo commit" y "reproducible a mano, sin IA". Lo que antes era un ideal incumplible pasa a ser una compuerta.

Para el curso y para la presentación pública, esto define el posicionamiento con honestidad: no es "la nueva forma de programar"; es ingeniería de sistemas aplicada a un constructor que no se cansa y al que no se le puede creer. A los que vienen de sistemas les suena familiar y les baja la desconfianza; a los que vienen del vibecoding les da lo que no tienen, que es justamente el esqueleto. Y me diferencia de las herramientas que venden velocidad y omiten el esqueleto entero.

Parte A — Cómo leer cada peldaño

Cada peldaño tiene ocho partes, siempre las mismas, para que se puedan comparar:

• Intención: qué busca, en una frase.
• Cuándo: en qué momento del proyecto se sube, y si se sube una vez o se repite. Esta parte es nueva en la versión 4 y la explico en detalle en la Parte B, porque un método sin línea de tiempo es una lista de buenas intenciones.
• Entradas: qué tiene que existir antes para poder subirlo.
• Artefacto: qué queda escrito o ejecutable cuando se sube. Siempre es algo concreto: un archivo, un test, un script.
• Compuerta: qué tiene que ser verdad para pasar al siguiente. Si no se cumple, no se sube.
• Quién decide: el dueño del proyecto, el agente, o nadie porque es automático.
• Fallo que evita: el tipo de problema que el peldaño previene, con una referencia corta al caso real donde lo comprobé.
• Contrato: el archivo donde está cómo se ejecuta: contexto, prompts, resultado, verificación, señales de alarma.

Y hay una parte más, que aparece sólo en seis peldaños y es una pieza transversal que cambia qué hay que leer: el Anexo H (ANEXO_HEURISTICAS.md). Son cuarenta y cinco reglas verificables —dieciocho de calidad del código y veintisiete de usabilidad—, cada una con su identificador estable, su severidad y el instrumento que la mide. No es un apéndice opcional: es obligatorio, y se engancha a la escalera en seis puntos. En el peldaño 2 entran sus dos entradas previas (el glosario del usuario y la lista de perfiles: las palabras que la gente usa de verdad para cada cosa, y quién es cada uno y qué viene a hacer). Y en los peldaños 5, 8, 9, 10 y 12 están sus cinco anclas —"ancla" quiere decir que la compuerta de ese peldaño no da verde si la pieza del anexo no está—. Esas cinco son exigencias mecánicas en la definición publicada de las compuertas, no recomendaciones: una herramienta que compila el método las va a pedir. Cada uno de esos seis peldaños lo dice en su ficha, con el enlace, y hay una comprobación en la cadena del método que se pone en rojo si alguna deja de decirlo. Nació de haberlo descubierto tarde: el anexo estuvo obligatorio y sin nombrar en este documento, y el primer lector que adaptó el método a otro formato se salteó veintisiete de las cuarenta y cinco reglas porque nunca supo que existían.

Dos aclaraciones importantes. Primero: la escalera es neutral respecto de la herramienta. Cada artefacto es un archivo, un test o un script; ninguno exige mi herramienta ni ninguna otra. Forge los automatiza (las compuertas, los comandos, el registro de pendientes), pero el peldaño existe sin Forge. Segundo: los peldaños están numerados en el orden en que se suben, y se agrupan en cuatro tramos: los del 0 al 4 son de arranque y se suben una vez por proyecto; los del 5 al 12 son el bucle que se repite con cada cambio; los del 13 al 20 son de salida a producción, y se suben una vez, antes del primer despliegue; y los del 21 al 23 son de operación, cuando el sistema ya está vivo. El 23 cierra el ciclo y vuelve al 0 para el próximo proyecto. Dentro de un tramo, el número dice el orden; entre tramos, el bucle se repite mientras los otros tres se suben una vez. Pero "no estrictamente secuenciales" no quiere decir "en cualquier orden": la Parte B dice exactamente cuándo se sube cada uno y qué pasa en el medio.

Parte B — La línea de tiempo: cuándo se sube cada peldaño y qué pasa entre medio

Esta parte no existía en las versiones anteriores, y su ausencia era un defecto serio: el método decía qué hacer y cómo verificarlo, pero no decía cuándo. Y "cuándo" es la mitad de un método. Un lector que se lo tomara al pie de la letra podía subir los veinticuatro peldaños uno tras otro y preguntarse en qué momento se hace, entonces, la infraestructura, la cadena de integración y despliegue continuos, la ingesta de los requerimientos, el desarrollo de la funcionalidad, las pruebas de punta a punta de todos los flujos, la mirada humana sobre las pantallas, y las pruebas humanas de aceptación. Todo eso pasa, y pasa en momentos precisos, entre los peldaños y dentro de ellos. Acá lo escribo.

B.0 El proceso entero, en un gráfico

Antes de las tablas, el dibujo. Está en notación de proceso (al estilo BPMN: eventos redondos, tareas rectangulares, compuertas en rombo, flechas de vuelta punteadas), y dice tres cosas que las tablas dicen peor. Primera: el proceso empieza afuera del método, en la ingeniería de requerimientos, que es un prerrequisito y además es permanente: no termina nunca, y cada requerimiento nuevo vuelve a entrar. Segunda: un requerimiento nuevo no entra solo al bucle; reinyecta en los peldaños de evaluación, porque puede cambiar los números con los que se decidió la arquitectura (¿sigue aguantando el "por diez"?), y de ahí para adelante. Tercera: el proceso termina en la ejecución manual de los casos de prueba por personas (peldaño 10), y lo que esa ejecución encuentra vuelve al bucle como requerimiento. El circuito se cierra con gente, no con máquinas. Cuarta, y el dibujo anterior a esta corrección no la mostraba: cuando lo que el sistema construye tiene consecuencia sobre el mundo (cobrar, enviar), el bucle se reabre después del peldaño 14, ya con los candados puestos, para construir esa parte en modo de ensayo antes de seguir hacia la cadena de producción (15). No es una vuelta al principio: es la misma compuerta de siempre (¿cierre de bloque?) corrida una vez más, ahora con la red de seguridad lista.

flowchart TB
  subgraph RE["Ingeniería de requerimientos · prerrequisito externo y permanente"]
    direction TB
    E0((Pedido del negocio)) --> RE1["Relevamiento: entrevistas, casos de uso, modelo de dominio, prototipos"]
    RE1 --> RE2["Requerimiento nuevo o cambiado"]
  end
  subgraph ARR["Arranque · peldaños 0 a 4, una vez"]
    direction TB
    P0["0 Elegibilidad"] --> P1["1 Contrato de convivencia"] --> P2["2 Definición y árbol semántico"] --> P3["3 Dimensionar"]
    P3 --> G1{"¿La arquitectura aguanta los números?"}
    G1 -- sí --> P4["4 Esqueleto con compuertas"]
    G1 -- no --> P3
  end
  subgraph LOOP["Bucle · peldaños 5 a 12, con cada cambio"]
    direction TB
    P5["5 Pendientes especificados"] --> P6["6 Decisiones escritas"] --> P7["7 Medir"] --> P8["8 Test en rojo y punta a punta"] --> P9["9 Calidad del código"] --> P10["10 Casos de prueba manual"] --> P11["11 Simetría"] --> P12["12 Reporte honesto"]
    P12 --> G2{"¿Cierre de bloque?"}
    G2 -- no --> P5
  end
  H1["Ejecución manual de los casos de prueba, por personas"]
  subgraph OUT["Salida a producción · peldaños 13 a 20, una vez"]
    direction TB
    P13["13 Auditoría"] --> P14["14 Candados"] --> P15["15 Cadena a producción"] --> P16["16 Observabilidad"] --> P17["17 Persistencia"] --> P18["18 Vulnerabilidades"] --> P19["19 Rendimiento"] --> P20["20 Documentación viva"]
  end
  D((Primer despliegue))
  subgraph OPS["Operación · peldaños 21 a 23"]
    direction TB
    P21["21 Monitoreo de recursos"] --> P22["22 Monitoreo de errores"] --> P23["23 Residente y retrospectiva"]
  end
  RE1 --> P0
  P4 --> P5
  RE2 -. "reinyecta: ¿cambian los números?" .-> P3
  RE2 --> P5
  G2 -- sí --> H1
  H1 -- "hallazgos = requerimientos" --> RE2
  H1 --> P13
  P14 -. "lo que tiene consecuencia se construye ahora, con los candados puestos" .-> P5
  P20 --> D --> P21
  P21 -. "desvíos = pendientes" .-> P5
  P22 -. "errores = pendientes" .-> P5
  P23 -. "vuelve al 0 para la etapa siguiente" .-> P0

Si el dibujo no se ve (el visor de markdown no dibuja mermaid), el texto de arriba lo describe entero; en la versión HTML se dibuja solo.

B.1 Las cinco fases de un proyecto

Un proyecto llevado con este método pasa por cinco fases. Las tres del medio son las que corresponden a los tramos del bucle, de la salida a producción y de la operación; la fase 1 es el tramo de arranque; y la fase 0 es la ingesta inicial, que el método también cubre aunque no sea un "peldaño" en sí. No pongo duraciones: dependen del tamaño y de la complejidad de lo que se pide, y una duración escrita se convierte en una expectativa falsa. Lo que no depende del tamaño es el orden.

Esta tabla es la del proyecto nuevo. Cuando el sistema ya existe y no nació con el método, las fases 0 y 1 se reemplazan por el tramo de normalización (lectura, cinturón, medir y ordenar) que está en el camino evolutivo-correctivo; las fases 2, 3 y 4 son las mismas.

En un proyecto con usuarios y consecuencias, lo que crece es el bucle: la funcionalidad. El arranque, la salida a producción y la operación tienen la misma forma en un sistema chico y en uno grande; cambia cuánto hay que medir, no qué.

B.2 Qué pasa entre peldaño y peldaño

Acá está lo que faltaba. Para cada fase, qué tareas de cada tipo se hacen y en qué momento exacto respecto de los peldaños. Leé la tabla por filas: cada fila es un tipo de trabajo, y cada celda dice cuándo se hace dentro de esa fase.

Un detalle que quiero subrayar porque es donde más se equivoca la gente que viene del vibecoding: las pruebas de punta a punta de todos los flujos no son una sola vez al final. Son tres veces, en tres escalas. Con cada pendiente, el flujo que ese pendiente tocó. Al cierre de cada bloque, todos los flujos que existen hasta ahí. Y antes de producción, todos los flujos con la versión exacta que se va a promover. Si solo hacés la tercera, llegás al final con un sistema que nadie probó de punta a punta durante semanas y la salida a producción se convierte en una semana de arreglos.

B.3 El ritmo del bucle: un bloque funcional típico

Un bloque funcional es un conjunto de entre cuatro y ocho pendientes relacionados, que juntos hacen algo que el negocio puede usar: "la agenda básica", "los recordatorios", "el reporte mensual". Así se ve por dentro:

1. Apertura del bloque. El dueño cuenta, en prosa, qué quiere para este bloque. El agente lo convierte en pendientes numerados, con su "cómo se verifica", y pregunta lo que no da para escribir un pendiente verificable (peldaño 5). El dueño prioriza.
2. Cada pendiente. El agente anuncia qué pendiente toma y por qué. Si en el camino aparece una regla de negocio que no está escrita, frena y pregunta (6). Si el pendiente depende de un número —cuántas consultas, cuánto tarda—, primero lo mide con un instrumento con test (7). Construye. Cuando termina, cierra en este orden: el test probado en rojo, verde, la regresión de los vecinos y una prueba de punta a punta del flujo tocado (8); la compuerta de calidad del código en verde (9); los casos de prueba manual del flujo, escritos para una persona (10); y, si el cambio tocó un contrato entre dos partes del sistema, el otro lado actualizado en el mismo commit (11). El reporte separa lo verificado de lo creído y declara los puntos ciegos (12). El dueño lee el reporte y mira la captura de la pantalla. No lee código.
3. Cierre del bloque. La batería completa de punta a punta en verde en el entorno de prueba. El dueño o un usuario de confianza ejecuta los casos de prueba manual del bloque (10) y anota qué pasó y qué falló; cada fallo vuelve al bucle como pendiente correctivo. Se lee el reporte de calidad del bloque (9). Se actualiza el manual de usuario con las pantallas nuevas (20, en el mismo commit). Recién entonces se abre el bloque siguiente.

En un día típico del bucle, lo que el método le pide al dueño es poco y puntual: contestar dos o tres preguntas de reglas de negocio, leer dos o tres reportes, mirar dos o tres capturas. Eso es todo. Si le está pidiendo más que eso, o el agente está preguntando lo que podría resolver solo (peldaño 1), o el dueño está leyendo código (y entonces algo del peldaño 8 o del 12 no está funcionando).

B.4 Los hitos humanos

Resumo en una lista los momentos en que un humano, el dueño o alguien de su confianza, tiene que mirar o usar el sistema. Son pocos, están en momentos precisos, y ninguno se puede delegar al agente:

• Fin del arranque: abrir la URL del entorno de prueba y ver el sistema vacío.
• Con cada pendiente que toca una pantalla: mirar la captura real del entorno de prueba.
• Al cierre de cada bloque: ejecutar los casos de prueba manual del bloque (10) en el entorno de prueba y anotar el resultado; lo que falla vuelve al bucle como requerimiento.
• Antes del primer despliegue a producción: pruebas de aceptación sobre todos los flujos, siguiendo todos los casos de prueba manual.
• En el peldaño 20: una persona que no programa sigue el manual de recuperación en el entorno de prueba.
• Después de cada despliegue a producción: verificar que la versión que corre es la que se quería, y hacer una pasada de solo lectura por los flujos críticos.
• Antes del primer despliegue, en el 19: leer los números de la prueba de carga con la tolerancia del negocio al lado, y el punto de ruptura.
• En cada ciclo del monitoreo (21 y 22): leer el reporte cíclico con el agente y decidir qué desvío y qué error se vuelven pendientes.

Todo lo demás —los tests, las mediciones, las auditorías, la documentación— lo hace el modelo y el humano lo verifica por el artefacto, no por el código.

B.5 Cómo entran los requerimientos: del relevamiento al árbol semántico y a los pendientes

Quiero detenerme en esto porque es donde la ingeniería de sistemas clásica tiene más que decir y donde el vibecoding la ignora con más entusiasmo. Un requerimiento no es una frase del cliente en un chat. Es una frase del cliente procesada por métodos que existen desde hace décadas y que siguen valiendo con un modelo al frente, porque el modelo es muy bueno aplicándolos si se lo pedís y muy malo aplicándolos si no.

Los métodos que uso, y que el método exige en cada fase:

• Entrevistas con el dueño, abiertas, en prosa, registradas. Son la fase 0. No intento que sean completas: intento que el agente detecte qué les falta.
• Casos de uso o historias de usuario, uno por flujo que el negocio puede nombrar: "la recepcionista carga un turno", "el paciente recibe el recordatorio". Cada uno tiene actor, disparador, pasos, resultado y excepciones. Son la unidad con la que se abre un bloque funcional.
• Modelo de dominio: las entidades del negocio, sus atributos, sus estados posibles y las transiciones entre estados. Es el corazón del árbol semántico (ver abajo) y lo que evita que el modelo invente estados que el negocio no tiene.
• Criterios de aceptación por historia, en la forma "dado tal situación, cuando pasa tal cosa, entonces se ve tal resultado". Son los que se convierten en el "cómo se verifica" de cada pendiente y, después, en el test de punta a punta.
• Prototipos de pantalla, aunque sean un dibujo. La vista humana de las pantallas empieza acá, antes de que exista código.
• Trazabilidad: cada requerimiento se puede seguir hasta el pendiente que lo implementa, el test que lo prueba y el commit que lo cerró. En el método la trazabilidad no es una matriz aparte: es el pendiente mismo, que cita su origen y su evidencia.

El árbol semántico. Es el artefacto que ordena todo esto y es el mapa que el agente lee en cada sesión (peldaño 2). Es un árbol, no una lista: el sistema en la raíz; debajo, los dominios o módulos; debajo de cada uno, sus actores, sus procesos (los casos de uso), sus entidades con sus estados, sus pantallas y sus integraciones externas; y colgando de cada nodo, los pendientes que lo tocan y las decisiones que lo afectan. Lo construye el agente a partir del relevamiento, lo corregís vos, y crece con cada bloque. Su valor es doble: le da al modelo el contexto exacto del nodo que va a tocar sin tener que leer todo el proyecto, y te da a vos una forma de verificar que el sistema que el agente entiende es el que el negocio pidió, sin leer código. Cuando un pendiente no cuelga de ningún nodo, o el árbol está incompleto o el pendiente está fuera de alcance; las dos cosas se ven en diez segundos.

La especificación detallada vive en el pendiente. En el método clásico había un documento de especificación de requerimientos, largo, que envejecía. Acá ese documento se descompone: cada pendiente lleva su propia especificación completa, y la suma de los pendientes es la especificación del sistema. Un pendiente bien escrito tiene: título; el nodo del árbol semántico del que cuelga; la historia o caso de uso que lo origina, con las palabras del cliente; la descripción detallada de lo que se pide; las reglas de negocio aplicables, con su decisión y su fecha; los datos que entran y salen; las pantallas afectadas, con el prototipo si lo hay; los casos borde y las excepciones; los criterios de aceptación; y cómo se verifica. El agente lo redacta a partir de tu pedido en prosa, pregunta lo que no da para especificar, y vos lo leés antes de que se construya. Leer una especificación de pendiente es lo más cerca que vas a estar de leer código, y es exactamente la distancia correcta.

Los pendientes cerrados son documentación. Esto es lo que cierra el círculo. Cuando un pendiente se cierra, no se borra ni se archiva vacío: queda con su especificación, la decisión que lo originó, la evidencia con la que se cerró (los números del rojo y del verde, la captura de la pantalla, el número medido), el commit, y la fecha. La cola de pendientes cerrados es, entonces, el historial funcional del sistema: qué se construyó, por qué, cuándo, y cómo se probó. De ahí salen el diario de cambios, las secciones nuevas del manual de usuario y, cuando alguien pregunta seis meses después "¿por qué el sistema hace esto?", la respuesta. El manual del curso enseña a exigir esta documentación al cierre de cada pendiente, en la misma sesión, como parte de la rutina del peldaño 5.

Parte C — Los veinticuatro peldaños

Van en el orden en que se suben. Los seis peldaños de calidad operativa (16 a 19 antes del primer despliegue; 21 y 22 después) son los que yo hacía sin nombrar: que el sistema se pueda ver mientras corre, que aguante el volumen para el que se dimensionó, que no tenga agujeros conocidos, y que, una vez en producción, nadie se entere de un problema por un usuario enojado. Los dos monitoreos terminan en el mismo lugar que todo lo demás: el bucle, como pendientes correctivos. Si sos principiante, cada contrato de esos seis, y los de los peldaños 9 y 10, empiezan con un párrafo que explica sus palabras en lenguaje de todos los días, y el glosario las tiene todas.

Y una advertencia antes de empezar a leerlos, porque sale más cara después que ahora: seis de los veinticuatro no se suben sólo con lo que dice su ficha. El peldaño 2 carga las dos entradas previas del Anexo H —el glosario del usuario y la lista de perfiles— y los peldaños 5, 8, 9, 10 y 12 cargan sus cinco anclas. Cada uno de los seis lo dice en su ficha, al final, en una línea que empieza con Anexo H. Si vas a aplicar el método, leé el anexo antes de abrir el peldaño 5: cinco de tus compuertas no dan verde sin él, y enterarse cuando la compuerta ya te detuvo es la peor forma de enterarse.

Peldaño 0 — ¿Este proyecto se puede encarar así? (la elegibilidad)

Hay algo previo a todo, que no está en ningún repositorio porque siempre llegó decidido: la decisión de si un proyecto se encara con este método o no. Es un criterio que viví en mi cabeza durante meses y que estoy terminando de escribir. Los dos criterios excluyentes ya los tengo claros, y salen de los proyectos que rechacé, no de los que acepté Ref. 46: los "no" definen la frontera mejor que los "sí". Los criterios que ponderan todavía los estoy calibrando, y así lo marco.

• Intención: decidir si un proyecto se encara con este método, y con un agente al frente, o no, ANTES de abrir el repositorio. Porque si entrás a un proyecto que no da, el método se degrada a "programar con IA" y ahí sí el dueño termina leyendo código.
• Cuándo: una sola vez, antes de cualquier otra cosa. Si el sistema ya existe, este peldaño se sube en su versión para legados (la estación N0 del camino evolutivo-correctivo), con cuatro criterios más y X2 medido pantalla por pantalla.
• Entradas: el pedido del cliente, el dominio del negocio, los datos, la tecnología, los entornos disponibles, y quién va a ser el dueño.
• Artefacto: una ficha de elegibilidad de una página, con los criterios puntuados y la decisión: va, no va, o va con condiciones.
• Compuerta: los criterios excluyentes están todos en verde, y el puntaje de los que ponderan supera el umbral (umbral que todavía no definí).
• Quién decide: el dueño. Hoy soy yo; la idea es que el método permita que lo decida otra persona con la misma ficha.
• Fallo que evita: meterse en un proyecto donde el agente no puede verificarse solo, o donde no hay un dueño del dominio que decida, y terminar con el humano revisando código línea por línea.
• Contrato: peldanos/peldano-00-elegibilidad.md.

Los dos criterios excluyentes.

Una precisión que vale oro para la neutralidad de herramienta: NAC3 (el protocolo que usa mi herramienta para que las pantallas se puedan operar por programa) NO es condición; es el medio con el que hoy lo logro. El criterio neutral queda así: la interfaz se puede ejecutar por programa, y cada elemento de la pantalla es accesible con sus distintos métodos (hacer clic, tipear, leer su estado), de modo que un test pueda recorrer la pantalla y después verificar el efecto en el backend. Una tecnología cuya interfaz no expone sus elementos a un "driver" (como Playwright, por ejemplo) queda afuera, aunque tenga repositorio.

Y una lectura que me parece importante: en el fondo X1 y X2 son la misma condición vista de dos lados. El agente tiene que poder verificarse solo, de punta a punta, y dejar la evidencia en el repositorio. X1 es la mitad "¿dónde queda la evidencia?"; X2 es la mitad "¿cómo se produce la evidencia?".

hipótesis Criterios que ponderan, todavía sin peso. Los dejo marcados como hipótesis hasta que los calibre con los primeros proyectos que usen el método de punta a punta.

Dos criterios que tenía en versiones anteriores (que el agente pueda probar solo, y que el proyecto sea nuevo o auditable) los absorbí en X2 y X1 respectivamente, porque son consecuencias y no criterios aparte.

Peldaño 1 — El contrato de convivencia (las reglas antes del código)

Antes de escribir una sola línea, poné por escrito cómo van a trabajar vos y el agente. Parece una formalidad, y no lo es: es lo que evita el ochenta por ciento de las frustraciones del mes uno. Pensá que el agente llega cada mañana sin memoria de ayer; lo que no esté escrito se lo vas a tener que repetir cada vez, y cada vez un poco distinto.

• Intención: fijar cómo trabajan el humano y el agente antes de la primera línea de código.
• Cuándo: una sola vez, inmediatamente después de la elegibilidad. Se revisa cuando un golpe lo exige.
• Entradas: nada del proyecto; es el primer archivo. De vos: tus preferencias de trabajo.
• Artefacto: un documento de estándares de calidad que diga, como mínimo: el tiempo del humano es sagrado (no se lo gasta en cosas que el agente puede resolver solo); cero deuda técnica, es decir, cuando algo se rompe se arregla de raíz y se agrega la regresión en la misma sesión; el alcance es exacto, ni más ni menos de lo pedido; se habla en el idioma del usuario; la documentación se actualiza en el mismo commit; y jamás se anuncia como hecho algo que no se hizo.
• Compuerta: el contrato está en el repositorio y se lee en cada sesión.
• Quién decide: el dueño. El agente puede proponer cambios, pero no edita el contrato por su cuenta.
• Fallo que evita: el agente que "ayuda" expandiendo el alcance porque le pareció buena idea; el que deja deuda "para después" (y el después nunca llega); y el que reporta como hecho lo que cree que hizo. Lo escribí por primera vez cuando llevaba dos semanas repitiendo lo mismo en cada sesión Ref. 1.
• Contrato: peldanos/peldano-01-contrato-de-convivencia.md.

Peldaño 2 — La definición del proyecto y la lectura obligatoria

Cada sesión del agente arranca de cero. Dale un mapa, corto, y obligalo a leerlo antes de tocar nada. Las dos mitades importan por igual: un mapa que nadie lee no actúa, y un mapa largo no lo lee nadie.

• Intención: que cada sesión arranque sabiendo qué es el proyecto, en qué estado está y qué decisiones ya se tomaron.
• Cuándo: se escribe una vez, después del contrato; se mantiene al día durante todo el proyecto, con cada decisión nueva.
• Entradas: el contrato (peldaño 1) y el relevamiento del negocio.
• Artefacto: un archivo de proyecto operativo, y acá va un énfasis: CORTO. Es el programa, no el historial. Más el árbol semántico del sistema (ver B.5): dominios, actores, procesos, entidades con sus estados, pantallas e integraciones, con los pendientes y las decisiones colgando de cada nodo. Más un archivo de estado vivo con lo que se está trabajando y las dudas abiertas.
• Compuerta: el agente lee el archivo de proyecto y el árbol semántico antes de tocar código, y se probó que los lee.
• Quién decide: el dueño define; el agente lo mantiene al día.
• Fallo que evita: dos, bien concretos. Trabajo descartable por no haber leído el mapa Ref. 9. Y el archivo de proyecto que crece hasta volverse ilegible Ref. 41: el archivo operativo y el libro de casos tienen que ser archivos distintos.
• Anexo H: acá entran las dos entradas previas del Anexo H, y entran acá porque todo lo que viene después las usa. Una es el glosario del usuario: las palabras que la gente usa de verdad para cada cosa, no las que usa el sistema. La otra es la lista de perfiles: quién es cada uno —administración, operación, consulta, cliente— y qué viene a hacer. De esas dos salen la matriz del peldaño 8, los casos por perfil del 10 y los criterios de aceptación por perfil del 5. Si no están, las cinco anclas del anexo no tienen de dónde salir.
• Contrato: peldanos/peldano-02-definicion-y-lectura.md.

Peldaño 3 — Dimensionar antes de diseñar la arquitectura

Este es el peldaño que más caro cuesta saltearse, y lo sé porque me lo salteé. Las decisiones estructurales se toman con números, y los números primarios los tiene el negocio, no el modelo.

• Intención: que las decisiones estructurales (qué motor de base de datos, si la interfaz es sincrónica o asincrónica, cuánta concurrencia) se tomen con números y no con gusto.
• Cuándo: una vez, antes de armar el esqueleto; se rehace si el negocio cambia de escala. Media página y una decisión en un proyecto chico.
• Entradas: un relevamiento de datos de volumetría hecho con el negocio, por naturaleza incompleto; y acceso de lectura al sistema anterior si existe. Hay datos que solo el negocio tiene y el modelo no puede inferir: por eso el prompt le exige evaluar si están completos y pedir los que falten, en vez de estimarlos con cara de seguro.
• Artefacto: un registro de dimensionamiento con opciones FIJAS (tres o cuatro opciones concretas) y la elegida; y las decisiones "asimétricas" declaradas explícitamente, por ejemplo "la interfaz de persistencia es asincrónica desde la línea uno aunque el primer motor sea sincrónico", porque si estás equivocado cuesta poco y si no lo hacés cuesta una fortuna.
• Compuerta: el dimensionamiento está registrado antes de armar el esqueleto.
• Quién decide: el dueño elige entre las opciones fijas; el agente las presenta con números.
• Fallo que evita: arrancar con un almacenamiento que no aguanta la volumetría y descubrirlo cuando cambiar la interfaz cuesta una etapa entera de reingeniería Ref. 15.
• Contrato: peldanos/peldano-03-dimensionar.md.

Peldaño 4 — El esqueleto con sus compuertas

Antes de que el sistema haga algo útil, tiene que arrancar, testearse y desplegarse VACÍO. Sí, vacío. Porque el camino a producción es parte del producto, y la única forma de saber que funciona es recorrerlo cuando todavía no hay nada que perder. Este es el peldaño donde se hace toda la infraestructura inicial y la cadena de integración y despliegue, y por eso es el más largo del arranque.

• Intención: tener un sistema que arranca, se prueba y se despliega sin ninguna funcionalidad todavía.
• Cuándo: una vez, al final del arranque, después del dimensionamiento y antes de cualquier funcionalidad. Es el cierre del tramo de arranque.
• Entradas: el dimensionamiento (peldaño 3), el relevamiento de entornos, y las credenciales del lugar donde se va a desplegar.
• Artefacto: el esqueleto con la integración continua en verde, la estructura de tests armada con un test de humo, un despliegue a un entorno de prueba que funciona y se corrió dos veces, y las compuertas del flujo declaradas por escrito.
• Compuerta: el esqueleto está en verde, la integración continua corre, y el despliegue al entorno de prueba funciona con cero funcionalidad. El dueño abrió la URL y vio la pantalla vacía.
• Quién decide: el agente ejecuta; el dueño aprueba visualmente.
• Fallo que evita: descubrir el despliegue un mes después del arranque y pagar cinco pendientes seguidos para que funcione, con funcionalidad en juego Ref. 32.
• Contrato: peldanos/peldano-04-esqueleto.md.

Peldaño 5 — El plan son los pendientes

Acá hay una idea que, cuando la agarrás, no la soltás más: no hay "plan" por un lado y "lista de tareas" por el otro. La lista de pendientes ES el plan. Y cada pendiente dice cómo se verifica, porque eso es lo que vos vas a mirar en vez de mirar el código.

• Intención: una única cola de trabajo, con orden y con compuerta, que sea la verdad del proyecto.
• Cuándo: se crea al abrir el primer bloque funcional, apenas termina el arranque; se usa en cada sesión durante todo el proyecto. Cada bloque nuevo arranca convirtiendo el pedido del cliente en pendientes.
• Entradas: el pedido del cliente para el bloque, las auditorías, y los hallazgos de las pruebas humanas.
• Artefacto: un registro de pendientes numerados, cada uno con su especificación detallada (ver B.5): el nodo del árbol semántico del que cuelga, la historia de origen con las palabras del cliente, la descripción, las reglas de negocio aplicables, los datos, las pantallas, los casos borde, los criterios de aceptación y cómo se verifica. Y, al cerrarse, la documentación del pendiente hecho: la evidencia, el commit, la fecha, lo que quedó decidido en el camino. Los pendientes cerrados son el historial funcional del sistema.
• Compuerta: ningún cambio entra sin pendiente especificado; y el pendiente se cierra con evidencia documentada, no con "listo".
• Quién decide: el dueño prioriza; el agente propone y ejecuta en orden.
• Fallo que evita: la especificación que "se supera" y queda obsoleta en dos semanas Ref. 17; y el trabajo del que seis meses después nadie sabe por qué se hizo Ref. 7.
• Anexo H: ancla 1 del Anexo H. Todo pendiente que toca una pantalla declara, además de lo de arriba, tres cosas más: el grupo de convergencia funcional al que pertenece (lo que la persona vino a hacer, que es por donde se agrupa la funcionalidad), los perfiles que la tienen, y un criterio de aceptación por perfil. Sin esa declaración el pendiente no pasa el peldaño, y no es una recomendación: es lo que la compuerta mide.
• Contrato: peldanos/peldano-05-pendientes.md.

Peldaño 6 — Las decisiones se escriben junto al código

El modelo, cuando encuentra un hueco en las reglas de negocio, lo llena. No se detiene a preguntar; completa con lo que le parece más probable, con la misma naturalidad con la que escribe lo demás. Por eso este peldaño no es "escribí las decisiones" sino "exigile que frene y pregunte cuando falte una", y cuando decidís, la decisión queda con tus palabras, tu nombre y la fecha.

• Intención: que cada regla de dominio o decisión estructural tenga dueño, fecha y lugar.
• Cuándo: en cada sesión del bucle, cada vez que el agente se topa con una regla no escrita. Suelen ser dos o tres por bloque funcional. También en el arranque (peldaños 0 y 3) y en la salida a producción (14 y 15).
• Entradas: la conversación con el dueño. Es el único insumo.
• Artefacto: la decisión escrita en el commit y en un registro de decisiones, con las palabras textuales. Si el dueño no contestó y el agente tuvo que elegir, queda marcada como "decisión por omisión" para revisarla.
• Compuerta: una regla de negocio no entra al código sin su frase de origen.
• Quién decide: el dueño. Siempre. Sin excepciones.
• Fallo que evita: discutir seis semanas después por qué algo es así; y, peor, el agente inventando reglas de dominio porque le parecieron razonables. La práctica de escribir la regla en el commit con fecha y dueño viene de la Obra Social Ref. 29, y la de congelar decisiones antes de construir, de mi herramienta Ref. 5.
• Contrato: peldanos/peldano-06-decisiones.md.

Peldaño 7 — Medir antes de construir, con un instrumento que también se verifica

Este es, para mí, el peldaño más adulto de todos, y el que más tardé en formalizar porque daba por sentado que un modelo lo aplicaría solo. No lo aplica. La regla es: ningún número que decide algo sale de una impresión; sale de un medidor que vive en el repositorio, que tiene un test, y que vos podés correr. Y el medidor también se verifica, porque los medidores mienten.

• Intención: que todo número que alimenta una decisión salga de un instrumento con test, y que el instrumento mismo se audite.
• Cuándo: en el bucle, cada vez que un pendiente depende de un número o de una hipótesis de causa, ANTES de construir. En el arranque, el dimensionamiento es el primer caso. En un proyecto chico, "medir" es contar con un comando y anotar el número con la fecha.
• Entradas: la hipótesis, del dueño o del agente, y acceso a lo que se quiere medir.
• Artefacto: el medidor con guarda en el repositorio; el número con su comando y su fecha; la auditoría en dos direcciones; lo aproximado marcado; y, si corresponde, un presupuesto por camino apretado a lo medido y protegido por un test.
• Compuerta: las cinco reglas: medidor con guarda; si el instrumento no existe se construye; se audita en dos direcciones; lo aproximado se marca; y el que ejecuta verifica los números del que planificó.
• Quién decide: el número. El dueño trae la hipótesis; el agente la mide antes de construir.
• Fallo que evita: los medidores que mentían y el plan con tres de cuatro números mal Ref. 36; el trinquete en cero que no veía 84 llamadas Ref. 35. Las reglas las escribí yo, en sesión, antes de que fueran doctrina Ref. 45.
• Contrato: peldanos/peldano-07-medir.md.

Peldaño 8 — Tests como candados, probados en rojo

Un test que nunca viste fallar no sabés si prueba algo. Por eso acá la regla no es "escribí tests"; es "demostrá que el test se pone en rojo contra el código viejo, después en verde, y después que la regresión sigue en verde". Y las pruebas de punta a punta, desde la pantalla hasta el backend, son las que reemplazan tu lectura del código.

• Intención: que cada comportamiento que importa tenga un test que FALLA si se rompe, y que se sepa con certeza que falla.
• Cuándo: con cada pendiente del bucle, al cerrarlo. La prueba de punta a punta del flujo tocado, en el mismo cierre. La batería completa de punta a punta, al cierre de cada bloque y antes de cada despliegue a producción.
• Entradas: el cambio ya implementado y el pendiente con su "cómo se verifica".
• Artefacto: el test nuevo, la salida en rojo como recibo (el comando, la versión contra la que corrió, los números, el código de salida: lo que hace falta para volver a correrlo con un comando), la salida en verde con números, la regresión de los vecinos en la misma sesión, y el commit que dice contra qué se probó en rojo.
• Compuerta: rojo demostrado con recibo, verde, regresión en verde. Y el agente no simula justamente la parte que quiere probar.
• Quién decide: el agente ejecuta y reporta; el dueño lee el reporte, no el test.
• Fallo que evita: los tests que pasan porque no prueban nada, y el verde que esconde un bug Ref. 44. El caso de los contadores es el ejemplo completo de un test probado en rojo contra el criterio viejo Ref. 26.
• Rojo del primer bloque: cuando la versión anterior no tiene el módulo, el rojo se prueba por mutación (un defecto plantado, el test en rojo, el diff en el recibo), no con un archivo que no carga.
• Anexo H: ancla 2 del Anexo H. El mismo pendiente carga el test de la matriz de funcionalidad por perfil: una tabla que dice qué puede hacer cada perfil, de la que se derivan el menú, las rutas y los permisos en vez de escribirlos tres veces en tres lugares. El test de punta a punta compara, por cada perfil, lo que se puede alcanzar contra su fila de la matriz: ni menos ni más. Es la forma de atrapar al que ve un botón que no le corresponde, y al que tiene el permiso y no encuentra la pantalla.
• Contrato: peldanos/peldano-08-tests-en-rojo.md.

Peldaño 9 — Calidad del código verificada por máquina, con compuerta

El dueño no lee el código, y ese es el punto. Pero el código lo va a mantener alguien, y un código que funciona hoy y es ilegible mañana es deuda que se cobra en el mes tres. Si nadie lo lee, lo tiene que mirar una máquina: en cada commit, lo que un revisor humano miraría, convertido en un número con un límite. Lo hice en todos mis proyectos sin nombrarlo como peldaño.

Y acá conviene tener a mano la frase que separa este peldaño del anterior, porque es la confusión más cara del oficio y se resuelve en nueve palabras: la cobertura cuenta pruebas; el rojo dice si sirven. Un número de cobertura del noventa por ciento te dice cuánto código ejecutan los tests, y no te dice nada sobre si alguno de esos tests se pondría en rojo si el comportamiento se rompe. Eso lo dice el peldaño 8, y lo dice de la única forma que no se puede fingir: viendo el rojo. La cobertura es un número de este peldaño; el rojo es el recibo del anterior. (La formulación es de la primera adaptación del método a otro formato, acreditada en la Parte F.)

• Intención: que la calidad del código se verifique por máquina en cada commit, con la construcción en rojo como consecuencia, y que nunca se degrade sola.
• Cuándo: se monta al abrir el primer bloque funcional y corre en cada push; cada pendiente se cierra con la calidad en verde, después del test en rojo (8); el reporte se lee con el dueño al cierre de cada bloque. En un legado, la primera corrida es la línea base.
• Entradas: la integración continua (4), código de al menos un pendiente cerrado, y los límites decididos por el dueño (tamaño de archivo y de función, para empezar).
• Artefacto: linter y formateador con una sola configuración; límites de tamaño y complejidad; detección de duplicación y código muerto; cobertura con trinquete; tipos si el lenguaje lo permite; docs/CODE_QUALITY.md con cada límite y su valor medido; la compuerta en docs/GATES.md. Obligatorias en cualquier proyecto con usuarios, opcionales solo sin usuarios reales, las pruebas de mutación (errores plantados a propósito, contados por cuántos atrapan los tests), con su puntaje por bloque junto a la cobertura.
• Compuerta: nada se fusiona con la calidad en rojo; ninguna excepción al linter sin razón escrita; ningún límite subido para pasar.
• Quién decide: el dueño fija los límites y decide qué se arregla ahora y qué se tolera con fecha; el agente mide y arregla en el mismo commit.
• Fallo que evita: el componente de más de dos mil líneas y el archivo de casi diez mil que una auditoría encontró porque ningún límite los había frenado Ref. 41; el número de calidad que empeora sin que nadie lo vea Ref. 35.
• Anexo H: ancla 3 del Anexo H, y es la más grande de las cinco: acá la compuerta se extiende de la calidad del código a la usabilidad. El catálogo de las cuarenta y cinco reglas está declarado y activo por grupo; cada regla activa tiene su instrumento, su severidad y su verificador; cada regla apagada tiene su registro con motivo, quién lo autoriza y fecha de revisión —apagada sin registro es rojo, que no es lo mismo que la regla ausente—; cada umbral que el dueño no declaró se publica como no declarado en vez de inventarse; y el reporte sale con las dos cifras y la huella del conjunto de reglas. Un sistema puede pasar la calidad del código con honores y ser inusable; esta ancla es la que lo impide.
• Contrato: peldanos/peldano-09-calidad-de-codigo.md.

Peldaño 10 — Los casos de prueba manual se escriben junto con la funcionalidad, y los ejecutan personas

Las pruebas automáticas las escribe y las corre el modelo, y prueban lo que el modelo entendió. Falta la prueba que hace una persona con sus ojos y sus manos, siguiendo un guion. El guion lo escribe el mismo que construyó la funcionalidad, en el mismo momento, a partir de los criterios de aceptación; lo ejecutan personas al cierre de cada bloque, en la aceptación y después de cada despliegue; y lo que falla vuelve al bucle como requerimiento. Es el cierre del circuito que el gráfico del proceso muestra.

• Intención: que toda funcionalidad nazca con su caso de prueba manual, escrito para una persona que no sabe cómo está hecho el sistema, y que cada ejecución humana reinyecte lo que falla como pendiente.
• Cuándo: con cada pendiente, al cerrarlo, después del test en rojo (8) y de la calidad (9). Ejecución por personas al cierre de cada bloque, antes del primer despliegue (aceptación) y después de cada despliegue, en solo lectura.
• Entradas: los criterios de aceptación del pendiente (5), el entorno de prueba con datos, y la decisión de quién ejecuta y cuándo.
• Artefacto: docs/MANUAL_TESTS.md con un caso por flujo tocado (identificador, pendiente, precondición, pasos con lo que se hace y lo que se ve, resultado esperado con efecto en el backend verificable por una persona, datos, tabla de ejecuciones); las ejecuciones registradas; un pendiente correctivo por fallo.
• Compuerta: ningún pendiente que toque una pantalla se cierra sin su caso; ninguna ejecución sin fecha y nombre; ningún fallo sin pendiente con las palabras de la persona.
• Quién decide: el dueño o un usuario de confianza ejecuta; el agente escribe los casos y abre los pendientes; el modelo nunca marca un caso como ejecutado.
• Fallo que evita: la prueba humana sin guion que encuentra cosas distintas cada vez, y el hallazgo humano que se arregla en el momento y se pierde; el menú desplegable incómodo que ningún test vio y la encargada sí, en el proyecto guía del curso.
• Anexo H: ancla 4 del Anexo H. Cada caso manual se corre una vez por cada perfil afectado, y los perfiles salen de la matriz del peldaño 8, no de la memoria de quien ejecuta. Un caso corrido con un solo perfil no cuenta como ejecutado: la mitad de los problemas de permisos y de menú sólo se ven desde el perfil que no es el del que construyó.
• Contrato: peldanos/peldano-10-casos-de-prueba-manual.md.

Peldaño 11 — Simetría entre productor y consumidor, y el registro de anti-patrones

Cuando cambiás una punta (el servidor, la base, un robot), la otra punta (la pantalla, un contador, un reporte) tiene que cambiar en el mismo commit. El principio que lo sostiene es que toda lista tiene un solo dueño. Y los errores que ya pagaste una vez se anotan con su verificación automática, para no pagarlos dos veces.

• Intención: que un cambio en una punta arrastre la otra, siempre, en el mismo commit.
• Cuándo: con cada pendiente que toca un contrato entre dos partes del sistema; el mapa de contratos se construye al abrir el segundo bloque funcional, cuando ya hay pantalla y servidor; el registro de anti-patrones crece cada vez que algo se rompe por segunda vez.
• Entradas: el mapa de quién produce y quién consume cada contrato; el registro de anti-patrones.
• Artefacto: el servidor define la lista y el consumidor la lee; el mapa productor/consumidor; el registro de anti-patrones con olor, causa raíz, arreglo y detección temprana.
• Compuerta: automática: el agente busca el otro lado antes de dar por cerrado un cambio.
• Quién decide: nadie; es automático.
• Fallo que evita: el contador que no coincide con la consulta Ref. 26; dos copias del mismo módulo que se desincronizan Ref. 41. La solución de una sola fuente la impuse en la Obra Social Ref. 27.
• Contrato: peldanos/peldano-11-simetria-y-antipatrones.md.

Peldaño 12 — Verificación honesta y reporte proporcional

Si no vas a leer código, el reporte del agente tiene que ser confiable, y eso no pasa solo. El modelo fue entrenado para ser útil y completo, y un reporte que dice "esto no lo pude verificar" se siente menos útil que uno que dice "listo". Entonces exigile explícitamente las malas noticias, los puntos ciegos y lo que no hizo.

• Intención: que el reporte del agente sea confiable sin que el dueño lea código.
• Cuándo: en cada reporte, de cada pendiente, durante todo el proyecto. Es la forma que tiene que tener todo lo que el agente te dice.
• Entradas: el trabajo hecho y el pendiente que lo pedía.
• Artefacto: un reporte con tres bloques: verificado (con la prueba al lado), creído (y por qué no se probó), puntos ciegos (lo que no puede ver desde donde está). Cubre cada ítem pedido. Las malas noticias primero.
• Compuerta: ninguna afirmación sin su prueba. "Listo" no se dice a secas. Ante un "sigue roto", primero se compara la versión publicada con la que tiene el arreglo.
• Quién decide: el dueño confía, o pide la prueba. Nunca revisa código.
• Fallo que evita: el error reportado como éxito y los reportes que declaraban verificado lo que no lo estaba Ref. 43; el turno que trabajó invisible una hora cuarenta y tres Ref. 16. La regla de honestidad de verificación la escribí en junio Ref. 8.
• Anexo H: ancla 5 del Anexo H. El reporte informa también los grupos del anexo: qué se midió, qué quedó sin medir y qué regla está apagada con su registro. Es la misma regla de honestidad aplicada al anexo: una regla que la instalación no sabe medir se reporta como no medida, nunca como verde.
• Contrato: peldanos/peldano-12-verificacion-honesta.md.

Peldaño 13 — La auditoría periódica como insumo del plan

Cada tanto hay que mirar el sistema entero con ojos frescos, y lo que se vea no va a un informe que se archiva: va a la cola de pendientes. La parte importante es "ojos frescos": que audite alguien que no construyó, porque el que construyó comparte sus propios supuestos. Alcanza con otra sesión del modelo, con otro archivo de instrucciones.

• Intención: mirar el sistema completo cada tanto y convertir lo que se ve en pendientes.
• Cuándo: obligatoria antes del primer despliegue a producción (abre el tramo de salida). En operación, cada uno o dos meses según el ritmo de cambio, y al cierre de cada etapa grande.
• Entradas: el repositorio entero y la producción en solo lectura.
• Artefacto: un informe con hallazgos graduados, cada uno con ubicación, riesgo, evidencia y prioridad; notas por dimensión; y los hallazgos urgentes ya convertidos en pendientes.
• Compuerta: cada hallazgo urgente tiene un pendiente abierto antes de dar la auditoría por cerrada.
• Quién decide: el dueño prioriza los hallazgos.
• Fallo que evita: consultas que leen tablas enteras Ref. 18; dos puertas de administrador que nadie vio hasta que las miró otro Ref. 40; una vulnerabilidad conocida y un componente enorme Ref. 41.
• Contrato: peldanos/peldano-13-auditoria.md.

Peldaño 14 — Fail-closed, candados y cero daño silencioso

Ante la duda o el fallo, el sistema NO actúa. Y lo dice. Suena obvio, pero es lo contrario de lo que el software hace por defecto, que ante la duda sigue adelante. Este peldaño va antes de construir las funcionalidades que actúan sobre el mundo, no después.

• Intención: que el sistema, ante una duda o un fallo, no actúe, y avise.
• Cuándo: en el tramo de salida a producción, antes de construir cualquier funcionalidad que cobre, envíe, apruebe o borre; se revisa con cada acción nueva con consecuencias. Las automatizaciones nuevas arrancan en modo de ensayo y se habilitan después de mirar su registro unos días.
• Entradas: el relevamiento de las acciones con consecuencia, hecho con el dueño.
• Artefacto: la tabla de candados: cada acción con su reversibilidad, su candado, su camino de vuelta; un test por candado probado en rojo; las automatizaciones nuevas en modo de ensayo.
• Compuerta: toda acción irreversible tiene candado y camino de vuelta documentado.
• Quién decide: el dueño aprueba candado por candado; el sistema no los saltea nunca.
• Fallo que evita: un doble cobro, una aprobación automática sin pasar por un humano, el borrado de datos del cliente. Los candados de la Obra Social son el modelo Ref. 28; el reflejo de no romper el listado entero, también Ref. 25.
• Contrato: peldanos/peldano-14-fail-closed.md.

Peldaño 15 — Integración continua, entornos, secretos y despliegue como parte del producto

Llegar a producción tiene que ser un paquete reproducible: los tests corren UNA vez, el despliegue solo empaqueta y sube, la configuración vive en el servidor y no en el repositorio, y la vuelta atrás está probada. Buena parte de esto ya existe desde el esqueleto; este peldaño lo completa hacia producción.

• Intención: que llegar a producción sea un paquete reproducible, con los tests corridos una sola vez y la configuración fuera del repositorio.
• Cuándo: la cadena de integración y el despliegue al entorno de prueba se montan en el peldaño 4. El cierre hacia producción —entorno real, secretos, promoción, vuelta atrás probada, candado contra secretos— se hace en el tramo de salida, después de la auditoría y de los candados. La rutina de cada despliegue se aplica en toda la operación.
• Entradas: el relevamiento de entornos y accesos; el esqueleto con su integración.
• Artefacto: la integración continua que corre la batería una vez por commit; el despliegue que espera ese resultado y solo empaqueta; la configuración solo en el servidor; el procedimiento de promoción escrito y repetible; la vuelta atrás probada; la verificación que impide subir un secreto.
• Compuerta: prueba en verde con la misma versión antes de tocar producción; vuelta atrás probada; ningún secreto en el repositorio ni en el chat sin rotar.
• Quién decide: el dueño promueve a producción; el agente prepara todo.
• Fallo que evita: tests corridos tres veces por commit y la cuota fundida Ref. 39; el despliegue endurecido a golpe de pendientes por haberlo descubierto tarde Ref. 32; secretos pegados en el chat Ref. 42.
• Contrato: peldanos/peldano-15-ci-entornos-secretos-deploy.md.

Peldaño 16 — Observabilidad y trazabilidad totales, con nivel configurable

Cuando algo falle en producción quiero seguir una acción desde la pantalla hasta la base de datos con un solo identificador, sin abrir el código; quiero poder subir el detalle de los registros en producción en un minuto, sin volver a desplegar; y quiero que toda acción con consecuencia deje un rastro que la aplicación no pueda borrar.

• Intención: que el sistema se pueda ver mientras corre (observabilidad) y que cada acción importante tenga su rastro (trazabilidad), con un nivel de detalle que se cambia por configuración.
• Cuándo: en la salida a producción, después del 15 y antes del 19. En un legado, el nivel mínimo entra en el cinturón de seguridad (N4) y el completo acá. La regla "todo módulo nuevo registra y propaga" rige durante toda la operación.
• Entradas: la configuración por entorno (15), la tabla de candados (14), la lista de datos personales del relevamiento, y la decisión de dónde viven los registros.
• Artefacto: registros estructurados con nivel configurable sin desplegar; un identificador de correlación en cada registro, de la pantalla a la base; una auditoría inmutable de las acciones con consecuencia; puntos de salud y métricas; docs/OBSERVABILITY.md.
• Compuerta: un identificador real seguido por todas las capas; el nivel cambiado sin desplegar; ningún dato personal en los registros.
• Quién decide: el dueño decide dónde viven los registros, cuánto se conservan y qué es dato personal; el agente arma.
• Fallo que evita: el proceso que siguió vivo una hora cuarenta y tres y se encontró por el log Ref. 16; el agente residente que opera a ciegas si no hay registros que leer Ref. 13.
• Contrato: peldanos/peldano-16-observabilidad-y-trazabilidad.md.

Peldaño 17 — Optimización de la capa de persistencia, medida antes y después

La base de datos es donde los sistemas se mueren despacio: bien con cien registros, mal con cien mil, y nadie sabe cuándo empezó. Acá se decide con números, antes de producción, y con el método del peldaño 7: medir, cambiar, volver a medir sobre los mismos datos.

• Intención: que las consultas reales del sistema, a los volúmenes del dimensionamiento, entren en lo que el negocio tolera, con presupuestos que impidan que vuelvan a salirse.
• Cuándo: en la salida a producción, después del 16 y antes del 19; se repite cuando un bloque agrega una tabla grande o el monitoreo (21) muestra una consulta fuera de rango. En un legado, las mediciones salen de N6 y casi todo se paga "al tocar".
• Entradas: el dimensionamiento (3 o N6), el mapa productor-consumidor (11), la observabilidad (16), y el entorno de prueba cargado al volumen esperado.
• Artefacto: medidores de consultas con test; docs/PERSISTENCE.md con la tabla de antes y después por cambio, los presupuestos por camino y la retención por tabla; un test por presupuesto.
• Compuerta: ninguna consulta que lea una tabla entera en un flujo crítico; cada presupuesto con su test; la pantalla más lenta dentro de lo que el dimensionamiento esperaba.
• Quién decide: el dueño aprueba la lista de cambios, uno por uno; el agente mide y aplica.
• Fallo que evita: las consultas que leían tablas enteras en un sistema vivo Ref. 18; el presupuesto que hubo que apretar a lo medido Ref. 37; los millones de filas sobre archivos Ref. 15.
• Contrato: peldanos/peldano-17-persistencia.md.

Peldaño 18 — Escaneo y solución de vulnerabilidades, en la cadena y con calendario

La auditoría (13) mira el sistema entero con criterio, cada tanto; este peldaño mira una sola cosa, la seguridad, todo el tiempo y por máquina: dependencias, código, secretos en el historial y configuración del servidor. Y una regla: una actualización de dependencia es un cambio, y entra por el bucle.

• Intención: que ninguna vulnerabilidad conocida llegue a producción, y que las nuevas se detecten solas aunque nadie toque el sistema.
• Cuándo: en la salida a producción, después del 15 y antes del primer despliegue; después, en cada push y con calendario semanal. En un legado, la primera corrida es parte de N3.
• Entradas: la integración continua (4 y 15), el relevamiento de entornos, la auditoría anterior, y el criterio del dueño sobre qué es urgente.
• Artefacto: el escaneo en cuatro capas corriendo en la cadena y con calendario; docs/SECURITY_[fecha].md con los hallazgos y lo no escaneado; docs/SECURITY.md con la política; la compuerta en docs/GATES.md; los P0 y P1 arreglados con su pendiente.
• Compuerta: ningún P0 abierto se promueve a producción; un P1 nuevo abre un pendiente solo.
• Quién decide: el dueño define qué es P0 y aprueba los arreglos; el agente monta y corre.
• Fallo que evita: la vulnerabilidad conocida que apareció en la auditoría de calidad Ref. 41; las puertas de administrador que solo vio otra sesión Ref. 40; la seguridad tratada como una lista que se tilda una vez Ref. 23.
• Contrato: peldanos/peldano-18-vulnerabilidades.md.

Peldaño 19 — Pruebas de rendimiento en volumen y punto de ruptura

El peldaño 3 dimensionó con cuentas; este comprueba las cuentas con el sistema corriendo: al volumen esperado, al "por diez", y hasta que algo se rompa. El punto de ruptura es el número más útil del tramo, porque de él salen los umbrales de alerta del 21.

• Intención: saber cómo se comporta el sistema al volumen esperado, al "por diez", y dónde y por qué se rompe, antes de que entre el primer usuario.
• Cuándo: en la salida a producción, después del 16 y del 17, antes del primer despliegue; se repite antes de cada despliegue que cambie la arquitectura, la persistencia o un flujo crítico. En un legado, con los volúmenes medidos en N6.
• Entradas: el dimensionamiento, la observabilidad encendida, la persistencia optimizada, los flujos críticos y la tolerancia del negocio para la pantalla más usada.
• Artefacto: el script de carga en el repositorio, con test; docs/PERFORMANCE_[fecha].md con las tres corridas, el punto de ruptura y el diagnóstico; docs/PERFORMANCE.md con los umbrales y la compuerta; un pendiente por cuello de botella.
• Compuerta: la pantalla más usada dentro de la tolerancia al volumen esperado, o un pendiente con el número; el punto de ruptura escrito con qué se rompe.
• Quién decide: el dueño da la tolerancia y decide hasta qué volumen se arreglan los cuellos de botella ahora.
• Fallo que evita: la carga real que solo se conoció mirando producción Ref. 12; el punto de ruptura que se disfrazó de test fallido Ref. 44; el dimensionamiento como compuerta Ref. 14.
• Contrato: peldanos/peldano-19-rendimiento-y-punto-de-ruptura.md.

Peldaño 20 — Documentación viva y manuales que una persona puede seguir sin IA

El sistema tiene que poder usarse, mantenerse y recuperarse sin el agente y sin vos. Si el día que no hay agente no se puede desplegar, no está terminado. Y como regenerar documentación con un modelo es gratis, la regla pasa a ser "en el mismo commit".

Dicho en una palabra que cualquiera entiende antes de terminar de leerla: sin estos manuales, el dueño no es dueño, es inquilino. Tiene el sistema, lo paga, vive adentro, y no puede entrar si se le pierde la llave: para arrancarlo, para recuperarlo o para entender por qué dejó de funcionar depende de que el que lo construyó —o el modelo que lo construyó— siga disponible y siga teniendo ganas. La propiedad de un sistema no es el código: es poder operarlo sin pedir permiso. (La formulación es de la primera adaptación del método a otro formato, acreditada en la Parte F.)

• Intención: que el sistema se pueda usar, mantener y recuperar sin el agente y sin el constructor.
• Cuándo: el manual de usuario crece con cada bloque funcional, al cierre, con las pantallas nuevas. Los tres manuales completos se generan en el tramo de salida a producción, después del 15, y la prueba con una persona que no programa se hace antes del primer despliegue. La rutina del mismo commit rige durante toda la operación.
• Entradas: el sistema corriendo en el entorno de prueba; los artefactos del 14 y el 15.
• Artefacto: el manual de usuario con capturas reales, el de mantenimiento, y el de infraestructura y recuperación escrito para una persona que tiene que hacerlo a mano a las tres de la mañana; cada uno con fecha y versión.
• Compuerta: la documentación está al día en el mismo commit; alguien que no programa siguió el manual de recuperación y la ejecución dejó su registro (lo de abajo).
• La prueba deja tres cosas escritas, no un "se hizo": el tiempo medido de punta a punta (cuándo empezó, cuándo terminó el sistema de volver a funcionar), el punto exacto donde la persona se trabó —el paso del manual, con sus palabras—, y cada palabra que no entendió. Las tres se escriben con su fecha y el nombre de quien hizo la prueba. Y cada palabra que no entendió abre un pendiente: o se explica en el manual, o se le cambia el nombre a la cosa. Sin ese registro la compuerta no está cumplida, aunque la persona haya recuperado el sistema: una prueba que no produce evidencia es la forma más barata de tener una compuerta que no mide nada.
• Quién decide: el agente mantiene; el dueño lee el manual, no el código.
• Fallo que evita: el documento desactualizado que provocó un commit en el repositorio equivocado; el archivo de proyecto convertido en historial Ref. 41. Los manuales reproducibles a mano son los de la Obra Social Ref. 24.
• Contrato: peldanos/peldano-20-documentacion-viva.md.

Peldaño 21 — Monitoreo de recursos, funciones y consultas fuera de rango, con reporte cíclico

Las pruebas del 19 dicen cómo se comporta el sistema un día; la producción es todos los días, con los datos creciendo. Este peldaño vigila el uso de recursos y el tiempo de respuesta de cada función y cada consulta contra los umbrales del 19 y contra su propia historia, avisa cuando algo sale de rango, y produce un reporte cíclico que se lee con el dueño. Cada desvío es un pendiente.

• Intención: ver un problema de recursos o de rendimiento antes de que lo vea el usuario, y que cada desvío tenga causa o pendiente.
• Cuándo: se monta con el primer despliegue a producción; desde entonces corre solo, y el reporte se lee en cada ciclo (semanal con consecuencias, mensual en un proyecto chico). En un legado, la primera lectura es la línea base.
• Entradas: las métricas del 16, los presupuestos del 17, los umbrales del 19, producción en solo lectura, y el canal y el ciclo decididos con el dueño.
• Artefacto: recolección con historia; alertas por umbral y por desvío; el reporte cíclico generado solo; docs/MONITORING.md; la rutina de lectura en el contrato.
• Compuerta: una alerta provocada llegó al canal; el primer reporte tiene cada desvío con causa o propuesta; ningún umbral subió sin razón escrita.
• Quién decide: el dueño decide el canal, el ciclo y qué desvío se atiende ahora; el agente monta y propone.
• Fallo que evita: el techo que hubo que apretar a lo medido Ref. 37; la cuota que se fundió sin que nadie mirara Ref. 39.
• Ventana verificable: la medición cíclica lleva el primer y el último registro leídos de la base; una ventana escrita a mano se marca como tal y solo avisa.
• Contrato: peldanos/peldano-21-monitoreo-de-recursos-y-rendimiento.md.

Peldaño 22 — Monitoreo de errores y reporte cíclico: ningún error sin pendiente

Un sistema en producción produce errores que nadie reporta. Este peldaño los captura en los tres lugares donde se esconden (el backend, las tareas, el navegador del usuario), los agrupa, avisa de los nuevos y de los que crecen, y produce un reporte cíclico. Dos reglas: ningún error sin pendiente, y no existe el "error conocido" sin un pendiente que diga por qué se tolera y hasta cuándo.

• Intención: que ningún error en producción pase sin ser visto, y que cada uno se cierre con el test que lo reproduce en rojo.
• Cuándo: se monta con el primer despliegue, junto con el 21; desde entonces corre solo, con alertas en el momento y reporte cíclico. En un legado, los errores que ya existían el primer día se vuelven pendientes con su marca de velocidad.
• Entradas: los registros del 16, la tabla de candados (14), producción con el navegador incluido, el canal y el ciclo del 21.
• Artefacto: captura centralizada y agrupada, sin datos personales; alertas por error nuevo, recurrente que crece y con consecuencia; el reporte cíclico con la tasa de error por flujo; docs/MONITORING.md; la rutina en el contrato.
• Compuerta: un error provocado en el navegador seguido hasta el reporte; ningún error recurrente sin pendiente ni razón con fecha.
• Quién decide: el dueño lee el reporte y decide qué se atiende; el agente captura, agrupa y propone.
• Fallo que evita: el error de autenticación reportado como éxito Ref. 43; las cuatro rondas hasta la causa raíz por no tener el error reproducido Ref. 22.
• Fuente del error: los errores de las herramientas que observan el sistema van aparte, en su propia sección del reporte, y no abren pendientes.
• Contrato: peldanos/peldano-22-monitoreo-de-errores.md.

Peldaño 23 — El agente adentro del sistema, y la retrospectiva con número

El último peldaño tiene dos partes que cierran el mismo ciclo. Primero: el agente queda residente en producción, con alcance acotado, actuando a nombre de una persona. Segundo: el método mismo se revisa con números, y lo que se aprende vuelve al peldaño 0 para el próximo proyecto.

• Intención: que el agente quede residente en producción con alcance acotado, y que el método se revise con números.
• Cuándo: el agente residente, al entrar en operación, después del primer despliegue a producción. La retrospectiva, al cierre de cada etapa y del proyecto; es obligatoria aunque sea de una página.
• Entradas: el sistema en producción, los incidentes, los costos.
• Artefacto: el documento del agente residente con su mapa del sistema, su alcance, su credencial a nombre de una persona y la prueba de que lo que está fuera del alcance se rechaza; y la retrospectiva con números con fuente, cada incidente mapeado a un peldaño, y al menos una propuesta concreta de cambio a la escalera.
• Compuerta: el agente no puede hacer lo que el dueño no aprobó; la retrospectiva produce al menos un cambio a la escalera.
• Quién decide: el dueño.
• Fallo que evita: el agente que opera sin mapa; y el método que se repite igual proyecto tras proyecto sin aprender. La retrospectiva con número que mató al equipo multiagente es el modelo Ref. 6; el agente residente, el de la Obra Social Ref. 13.
• Contrato: peldanos/peldano-23-agente-residente-y-retrospectiva.md.

Parte D — Cómo se ejecuta, cuánto se exige, y con qué herramienta

Cómo se ejecuta cada peldaño: el contrato

La ficha de ocho partes dice qué busca cada peldaño, cuándo se sube y qué deja. Pero un peldaño se entiende cabalmente recién cuando se ve cómo se pide, qué tiene que volver y cómo sé que volvió completo. Por eso cada peldaño tiene, además de la ficha, un contrato en un archivo propio dentro de peldanos/, siempre con las mismas cinco secciones:

1. Contexto requerido, nombrado en forma genérica ("relevamiento de datos de volumetría", "acceso de lectura al sistema anterior", "la lista de acciones con consecuencia real"), sin bajar al detalle de la ingeniería de sistemas. Los relevamientos son por naturaleza incompletos; no intento hacerlos completos con un formulario.
2. Prompts, los que se le dan al modelo, textuales. El inicial y, cuando el peldaño es una conversación, el de cierre. Todos llevan la misma cláusula, que es el corazón del asunto: el modelo evalúa si el contexto alcanza; si no alcanza, pide todo lo que falte antes de seguir; y no estima ni inventa un dato que solo el negocio tiene. El que sabe qué le falta para calcular es el modelo, no un formulario. Y cada prompt viene precedido de un bloque que dice "Antes de enviar el prompt": los archivos y los insumos que vos (o el negocio con vos) tenés que haber construido antes de pegarlo, con su nombre, su contenido y el estado mínimo aceptable. El prompt los nombra, el bloque te dice cómo tienen que estar hechos; sin ese bloque, el prompt menciona archivos que nadie te dijo cómo escribir.
3. Resultado esperado: las características detalladas del artefacto.
4. Verificación de completitud: la lista de comprobaciones que hace el dueño sobre el artefacto, sin leer código. Si una da "no", el peldaño no está subido.
5. Señales de alarma: dos o tres síntomas de que el peldaño se subió mal aunque parezca subido.

Esa verificación de completitud está repartida en treinta y dos contratos, uno por peldaño y uno por estación, y eso sirve mientras el proyecto está en marcha. Pero hay un momento anterior en el que no tenés treinta y dos contratos a mano: la reunión en la que alguien te ofrece construirte el sistema. Para ese momento hay una hoja: las veinticinco preguntas para el proveedor, que es la misma verificación de completitud juntada, escrita para una persona que nunca contrató software y ordenada por lo que le están prometiendo. Cada pregunta dice qué respuesta se puede ver —un archivo, un número con su comando, una prueba en rojo, un manual, una firma— y de qué peldaño sale. Se imprime y se lleva.

Y en el encabezado de cada contrato: el tramo, el cuándo, la forma y el tamaño (si es obligatorio en todo proyecto o proporcional).

Los prompts están en inglés, y cada uno trae su traducción. Es una decisión que tomé por tres razones: el mismo contenido en castellano ocupa entre un 30 y un 50 % más de tokens; la capacidad de seguir instrucciones de los modelos está mejor calibrada en inglés, así que un prompt en inglés tolera mejor la brevedad sin volverse ambiguo; y el vocabulario del oficio (test, commit, rollback, mock) es inglés. Pero no quiero que el inglés sea una barrera para leer el método: debajo de cada prompt va la explicación de qué estoy pidiendo y por qué cada cláusula está ahí, y en la versión HTML hay un botón que muestra el prompt traducido al idioma del documento. El prompt que se le pega al modelo es el inglés; la traducción es para que vos lo entiendas. Y todos terminan con "Reply in my language", porque el prompt está en inglés pero la conversación no tiene por qué estarlo.

Qué es obligatorio y qué es proporcional, según el tamaño del proyecto

Una pregunta que aparece enseguida: "¿todo esto para un sistema chico?". La respuesta es que veinticuatro peldaños no son veinticuatro etapas largas; varios se suben en una sesión, y los que son proporcionales se achican con el proyecto. Lo que no se achica es la lista de los que no se negocian.

Pero antes de la tabla conviene decir cómo se llega a achicar un peldaño, porque la tabla sola se lee como un permiso y no lo es. Son tres momentos, y van en orden.

Primero se hace completo, incluso lo que no se entiende para qué. La primera vez que aplicás el método no estás en condiciones de saber qué parte te sobra: los peldaños que parecen burocracia son justo los que previenen los problemas que todavía no te pasaron, y la lista entera salió de problemas que ya pasaron. Hacerlo completo una vez es más barato que la discusión sobre qué saltear, y es lo único que te da el criterio para la etapa siguiente.

Después se adapta a lo que tenés enfrente. Cuando ya subiste los veinticuatro una vez, sabés qué produce cada uno y podés dimensionarlo: media página en vez de cinco, una corrida en vez de un presupuesto por camino, un reporte mensual en vez de uno semanal. Eso es lo que esta tabla propone. Y la decisión es del dueño, peldaño por peldaño y en voz alta: cuáles se achican y cuáles no se negocian en este proyecto, escrito antes de empezar y no después del primer problema. Un peldaño achicado por decisión escrita es proporcionalidad; achicado en silencio, es deuda.

Y al final se mejora, para los que vienen. El peldaño 23 cierra con una retrospectiva que vuelve acá como propuesta de cambio a la escalera. Lo que descubriste aplicándolo no es tu anécdota: es la próxima fila de esta tabla. Este documento está en su versión 4 por eso.

Esta tabla es una propuesta hipótesis para confirmar con el primer proyecto que use el método de punta a punta:

En resumen: hay trece peldaños que no se negocian en ningún proyecto (0, 1, 2, 3, 5, 6, 8, 9 en su mínimo, 10, 12, el escaneo de dependencias del 18, la captura de errores del 22 y la retrospectiva del 23), y once que se dimensionan con el proyecto.

Cómo se usa con cualquier herramienta

El método es neutral de herramienta; lo que cambia entre una y otra es dónde se pone cada artefacto para que el modelo lo lea. La correspondencia, para las herramientas más usadas a fines de 2026:

La columna de Forge es la que automatiza más; las otras tres funcionan igual de bien si el dueño hace a mano lo que Forge hace solo: pegar el prompt del peldaño en el momento correcto y exigir la verificación de completitud antes de pasar al siguiente. Esa es, de hecho, la práctica del curso.

Parte E — Lo que falta elaborar

1. El peldaño 0 completo: los pesos de los criterios que ponderan, el umbral, y más proyectos rechazados como contraejemplos. Tengo X1 y X2; falta lo demás.
2. Un nombre memorable para cada peldaño, en una frase, para los manuales y las publicaciones.
3. La exportación a Forge, en gran parte resuelta. El método corre completo como flujo de proyecto en Forge, con compuertas mecánicas y el prompt del peldaño en curso inyectado en el chat (D-035, D-036). Lo que falta es la matriz explícita, contrato por contrato, contra lo que Forge ejecuta hoy, para que una divergencia entre lo que este documento dice y lo que la herramienta hace se note apenas aparece, en vez de acumularse.
4. Probar los contratos en un proyecto de punta a punta, ya en marcha. El proyecto guía del curso (Turnera) corrió los veinticuatro contratos tal cual están escritos y cerró 24 de 24; lo que encontró en el camino ya corrigió el método (D-037 a D-040). Lo que falta no es la primera corrida completa, que ya pasó: es que lo corra un proyecto ajeno, sin que yo esté al lado resolviendo lo que el contrato no previó.
5. La primera cohorte del curso, que va a corregir el orden de la línea de tiempo donde haga falta y los errores típicos, que hoy están escritos desde mis proyectos y no desde alumnos.
6. El camino evolutivo-correctivo, probado en un legado propio, no en uno ajeno. El proyecto guía heredado del curso (Turnera heredada) corrió las ocho estaciones y el resto de la escalera tal cual, cerró 27 de 27, y motivó tres decisiones del método (D-038, D-039, D-040). Lo que falta es el mismo camino sobre un legado real de un tercero, con su propia historia y sus propios atajos, no sobre el sistema que yo armé para el curso.
7. Lo que NO está en la escalera y debería estar hipótesis: la gestión del costo de tokens y cuotas como presupuesto explícito (hoy es reactiva); la rotación de secretos como rutina y no como incidente; y un criterio para cuándo el humano SÍ tiene que mirar el código, porque hoy la respuesta es "nunca" y sospecho que hay momentos puntuales en que conviene.

Parte F — Trabajos relacionados: qué existe parecido, y en qué se distingue este método

Cuando terminé de escribir la escalera me hice la pregunta obvia: ¿esto ya existe con otro nombre? Pedí una investigación a fondo, en inglés, en castellano y en japonés, sobre metodologías, ensayos y trabajos académicos publicados hasta octubre de 2026 para construir software con inteligencia artificial. Lo que sigue es el resultado, resumido con honestidad: lo que ya está en otros lados lo cito en vez de reclamarlo, y lo que no encontré lo digo como "no lo encontré", no como "no existe". Esta parte se va a ir ampliando a medida que aparezcan cosas nuevas, que aparecen todas las semanas.

La respuesta corta: no encontré ningún método publicado que junte lo que este junta. Sí encontré un campo entero que, desde mediados de 2025, converge en varias de sus piezas por separado, y un practicante célebre que llegó a la misma premisa radical tres meses antes de que yo publicara esto.

F.1 Los parientes más cercanos

F.2 Lo que ya existe, y conviene citar en vez de reclamar

El rojo antes del verde impuesto al agente está en Beck, en Tsumiki, en las prácticas de Anthropic y en los patrones de Simon Willison de 2026. Los pasos ordenados con prompts textuales están en Spec Kit, en Tsumiki y en Reed. La caracterización como paso previo al legado está en Osmani, publicada un mes antes que este documento. La prueba de punta a punta desde la pantalla, con un evaluador distinto del generador, está en Anthropic. La ingeniería de requerimientos como prerrequisito está en todo el movimiento de desarrollo guiado por especificaciones. Y el humano que no lee el código está en Uncle Bob, en Karpathy para lo descartable, y en el libro de Yegge y Kim.

F.3 Lo que no encontré en ningún lado

• El destinatario. Toda la literatura asume un ingeniero que revisa. Uncle Bob no lee código porque tiene cuarenta años de criterio para construir la barrera. Este método parte del dueño que nunca lee, y deriva todo lo demás de esa restricción. Esa inversión no está planteada en ningún trabajo. Lo que hay para el no programador es documentación del daño: un estudio de junio de 2026 sobre 9.041 aplicaciones hechas con herramientas de "vibe coding" encontró vulnerabilidades en el 91 % de las auditadas (arXiv 2606.23130).
• El informe de verificado, creído y punto ciego como entregable obligatorio (peldaño 12). El problema está diagnosticado con números: la declaración de completitud de un agente supera a la aprobación real entre 28 y 38 puntos (SpecHarness, arXiv 2609.29921), y perder la etiqueta "no verificado" en un traspaso entre agentes dispara la aprobación de acciones riesgosas del 5 % al 60 % (arXiv 2609.20211). Nadie lo convirtió en un formato de rendición de cuentas hacia una persona.
• El medidor con test propio (peldaño 7). La regla "un número que alimenta una decisión se mide con un programa que tiene su test" no está escrita en ninguna fuente que haya encontrado.
• La escalera completa, de la elegibilidad al monitoreo y la retrospectiva. La más larga que encontré tiene diez pasos; casi todas terminan en el merge; solo AI-DLC y Osmani rozan la operación.
• Sin plazos como regla (D-030). No está contestada; está ausente.
• La combinación. Los que no leen código no prueban con rigor (Ronacher, Yegge). Los que prueban con rigor, leen (Beck, Osmani, Hashimoto, GitHub). Uncle Bob y old-coder rompen ese cruce, y lo hacen por tarea, no por proyecto.

F.4 La objeción que hay que responder, y cómo la respondo

Birgitta Böckeler midió, en agosto de 2026, que pedirle a un agente el ciclo de test primero no mejora la calidad de forma fiable, porque el agente a veces finge el rojo o implementa antes del test para que pase de entrada (martinfowler.com). Lo único que en su estudio distinguió a los tests que vigilan de los que decoran fueron las pruebas de mutación. Otro estudio del mismo año muestra que un modelo avala un tercio de sus propios errores (arXiv 2605.21537), y otro, que una sesión limpia más un modelo distinto encuentran más errores que dos sesiones del mismo modelo (arXiv 2610.01471).

Es una objeción seria, y la tomo. La respuesta del método tiene tres piezas (D-033). En el peldaño 8, el rojo es un recibo, no un relato: el comando exacto, la versión contra la que corrió, la cantidad de fallos y el código de salida, pegados tal cual, para que el dueño lo vuelva a correr con un comando y lo haga, una vez por bloque, con un pendiente elegido al azar. En el peldaño 13, la auditoría por otra sesión vuelve a correr una muestra de esos recibos. Y en el peldaño 9, las pruebas de mutación son obligatorias en cualquier proyecto con usuarios (quedan opcionales solo sin usuarios reales), con su puntaje al cierre de cada bloque junto a la cobertura. Ninguna de las tres piezas exige que el dueño lea código. Las tres hacen que fingir el rojo cueste más que correrlo.

F.5 Una adaptación del método a otro formato, y qué me enseñó

En 2026, Oscar Schmitz publicó "El Arte de Forjar Sistemas" (191 páginas), una novela que adapta este método: toma la escalera y la cuenta como ficción, con una dueña que decide y un equipo que construye. No es un trabajo relacionado en el sentido de los de arriba —no propone otro método— sino algo que no había pasado antes: alguien leyó el corpus entero para producir otra obra. La validé aseveración por aseveración contra la letra del método, y el informe de esa validación queda en el repositorio.

Lo que salió de ahí, y por qué está en esta parte y no en las referencias: las referencias son casos propios, con fecha y commit; una novela no es un caso. Lo que sí hizo fue dos cosas.

Aportó cuatro formulaciones mejores que las mías, y están adoptadas en este documento con este crédito: "la cobertura cuenta pruebas; el rojo dice si sirven" (peldaño 9), "el dueño no es dueño: es inquilino" (peldaño 20), la idea de que a achicar un peldaño se llega después de haberlo hecho completo (Parte D) y la de que la prueba del manual de recuperación tiene que registrar el tiempo, la traba y las palabras que no se entendieron (peldaño 20). La quinta es la hoja de las veinticinco preguntas para el proveedor: la idea de juntar la verificación de completitud en una hoja que un dueño se lleva a una reunión es suya; las veinticinco preguntas de este repositorio están escritas de cero desde los contratos del método, porque su versión es su obra y tiene sus derechos reservados.

Y mostró un defecto estructural del método que ninguna auditoría había visto, que es lo más valioso de todo: el autor reprodujo sin un error seis cifras seguidas de las referencias, y se salteó veintisiete de las cuarenta y cinco reglas del Anexo H. No se le pasaron: este documento no lo nombraba ni una vez, así que nunca supo que existían. Un lector que lee todo y aplica el método quedaría detenido en cinco compuertas publicadas sin entender por qué. Esa es la razón de que el anexo esté nombrado en la Parte A, en la apertura de la Parte C y en la ficha de los seis peldaños que lo cargan, y de que haya una comprobación en la cadena que se pone en rojo si alguna ficha deja de nombrarlo. El peldaño 23 pide que la retrospectiva vuelva como propuesta de cambio a la escalera; esta es la primera que vino de un lector.

Un marco útil para ubicar este método en el mapa es la taxonomía de Macedo, de junio de 2026 (arXiv 2606.04967): seis dimensiones (especificación, contexto, roles, ejecución, validación, portabilidad), y la constatación de que ningún framework de los que comparó cubre las seis a la vez, con un intercambio estructural entre profundidad de proceso y portabilidad. Urazuke apunta a las seis, y su apuesta por los prompts exactos en inglés más la neutralidad de herramienta es, justamente, el intento de romper ese intercambio.