Método · software con IA · código abierto
Urazuke, el método de la evidencia.
Urazuke (裏付け) es la palabra japonesa para el respaldo que tiene una afirmación: lo que la sostiene por detrás. Es mi método para construir software con inteligencia artificial que salga robusto y listo para producción, sin que el dueño del proyecto tenga que leer una sola línea de código. Lo destilé de tres sistemas reales que hoy tengo en producción, apoyado en la ingeniería de sistemas de siempre y en lo que esos sistemas me enseñaron sobre dónde los modelos la aplican de manera frágil.
Autor: Pablo Kuschniroff, asistido por Claude Code.
Creative Commons BY-SA 4.0 · Ocho idiomas · Neutral respecto de la herramienta · Tres sistemas en producción como fuente · Código abierto y colaborativo
La tesis
La IA no interrumpe el método: lo continúa.
Antes de la tesis, una aclaración que me importa: este método no es una colección de parches que fui poniendo después de cada golpe. Sale de dos factores combinados. El primero es mi propio conocimiento de la ingeniería de sistemas: relevamiento, requisitos, dimensionamiento, pruebas como evidencia, despliegue reproducible, auditoría; lo traigo de mucho antes de que existieran estos modelos. El segundo es lo que tres sistemas en producción me mostraron, incidente tras incidente: dónde los modelos aplican esos principios de manera frágil, y por lo tanto dónde hay que apretar por escrito. Las cicatrices prueban dónde hace falta la rigidez; no son el origen de los principios.
La industria dejó de confiar en el autor del código hace veinte años. Cuando la escritura pasó a equipos junior, tercerizados o rotativos, la revisión línea por línea se volvió imposible, y lo que creció en su lugar fue todo lo que hoy damos por sentado: tests automatizados, integración continua, criterios de aceptación, pipelines que no dejan pasar nada sin verde. Esa fue la respuesta de la ingeniería de sistemas a "el que escribe no es confiable": no leerle el código, exigirle evidencia. El modelo es el siguiente autor, no el primero desconfiable.
Dónde va el esfuerzo del humano
El humano hace dos cosas solamente: decide, y verifica artefactos. Redactar, construir, probar, medir y documentar lo hace el modelo. Cada peldaño termina en una verificación de completitud sin leer código.
La evidencia se prueba a sí misma
Un test que nunca viste fallar no sabés si prueba algo. Un medidor sin test miente. Un reporte sin puntos ciegos esconde. La disciplina de independencia del control de calidad, llevada un paso más adentro.
El costo de los artefactos
Antes la documentación era cara y envejecía. Ahora regenerarla es gratis, así que la regla pasa a ser "en el mismo commit" y "reproducible a mano, sin IA". Lo que era un ideal incumplible pasa a ser una compuerta.
Qué es y qué no 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: relevamiento, requisitos, dimensionamiento, diseño, construcción, prueba, despliegue, operación, auditoría. A los que vienen del vibecoding les da lo que no tienen, que es justamente el esqueleto.
Lo que es
- Un método: qué hacer en qué orden, qué pedirle al modelo, qué tiene que entregar, y cómo saber que está completo.
- Veinticuatro peldaños en cuatro tramos, cada uno con un contrato: contexto, prompts, resultado esperado, verificación, señales de alarma.
- Neutral respecto de la herramienta: Claude Code, Cursor, Codex CLI, Gemini CLI o Forge. Cada artefacto es un archivo, un test o un script.
- Destilado de tres sistemas reales en producción, con cada regla atada al commit y al golpe que la originó.
Lo que no es
- Un curso de programación ni de un framework.
- Una colección de trucos de prompts para que el modelo escriba mejor.
- Un método para el prototipo de la demo del viernes: es para lo que tiene que seguir funcionando después.
- Un método que sirve para cualquier proyecto. El peldaño 0 define la frontera por escrito.
La escalera
Veinticuatro peldaños, cuatro tramos, en el orden en que se suben.
Los peldaños están numerados en el orden cronológico en que se suben. Los de arranque se suben una vez por proyecto; los del bucle se repiten en cada cambio; los de salida a producción, una vez, antes del primer despliegue; los de operación, cuando el sistema ya está vivo. El 23 cierra el ciclo y vuelve al 0. Cada peldaño tiene una ficha de ocho partes y un contrato con los prompts. No hay plazos: el método es un proceso, no una promesa de velocidad.
Una vez por proyecto, antes de escribir funcionalidad
Las cinco que más tentación dan de saltear y más caro cuesta saltear.
En cada cambio, durante todo el proyecto
Van en el orden en que se hacen con cada pendiente. Se aprenden en los dos primeros bloques y se practican durante todo el proyecto.
Una vez, antes del primer despliegue
Convierten "funciona" en "se puede sostener": auditoría, candados, cadena a producción, observabilidad, persistencia, vulnerabilidades, rendimiento y manuales.
Cuando el sistema ya está vivo
Los dos monitoreos con reporte cíclico, el agente residente y la retrospectiva que cierra el ciclo y vuelve al 0.
Trece peldaños que no se negocian en ningún proyecto
- Elegibilidad (una hora; ahorra meses)
- Contrato de convivencia
- Definición corta, con "qué NO es"
- Dimensionar con números del negocio
- Los pendientes como plan
- Decisiones con dueño y fecha
- Tests vistos en rojo
- Reporte verificado / creído / puntos ciegos
- Retrospectiva con número
- Escaneo de dependencias y secretos en la cadena
- Captura centralizada de errores y reporte
- Calidad del código en la cadena, en su mínimo
- Casos de prueba manual ejecutados por personas
La línea de tiempo
Cuándo se sube cada peldaño, y qué pasa entre medio.
Un método sin línea de tiempo es una lista de buenas intenciones. Esta es la de cualquier proyecto: cinco fases, en orden, y en cada una lo que se hace además de los peldaños: la ingesta de requerimientos, la infraestructura, la cadena de integración y despliegue, el desarrollo, las pruebas de punta a punta, la vista humana, las pruebas humanas. Sin plazos: cada fase dura lo que el sistema pida.
Ingesta
Relevamiento con el dueño, con los métodos clásicos de la ingeniería de requerimientos: entrevistas, casos de uso, modelo de dominio con sus estados, prototipos de pantalla. En prosa, incompleto a propósito: el agente lo completa preguntando.
Arranque (peldaños 0 a 4)
Elegibilidad, contrato, definición con árbol semántico, dimensionamiento. Y toda la infraestructura inicial y la cadena CI/CD: repositorio, entorno de prueba, integración continua, primer despliegue con el sistema vacío. El dueño abre la URL y ve la pantalla vacía.
Bucle (peldaños 5 a 12)
Bloque funcional por bloque. Con cada pendiente: especificación, decisiones, test en rojo, prueba de punta a punta del flujo, captura de la pantalla que mira el dueño. Al cierre de cada bloque: la batería completa de punta a punta y pruebas humanas en el entorno de prueba.
Salida a producción (13 a 20)
Auditoría por otra sesión. Candados antes de construir lo que cobra o envía. Cierre de la cadena a producción con vuelta atrás probada. Los tres manuales. Pruebas de aceptación del dueño sobre todos los flujos. Y los cuatro peldaños de calidad operativa previos al despliegue: observabilidad, persistencia, vulnerabilidades, rendimiento.
Operación (21 a 23 y el bucle)
Agente residente a nombre de una persona. Auditoría periódica. Cada evolución entra por el bucle completo y sale por la cadena de despliegue. Retrospectiva con números al cierre de cada etapa. Los dos monitoreos, recursos y errores, montados en la semana del primer despliegue, con reporte cíclico que el dueño lee.
Las pruebas de punta a punta no son una vez al final
Con cada pendiente, el flujo que tocó. Al cierre de cada bloque, todos los flujos que existen. 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 semanas sin probar.
Los tres casos de uso
Carpeta vacía, sistema con método, o sistema heredado: por dónde se entra.
La escalera está escrita mirando una carpeta vacía, que es el caso más claro para aprender y no el más frecuente. Antes de abrir el agente conviene saber en cuál de los tres casos estás, porque cambia por dónde se entra. Y el tercero, el sistema que ya existe y no nació con el método, tiene un camino propio: se normaliza sin reescribir, y recién después se sube la escalera.
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: una semana de arranque antes de la primera funcionalidad. Es lo que describen el documento principal, los contratos y el curso.
Evolutivo-correctivo con 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. Es el 15 volviendo al 0.
Evolutivo-correctivo sin método
Un sistema que corre, con usuarios, hecho por otro o por vos mismo sin evidencia. Ocho estaciones de normalización (N0 a N7): recuperar por autodescubrimiento los insumos que nadie escribió, con marcas de fuente; un cinturón de seguridad como compuerta dura; la deuda pagada a medida que se toca. Después, el bucle en modo correctivo o evolutivo.
Leer el camino evolutivo-correctivo → El curso, parte 2: el proyecto heredado →
El contrato de cada peldaño
Cómo se pide, qué tiene que volver, y cómo sé que volvió completo.
Cada peldaño se ejecuta con un contrato de cinco secciones. Los prompts para el modelo están en inglés, una sola pieza idéntica en las ocho versiones del documento, y debajo de cada uno la explicación en el idioma del lector de qué le estamos pidiendo y por qué cada cláusula está ahí.
Contexto requerido
Nombrado en forma genérica. Los relevamientos son por naturaleza incompletos; no se completan con un formulario, los completa el modelo preguntando.
Prompts
Textuales. Todos con la misma cláusula: el modelo evalúa si el contexto alcanza, pide lo que falta antes de seguir, y no estima ni inventa un dato que solo el negocio tiene.
Resultado esperado
Las características detalladas del artefacto: qué archivo, qué secciones, qué no puede faltar.
Verificación de completitud
Lo que el dueño chequea sobre el artefacto sin leer código. Si uno da "no", el peldaño no está subido.
Señales de alarma
Los síntomas de que el peldaño se subió mal aunque parezca subido. Los que se ven semanas después, cuando ya duele.
Un prompt de ejemplo · peldaño 7
docs/PENDING.md; el cambio ya implementado; el comando de la batería en docs/STATUS.md; y el entorno de prueba corriendo, con datos para el flujo que se toca. En la documentación, cada prompt viene precedido por un bloque así: qué archivos construís vos, con qué contenido, y cuál es el estado mínimo aceptable.Por qué en inglés: el mismo contenido en otro idioma ocupa entre 30 y 50 % más tokens, los modelos siguen instrucciones con más precisión en inglés, y el vocabulario del oficio es inglés. Pero no quiero que el inglés sea una barrera: en la documentación, cada prompt trae su traducción al idioma del documento y un botón como este. Al modelo se le pega el inglés; la traducción es para que lo entiendas. Todos terminan con "Reply in my language".
Del requerimiento al pendiente
Ingeniería de requerimientos de siempre, descompuesta en unidades que un modelo puede construir y vos verificar.
Un requerimiento no es una frase del cliente en un chat. Es esa frase procesada por métodos que existen desde hace décadas y que el modelo aplica muy bien si se lo pedís y muy mal si no: entrevistas, casos de uso, modelo de dominio, criterios de aceptación, prototipos de pantalla, trazabilidad. En el método, tres artefactos los sostienen.
El árbol semántico
El sistema como un árbol: dominios; debajo, actores, procesos (los casos de uso), entidades con sus estados, pantallas e integraciones; y de cada nodo cuelgan los pendientes y las decisiones. Lo construye el agente, lo corregís vos, y es lo que el agente lee antes de tocar código. Un pendiente que no cuelga de ningún nodo está fuera de alcance, y se ve en diez segundos.
La especificación detallada vive en cada pendiente
El documento de especificación largo que envejecía se descompone: cada pendiente trae su nodo del árbol, la historia de origen con las palabras del cliente, la descripción, las reglas de negocio con su decisión y fecha, los datos, las pantallas, los casos borde, los criterios de aceptación y cómo se verifica. Leer esa especificación es lo más cerca que vas a estar de leer código, y es la distancia correcta.
Los pendientes cerrados son documentación
Un pendiente cerrado no se borra: queda con su especificación, la decisión que lo originó, la evidencia con la que se cerró, el commit y la fecha. La cola de pendientes cerrados es el historial funcional del sistema; de ahí salen el diario de cambios, el manual de usuario, y la respuesta a "por qué el sistema hace esto" seis meses después.
Con cualquier herramienta
Los artefactos son archivos, tests y scripts. Lo que cambia es dónde van.
Claude Code
El contrato y las rutinas van en el CLAUDE.md del proyecto; los prompts de peldaño se pegan en el chat al subir cada peldaño.
Cursor
Las rutinas van en .cursor/rules/ como reglas siempre activas; el resto, igual.
Codex CLI / Gemini CLI
En AGENTS.md o GEMINI.md en la raíz del repositorio.
Yujin Forge
El contrato y las rutinas son doctrinas, los prompts se inyectan solos al cruzar cada compuerta, y el registro de pendientes es nativo. Es el mismo método con menos copiar y pegar. Conocé Forge →
El curso
Veinticuatro lecciones con tareas prácticas, hasta la aplicación en producción.
Un manual tipo curso, una lección por peldaño, para aplicar el método sobre un proyecto propio o sobre el proyecto guía ("Turnera", una agenda de turnos con recordatorios, señas y datos personales: todo lo que hace falta para que ningún peldaño sea de mentira). Termina con la lista de salida a producción: veinticuatro condiciones que el dueño verifica sin abrir el código. La parte 2 del curso toma el mismo consultorio con un sistema heredado ("Turnera heredada") y enseña a normalizarlo antes de corregirlo y evolucionarlo.
Qué tenés que entender
El concepto de cada peldaño, explicado como se le explica a una persona, con el fallo real que lo originó.
La tarea, paso a paso
Con el prompt exacto para el agente y qué hacer con lo que devuelve. Incluye pruebas a propósito: dejar una pregunta sin contestar y ver qué hace.
La verificación y el entregable
Las preguntas que te hacés sobre lo entregado, sin abrir el código, y el archivo o la evidencia que tiene que existir al final.
Errores típicos y el proyecto guía
Lo que les pasa a casi todos la primera vez, y cómo se ve cada lección aplicada a Turnera.
Para el que entra
El desarrollador junior en la era posterior a la programación a mano.
Si el modelo escribe el código, ¿cómo se forma un junior, qué aprende y para convertirse en qué? Un documento aparte sobre los focos de capacitación que pierden peso, los que ganan, la alfabetización que sigue siendo obligatoria, el objetivo y un plan de doce semanas con mentor. Escrito a nivel principiante, como todo el método.
En equipo
Varios desarrolladores, cada uno con su agente, sobre una misma rama.
El método está escrito en singular. Este documento dice cómo se aplica cuando hay varios: las siete reglas de la rama compartida (el pendiente como unidad de propiedad, integrar chico y seguido, la integración continua como árbitro, lo que está a medias detrás de un interruptor, el mapa como detector de conflictos, las decisiones con nombre, revisar evidencia y no código), cómo se reparten los peldaños, y los prompts.
Todo el material, en ocho idiomas
Leelo en tu idioma.
El castellano es la fuente de verdad; las otras siete versiones son traducciones y, si divergen, prevalece el castellano. Los prompts son idénticos en todas. Tres documentos por idioma: el documento principal (la tesis, el relevamiento de los tres sistemas, los veinticuatro peldaños, los fallos reales y el glosario), los veinticuatro contratos, y el manual-curso. Y desde la versión 5, dos documentos más por idioma: el camino evolutivo-correctivo, para sistemas que ya existen, y la parte 2 del curso con el proyecto guía heredado.
El método se publica bajo Creative Commons Atribución-CompartirIgual 4.0: se puede usar, traducir y adaptar, con atribución y compartiendo igual. El repositorio es público y colaborativo: github.com/pkuschnirof/urazuke. Las mejoras entran por pull request desde un fork, con su evidencia, y las fusiono después de revisarlas.
¿Esto ya existe con otro nombre? Investigué a fondo qué hay de parecido hasta octubre de 2026 (Uncle Bob y su "gauntlet", Tsumiki, Spec Kit, Consort, IACDM, Osmani y otros), qué conviene citar en vez de reclamar, qué no encontré en ningún lado, y la objeción más seria con su respuesta. Está en la Parte F del documento principal, "Trabajos relacionados".
Dos manuales de ejecución en Forge, paso a paso y con capturas, hechos sobre proyectos de práctica reales: proyecto nuevo (Turnera) y proyecto existente (Turnera heredada). Con la evidencia recolectada en cada peldaño.
Dos documentos más, fuera del corpus traducido: las compuertas explicadas, en inglés, porque es documentación de herramienta y se genera desde los datos; y las evaluaciones de modelos de IA sobre el método, en castellano.
Si vas a consumir el método con una herramienta, no hace falta leer el repositorio: la interfaz de datos está en yujin.app/urazuke/api/. Su índice lista cada recurso con su dirección canónica, su versión y su huella: gates.json, la definición mecánica de las compuertas, y prompts.json, los prompts. La huella se recalcula sobre el contenido, así que una copia vieja se delata sola.
De dónde sale
Tres sistemas en producción, y cuarenta y seis casos documentados con fecha y evidencia.
Relevé en solo lectura tres repositorios que hoy están en producción con gente real usándolos: la herramienta donde se formó el método (mil noventa commits en cinco meses), un sistema de automatización para un ente de salud con dinero y datos sensibles en juego (seiscientos cuarenta y un pendientes, todos cerrados), y una mesa de entrada omnicanal para una asociación civil (el primero donde la medición precede sistemáticamente a la construcción). Cada caso que cito en el método está numerado en el documento de referencias, para que los procedimientos queden limpios y el detalle siga a un clic. Los clientes están anonimizados; los números, las fechas y los commits son reales.
Dónde el modelo falla al aplicar lo obvio
El medidor que mintió dos veces. El error de autenticación reportado como éxito. Las tres de cuatro aseveraciones que estaban mal. Cada uno me dijo dónde un principio que para mí era obvio necesitaba volverse una cláusula explícita del prompt.
Retrospectiva con número
Eliminé un equipo entero de agentes con sesenta dólares y setenta y tres minutos contra noventa minutos. Partí el despliegue con veinticuatro a veintisiete minutos contra once. La escalera misma es eso.
Pablo Kuschniroff, asistido por Claude Code
RPAForce / Yujin. El método se aplica a sí mismo: sus decisiones están registradas con fecha y palabras textuales, y el repositorio es público desde el 18 de octubre de 2026 en github.com/pkuschnirof/urazuke.
Preguntas frecuentes
Preguntas frecuentes.
- ¿Necesito saber programar?
- No. Necesitás un dueño del dominio con criterio y tiempo para decidir, y nociones mínimas de qué es un repositorio, un commit y un push. El método existe justamente para que el dueño verifique evidencia en vez de leer código.
- ¿Sirve para cualquier proyecto?
- No, y eso no es un defecto. Hay dos condiciones excluyentes: un repositorio estándar donde dejar la evidencia, y pantallas que se puedan operar por programa para probar de punta a punta. El peldaño 0 pone la frontera por escrito.
- ¿Necesito Forge o NAC3?
- No. El método es neutral respecto de la herramienta; cada artefacto es un archivo, un test o un script. Forge automatiza las compuertas y la inyección de prompts, pero el peldaño existe sin Forge. NAC3 es el medio con que hoy logramos la testeabilidad de pantalla, no una condición.
- ¿Por qué los prompts están en inglés si la documentación está en mi idioma?
- Porque los modelos siguen instrucciones con más precisión y menos tokens en inglés. Cada prompt es una sola pieza idéntica en las ocho versiones, explicada en tu idioma debajo, y termina con "Reply in my language".
- ¿Cuánto tarda un proyecto chico de punta a punta?
- No te doy un plazo, a propósito. El método es un proceso para hacer sistemas operables y mantenibles sin comprender un bit de código; no es un proceso para hacer sistemas más rápido, aunque la velocidad aparezca como consecuencia. Lo que fija el método es el orden y las compuertas; cuánto tarda cada etapa lo pone el tamaño y la complejidad de tu sistema.
- ¿Cómo propongo una mejora?
- Con evidencia: el peldaño 15 pide que cada retrospectiva termine en una propuesta concreta de cambio a la escalera, con el incidente que la justifica. Las propuestas entran por pull request desde un fork en github.com/pkuschnirof/urazuke y las reviso antes de fusionarlas.
Exigile evidencia. No le leas el código.
Un método para que el modelo construya y vos decidas y verifiques. En ocho idiomas, con licencia abierta, y con los golpes de tres sistemas reales para que no tengas que darte los mismos.