SERIE AI-NATIVE · Arquitectura
Un bucle, cuarenta y un comandos: cómo una herramienta crece sin convertirse en un cajón de trastos
Una herramienta que mantengo tiene cuarenta y un subcomandos y un solo bucle de control. El motor son 109 líneas. Añadir una capacidad requiere tres funciones. Aquí está el patrón, el ejemplo práctico y las tres reglas que evitan que un sistema de complementos se deteriore — ninguna de las cuales requiere la herramienta.
Resumen de 1 minuto
Qué es esto: la arquitectura de una herramienta personal de IA que ha crecido hasta 41 comandos sin convertirse en un cajón de trastos inconexos — un solo bucle de control compartido, y capacidades que se integran a él.
Por qué importa: el fracaso del cajón de trastos no es un problema de código, es lo que le pasa a cualquier sistema que crece — un equipo, un plan de estudios, los procesos de una empresa — cuando cada nueva necesidad recibe su propia maquinaria en vez de una adaptación para la maquinaria que ya tienes.
Qué puedes hacer: toma una decisión que tengas que enfrentar esta semana, escríbela como cuatro campos y haz una línea de aritmética a mano. Veinte minutos. Probablemente descubrirás que tu plan se apoya en algo más débil de lo que pensabas.
Contexto: un solo bucle es toda la idea, y esto no trata sobre mi herramienta
Todo lo que sigue viene de una sola base de código, y casi nada trata sobre esa base de código. La herramienta es privada y no puedes instalarla, que es la restricción honesta bajo la que escribí esto: si el valor de un artículo depende de que el lector obtenga lo que describe, es un folleto. Así que la prueba que me puse fue que cada principio aquí sobreviviera a la frase"…y nunca veré ese repositorio."
El tema es un problema que ya tienes. Mantienes algo que crece — una base de código, el proceso de un equipo, un curso que das, los sistemas de una casa. Cada nuevo requisito llega con apariencia de ser único. Y el camino de menor resistencia es siempre construirle su propia maquinaria.
El modo de fallo: una máquina nueva para cada necesidad
El fallo tiene una forma. Cada nuevo requisito llega con apariencia de ser único, así que recibe su propia maquinaria: su propio bucle, su propia regla de reintentos, su propia idea de qué significa "terminado", su propio registro de eventos que es sutilmente distinto al de al lado. Seis motores donde uno bastaría. (La versión de cocina es una superficie llena de aparatos de un solo uso, cada uno con su propio motor listo para romperse, frente a una batidora de pie con accesorios simples — pero la analogía es solo una rampa de entrada, no el argumento, así que lo dejo ahí.)
Nadie decide construir un cajón de trastos. Un cajón de trastos es lo que ocurre cuando nadie decide evitarlo. Y el costo no es el desorden — es que mejorar una cosa solo mejora esa cosa. Con un motor compartido, todas las capacidades mejoran a la vez.
La reducción: cuatro capacidades eran en realidad una sola con cuatro apariencias distintas
El giro en esta historia no es una idea ingeniosa. Es un hallazgo aburrido hecho al leer mi propio código.
Había cuatro bucles separados — uno que mejoraba una app generada, uno que refactorizaba una base de código, uno que hacía ingeniería inversa a un artefacto, uno que extraía una queja vaga para un producto. Cuatro dominios distintos, escritos con meses de diferencia, que parecían totalmente ajenos entre sí.
Eran la misma función. No parecidas — la misma, hasta una cláusula de guardia que aparecía idéntica en las cuatro, carácter por carácter, rechazando un conteo de iteraciones en cero. Escribí la misma línea defensiva cuatro veces sin darme cuenta, que es la señal más confiable de que algo quiere ser extraído: no que el código se parezca, sino que sigues reinventando por separado la misma pequeña precaución.
Debajo de cada una estaba esto:
Empieza en algún lado. Propón un candidato. Evalúalo contra algo externo a ti. Quédate con él solo si es mejor. Repite, con un límite estricto, registrando cada paso. Detente cuando llegues al objetivo o dejes de mejorar.
Eso es todo. Ese es el motor. Mejorar una app, limpiar una base de código, desarmar el producto de un competidor, elegir una estrategia, auditar un sistema de seguridad — todos tienen la misma forma, y las diferencias están enteramente en tres preguntas: qué cuenta como candidato, qué cuenta como mejor, y qué cuenta como permitido.
El motor, lo suficientemente pequeño como para leerlo
El controlador compartido son 109 líneas, incluyendo su documentación. Su núcleo es más o menos así:
best = seed
best_score = score(best)
while best_score < target and iterations_left:
candidate = propose(best, i)
candidate_score = score(candidate)
if accept(candidate, candidate_score, best, best_score):
best, best_score = candidate, candidate_score
record(i, candidate_score, accepted)
Tres cosas son estructurales, y cada una es una regla que puedes llevarte a cualquier dominio.
El límite no es opcional. El bucle no se puede construir con un límite menor a uno. No es "no debería" — es no puede; se niega. Cualquier proceso que pueda proponer puede desbocarse, y el lugar para frenarlo es el constructor, no una revisión de código.
El evaluador nunca es el proponente. La función que genera un candidato no puede ser la misma que lo evalúa. En el módulo de estrategia esto se impone desde la construcción: si pasas la misma función para ambas, lanza un error con el mensaje "never self-certify" (Traducción: nunca te auto-certifiques). Esta es la regla que la gente rompe todo el tiempo fuera del software: el equipo que escribe el plan también informa si el plan funcionó.
Cada paso se registra, incluidos los rechazados. La trayectoria es el resultado, no un artefacto de depuración. Saber la respuesta vale mucho menos que saber a qué otras respuestas superó.
Peldaño 1 — haz esto antes de seguir leyendo (2 minutos)
Elige cualquier proceso repetitivo que tengas: contratación, una revisión semanal, edición de borradores, selección de proveedores. Di en voz alta sus tres funciones. Proponer: ¿de dónde salen los candidatos? Evaluar: ¿qué, exactamente, decide que uno es mejor — y está fuera de ti?Aceptar: ¿qué te haría conservar un candidato que obtuvo peor evaluación?
La mayoría descubre que la segunda función falta. Ese es el hallazgo, no un error del ejercicio.
El ejemplo práctico: decidir qué hacer
El módulo más reciente es el que mostraré completo, porque la estrategia es el dominio donde la falsa rigurosidad es más común y más fácil de ocultar.
Le das un brief con cuatro partes: un objetivo, los criterios de éxito que indicarían que lo lograste, la evidencia que realmente tienes, y las opciones que estás considerando. Cada evidencia lleva una etiqueta de cómo la sabes: medida, documentada, previa (datos de otra persona, no tuyos), o juicio (tú lo supones).
Luego ejecuta el bucle. Proponer = añade la opción que cubra la mayor cantidad de criterios aún sin cubrir. Evaluar = una sola línea de aritmética. Aceptar = solo si es estrictamente mejor, y legal.
Aquí está la regla completa de evaluación, y es la parte que vale la pena robar:
score = (criteria covered / all criteria) × weight(weakest evidence)
measured 1.00 · documented 0.90 · prior 0.75 · judgment 0.50
La cobertura es lo que lograste. El peso del nivel es cuánto derecho tienes a creerlo. Y se multiplican.
Esa multiplicación es toda la opinión de la herramienta, así que déjame defenderla. Si los promedias, un plan que cubre todo solo con suposiciones parece una versión apenas más débil de un plan basado en mediciones — como un ochenta y tantos por ciento de bueno. Eso es falso. No es una afirmación más débil del mismo tipo; es una afirmación de otro tipo. Multiplicar lo deja claro: la cobertura total en nivel de juicio queda limitada a 0.50, por más completo que parezca.
Ejecuta el ejemplo incluido — una decisión real sobre reducir el tiempo de onboarding para nuevos ingenieros — y elige tres opciones, cubre 4 de 4 criterios de éxito, y obtiene una puntuación de 0.75. Puntaje perfecto en cobertura, y aun así pierde una cuarta parte de su puntuación, porque una de las tres opciones se apoya en un benchmark de la industria en vez de algo medido internamente.
El resultado lo dice explícitamente:
score 0.750 at prior tier · 4/4 criteria · stopped on plateau
✓ devcontainer for the five main repos [documented]
✓ CI gate on stale setup docs [documented]
✓ golden-path starter task [prior]
→ the claim is only as strong as its weakest evidence: prior
Un plan que lo cubre todo y te dice que se apoya en un artículo de revista vale más que un plan que lo cubre todo y no dice nada.El descuento es el producto.
Dos comportamientos más, ambos posiciones morales disfrazadas de ingeniería:
Una restricción dura detiene el proceso; no resta puntos. Una opción en el ejemplo cruza un límite declarado — daría acceso a producción a los nuevos empleados desde el primer día. El bucle no le resta puntos ni deja que un plan suficientemente atractivo se compre el paso. Simplemente se detiene, y exige que una persona lo apruebe con nombre y apellido. Todo lo que pueda ser superado por un número, eventualmente lo será si alguien lo desea lo suficiente.
La aritmética es deliberadamente simple. Ningún modelo de lenguaje se ejecuta en el momento de la decisión. El mismo brief, la misma respuesta, siempre — y cualquier revisor puede recalcular la puntuación a mano y pillar a la máquina si miente. Una recomendación que no puedes volver a calcular no es evidencia; es una afirmación con buena postura.
Peldaño 2 — la versión de veinte minutos, sin herramienta
Toma una decisión real que tengas por delante. En una sola página, escribe: el objetivo · 3–5 criterios que definirían el éxito · todas las opciones que estás considerando · y, junto a cada opción, qué criterios cubre y cómo lo sabes (medido / documentado / datos de otra persona / tú lo supones).
Ahora calcula: fracción de criterios cubiertos × el peso de tu evidencia más débil. Ese número es tu plan. En la primera pasada honesta de la mayoría, el resultado cae entre 0.35 y 0.55, y casi nunca la brecha es la cobertura — suele ser que toda la estructura se apoya en una suposición no medida que nadie había nombrado.
Cuatro capacidades más, mismo bucle
El valor del patrón es que añadir la siguiente capacidad resulta aburrido. Cuatro ejemplos breves:
Refactoriza una base de código. Propón un cambio de código, evalúa su calidad estructural y acepta solo si las pruebas siguen pasando — si no, revierte el cambio. La regla de aceptación es donde está la seguridad. Una puntuación de calidad por sí sola mejoraría felizmente la forma de un programa roto.
Audita un despliegue contra un estándar de seguridad. Esta es la mejor demostración de que el patrón no trata realmente sobre software. Una rúbrica de control publicada parece un cuestionario. Es un evaluador. Una vez que lo ves, la rúbrica se convierte en la función de evaluación; el bucle recoge evidencia de cada ítem de forma autónoma, y un documento de cumplimiento se transforma en algo que puede hacer fallar un build. Cualquier checklist, estándar o guía de evaluación que te hayan dado alguna vez es un bucle cerrado que alguien dejó a medias.
Evalúa la preparación empresarial de un sistema. Siete pilares, y cada hueco imprime el comando exacto que lo cierra. Un hallazgo sin acción siguiente es solo una queja.
Reflexión, como práctica medida. Esta es la que mantiene honesto todo el sistema. Lleva un registro de predicciones con probabilidades y fechas de vencimiento, las evalúa cuando se resuelven y caduca conclusiones así que las creencias se vuelven a poner a prueba en vez de acumularse. Una revisión semanal te pregunta cómo crees que salió. Un registro puntuado con Brier pregunta si tuviste razón, y lo recuerda.
Tres reglas que evitan que un sistema de complementos se degrade
Los complementos son la causa de muerte de la mayoría de los sistemas. Extensiones de navegador, software empresarial, documentos de procesos de un equipo, la carpeta de “misceláneos”. Hasta ahora, tres reglas han funcionado.
Regla 1 — una nueva capacidad no puede traer su propio bucle. Si tu capacidad necesita su propio bucle, todavía no la entiendes del todo. Es una afirmación fuerte y a veces es incorrecta, pero se equivoca mucho menos de lo que parece en el momento, y el modo de fallo que previene es peor que la fricción que causa.
Regla 2 — cruza los límites a través de una costura, nunca con un import. El adjunto de estrategia escribe su grafo de decisiones en algún lugar. No tiene idea de dónde. Tiene un puerto —una interfaz abstracta— y un adaptador aparte lo conecta a un almacén real. Cambia el almacén, no toques nada más, ejecuta la misma batería de pruebas contra ambos cuerpos.
David Parnas escribió la razón de esto en 1972, y nadie la ha mejorado:
"Its interface or definition was chosen to reveal as little as possible about its inner workings." (Traducción: Su interfaz o definición fue elegida para revelar lo menos posible sobre su funcionamiento interno.)
— D. L. Parnas, On the Criteria To Be Used in Decomposing Systems into Modules, CACM 15(12), 1972 [R1]
Su argumento no era estético. Estaba haciendo una predicción sobre el cambio: empieza por las decisiones de diseño que más probablemente cambiarán, y esconde cada una dentro de un módulo para que, cuando cambie, el cambio se detenga ahí. Cincuenta y cuatro años después, las decisiones más propensas a cambiar en mi herramienta son exactamente las que están detrás de costuras, y no fue planeado — lo descubrí equivocándome en los lugares donde no lo había hecho.
Tuve una demostración en vivo mientras construía el adjunto de estrategia. Lo conecté a un almacén de grafos estricto que pertenece a otro repositorio mío, y sus reglas de integridad rechazaron mi escritura: decision nodes are human-authored only. Había modelado un conjunto de opciones candidatas como una “decisión”. No lo es. Un bucle que propone candidatos está haciendo análisis; decidir es algo que hace una persona. La regla era correcta y mi modelo estaba equivocado, así que cambié el modelo. Eso es lo que te da una costura real: lo que está al otro lado puede negarse, y esa negativa es información.
Regla 3 — el sistema debe poder decirle que no a su dueño. Más sobre esto a continuación, porque es la regla con la que todos están de acuerdo y nadie implementa.
Peldaño 3 — el incómodo (10 minutos)
Encuentra una regla en tu trabajo que actualmente viva en un documento, una norma o tus buenas intenciones — “no lanzamos los viernes”, “toda afirmación lleva fuente”, “ningún proveedor sin dos referencias”.
Haz que algo realmente se niegue. Una prueba, un ítem en una lista de verificación que alguien deba marcar físicamente, un formulario que no se pueda enviar. Luego intenta violar tu propia regla y confirma que de verdad te detiene.Una regla que no puede activarse es solo una preferencia disfrazada de norma.
La parte que hace creíble todo lo demás
Aquí viene la sección que yo mismo saltaría si estuviera tratando de venderte algo.
Dos comandos aparecen en el propio manual de esta herramienta con una etiqueta de advertencia:NINGUNO ESTÁ CONSTRUIDO — son deseos, no capacidades.Fueron descritos en la documentación antes de existir, y en vez de borrar el párrafo en silencio, el párrafo se quedó y sumó una advertencia. Es de las entradas más útiles del manual, porque su función es evitar que una futura versión de mí prometa con confianza una función que no existe.
Y el caso más agudo. El sistema estaba documentado como si tuviera un bucle de auto-mejora que almacenaba una lección después de cada sesión. Así lo decía el manual. Lo que realmente tenía era un archivo,lessons.jsonl, congelado en42 entradas— intacto tras unas veintitrés entregas de trabajo, mientras la documentación describía alegremente un bucle que supuestamente estaba en marcha.
Un bucle documentado pero nunca construido esindistinguible de uno que simplemente se rompió en silencio. Esa es toda la lección, y se generaliza de forma brutal: todo proceso que tu organización cree tener, y que nunca ha visto activarse, está en ese estado ahora mismo. La lista de verificación de onboarding. Los seguimientos post-mortem. La revisión trimestral de accesos.
Revisé ese archivo de nuevo mientras escribía este párrafo, para asegurarme de no estar citando un hecho que ya se hubiera corregido.
Sigue en 42.
Que es, creo yo, la frase más honesta de este artículo — y se queda, porque un texto sobre construir sistemas confiables que omitiera en silencio el hueco sin arreglar de su autor estaría demostrando justo lo contrario de su tesis.
Patrones y anti-patrones
| Patrón | Antipatrón que reemplaza |
|---|---|
| Un solo controlador; las capacidades aportan tres funciones | Cada capacidad trae su propio bucle, regla de reintento y registro |
| El límite vive en el constructor y puede negarse | "Le ponemos un timeout después" |
| El evaluador y el proponente son objetos inequívocamente distintos | El equipo que redactó el plan es quien informa sobre el plan |
| La calidad de la evidencia multiplica la puntuación | La confianza se promedia, así que la especulación diluye en vez de poner un tope |
| Las restricciones duras detienen el proceso para intervención humana | Las restricciones duras se tratan como penalización, así que un número lo suficientemente grande las salta |
| Cruzar límites a través de un puerto con dos implementaciones activas | Importación directa, así que la dependencia nunca puede negarse ni ser reemplazada |
| Reglas que se ejecutan y pueden hacer fallar la construcción | Reglas en un documento que nadie ha visto activarse |
| Aritmética deliberadamente simple que un revisor puede volver a calcular | Un modelo en la ruta de decisión, así que la respuesta se mueve y no puede ser auditada |
El primer principio, en una sola frase
Una capacidad debería requerir tres funciones, no una máquina nueva — y lo que construyas debe poder negarse a quien lo creó.
Qué hacer en los próximos veinte minutos
| Haz | Cómo sabes que funcionó | Para cuándo |
|---|---|---|
| Nombra proponer / evaluar / aceptar para un proceso repetitivo que mantengas | Puedes decir los tres en una frase, y quien evalúa no eres tú | Hoy, 2 min |
| Escribe una decisión real como objetivo · criterios · opciones · evidencia con niveles | Una página; cada opción dice cómo lo sabes | Esta semana, 20 min |
| Calcula a mano: cobertura × peso del nivel de evidencia más débil | Obtienes un número entre 0 y 1, y puedes decir exactamente qué lo está limitando | En la misma sesión |
| Convierte una regla escrita en algo que realmente te detenga | Intentaste romperla y de verdad no pudiste avanzar | Esta semana, 10 min |
| Elige un proceso que creas que corre solo y revisa la marca de tiempo de su último resultado | Sabes la última vez que se ejecutó, por evidencia y no por memoria | Hoy, 5 min |
La última fila suele dar en el clavo. Apostaría a que encuentras al menos un 42 silencioso.
Referencias
- Parnas, D. L. (1972). On the Criteria To Be Used in Decomposing Systems into Modules. Communications of the ACM 15(12), 1053–1058. PDF — citado textualmente arriba; verificado 2026-09-29.
- Conway, M. E. (1968). How Do Committees Invent? Datamation. melconway.com — "organizations which design systems (in the broad sense used here) are constrained to produce designs which are copies of the communication structures of these organizations" (Traducción: las organizaciones que diseñan sistemas —en el sentido amplio usado aquí— están forzadas a producir diseños que son copias de las estructuras de comunicación de esas organizaciones), verificado textualmente 2026-09-29. Por qué está aquí: un cajón de trastos de capacidades suele ser el retrato de un equipo que nunca tuvo una conversación sobre el motor compartido.
- Brier, G. W. (1950). Verification of Forecasts Expressed in Terms of Probability. Monthly Weather Review 78(1), 1–3. La regla de evaluación detrás del registro de predicciones descrito arriba.
Escrito por Paul Jialiang Wu. Cada cifra de este artículo fue tomada directamente del código el 29/09/2026: 41 subcomandos, 8 bucles, un controlador compartido de 109 líneas, 1,035 pruebas superadas y un archivo de lecciones que sigue en 42. La herramienta es privada, por eso nada aquí depende de tener acceso a ella. Tipos de afirmaciones: los números son medidos, las tres reglas son posturas de diseño, y la afirmación de que se transfieren a dominios fuera del software es una inferencia que me encantaría debatir.