Image: AI generated
Una pregunta
Abre el archivo más largo de tu proyecto. ¿Cuántas funciones tiene?
Pídele a un agente de IA que modifique una función en ese archivo. El agente lee el archivo completo. Lo abrió porque necesitaba una función, pero vinieron 19 funciones innecesarias de acompañantes.
Aquí es donde comienza el problema.
Código que leen humanos vs. código que operan agentes
Hasta ahora, el código se escribía para que los humanos lo leyeran. Nombrar bien las variables, escribir comentarios, producir documentación: todo era para reducir la carga cognitiva humana.
En la era de los agentes, la pregunta cambia. ¿El código fácil de leer para humanos es el mismo que el código fácil de operar para agentes?
No lo es.
| Humano | Agente IA | |
|---|---|---|
| Navegación | Recorre el árbol de directorios con la vista | Busca con grep |
| Abrir archivos | Hace scroll en el IDE | read file — carga todo |
| Juicio de contexto | Intuición + experiencia | Solo conoce lo que está en el contexto |
| Código innecesario | Lo ignora | Consume presupuesto de contexto |
| Archivo de 2,000 líneas | Ve solo lo que necesita | Procesa todo |
Un humano haciendo scroll en un archivo de 2,000 líneas tiene una intuición que dice “no toques esta parte”. Un agente no tiene esa intuición. Cuando lee 2,000 líneas, 1,950 son contaminación de contexto.
La investigación lo confirma. Cuando se mezcla información irrelevante, el rendimiento de la IA cae entre un 30 y un 85%. El rendimiento baja incluso cuando los tokens innecesarios son espacios en blanco. Que un contexto más corto es mejor no es intuición, sino evidencia experimental.
No metas un robot en una oficina humana. Construye una fábrica donde los robots puedan trabajar.
Tres cosas que los agentes necesitan
Para que los agentes trabajen de forma fiable en un código base, tres cosas deben estar en su lugar.
1. Debe ser legible — sin ruido
Un concepto por archivo. El nombre del archivo es el nombre del concepto.
before: read utils.go → 20 funciones, 19 innecesarias
after: read check_one_file_one_func.go → 1 función, exactamente lo necesario
filefunc resuelve este problema. Separa el código en unidades semánticas con 22 reglas estructurales. Aplicado al framework Hono (23k+ estrellas), dividió 186 archivos en 626. Los 4,419 tests pasaron. Los archivos se multiplicaron por 3.4, pero ni una línea de lógica cambió.
“¿No serán demasiados archivos?” — Los agentes no navegan directorios. Buscan. Da igual que haya 500 o 1,000 archivos: un grep y listo. No abrir 295 archivos innecesarios importa más que encontrar los 5 que necesitas.
2. Debe ser verificable — mecánicamente
Cuando modificas una función sin tests, nadie sabe qué se rompe. El agente tampoco. Cae en un doom loop.
before: 0 tests, sin saber qué se rompe al modificar
after: 527 funciones con tests, cambios de comportamiento detectados al instante
tsma resuelve este problema. Indexa cada función del proyecto, detecta la presencia de tests, mide cobertura y devuelve las ramas no cubiertas con números de línea.
Sin feedback, pedirle a un LLM que escriba tests se estanca en un 60–70% de cobertura. Dile “línea 41, 44, 70 sin cubrir” y alcanza el 100%. Mismo modelo. La única diferencia es la resolución del feedback.
Resultados experimentales en un proyecto con 527 funciones: completado hasta TODO 0. Un agente autónomo declaró “todo hecho” en 40. Aplica el ratchet: 527 completados.
3. Las especificaciones deben ser verificables cruzadamente
Debe ser mecánicamente verificable si los esquemas de API, esquemas de BD, políticas de seguridad y transiciones de estado son consistentes entre sí. Cuando uno cambia, debes saber antes de compilar si entra en conflicto con los demás.
before: 200 endpoints, humanos verifican consistencia de specs
after: un operationId encadena todas las capas, las máquinas detectan el drift
yongol resuelve este problema. Encadena 10 SSOTs (OpenAPI, DDL, sqlc, SSaC, Rego, Hurl, etc.) a través de un único operationId y valida cruzadamente con ~287 reglas. user_id es string en OpenAPI pero BIGINT en DDL — las herramientas existentes no capturan contradicciones entre capas como esta.
Una estructura que atraviesa las tres herramientas
filefunc, tsma y yongol son herramientas independientes, pero comparten una estructura común.
filefunc: 22 reglas estructurales → validate → corregir → repetir
tsma: medir cobertura → feedback de ramas no cubiertas → corregir → repetir
yongol: validación cruzada → detectar drift → corregir → repetir
Todo el mismo bucle.
LLM genera → herramienta determinista juzga → resultado devuelto al LLM → repetir
Symbolic Feedback Loop. Una estructura cíclica donde herramientas deterministas corrigen la generación probabilística de los LLMs. No es IA verificando IA, sino máquinas verificando IA.
Dale opiniones y halaga. Dale hechos y corrige. Pregúntale “¿el código está bien?” y responde “sí, se ve genial”. Dile “línea 41: nombre de campo no coincide” y lo corrige inmediatamente. Feedback sin nadie a quien halagar, porque los números y las ubicaciones no son emociones.
De legacy a agent-operable
No necesitas cambiar un código base existente de golpe. Esto no es cimentación, es refuerzo sísmico. Reforzar el edificio sin cerrar la tienda.
Paso 1 — Hazlo legible
Empieza con los archivos más largos. Ejecuta filefunc validate y lleva las violaciones a cero. Todos los tests existentes deben pasar.
Paso 2 — Hazlo verificable
Repite tsma next. Añade tests a las funciones sin testear y cubre las ramas faltantes. Incluso si el agente muere a mitad de camino, el progreso se conserva. Un nuevo agente ejecuta tsma next y continúa donde quedó.
Paso 3 — Validación cruzada
Introduce SSOTs y ejecuta yongol validate. Las máquinas capturan contradicciones entre capas.
Cada paso es independiente. Puedes hacer el paso 2 sin el 1, o el paso 1 sin el 2. Pero cuando los tres se combinan, el alcance del trabajo autónomo de agentes se expande drásticamente.
Cambiar el sistema operativo
Un agent-operable codebase no es simplemente linting o herramientas. Es cambiar el sistema operativo del código base.
| human-readable | agent-operable | |
|---|---|---|
| Tamaño de archivo | Rango scrolleable para humanos | Un concepto |
| Tests | Mejor si los hay; la intuición cubre el resto | Obligatorio para cada función |
| Specs | Documentos, wikis, comunicación verbal | Declarativos, verificables cruzadamente, legibles por máquinas |
| Feedback | Revisión de PR (horas) | Ejecución de verificador (segundos) |
| Criterio de fin | Humano dice “ya está” | Máquina dice “quedan 487” |
Mucha gente está haciendo el tren más rápido. Modelos más grandes, agentes más inteligentes, mejores prompts.
Cuanto más rápido va el tren, más importan las vías. Casi nadie está tendiendo vías todavía.
Artículos relacionados
- filefunc — Un concepto por archivo — Convención de estructura de código que elimina la contaminación de contexto del LLM con 22 reglas estructurales
- tsma — Línea de defensa contra regresiones en código legacy — Automatización de tests basada en ratchet que completa 527 funciones hasta TODO 0
- Por qué los agentes de código funcionan y por qué fallan — Análisis estructural del Symbolic Feedback Loop
- Topología de feedback sobre coeficiente intelectual del modelo — Por qué el mismo modelo se detiene en 40 o completa 527
- whyso — Lo que git blame no muestra — Extracción automática de historial de cambios por archivo
Referencias
- Stanford, “Lost in the Middle: How Language Models Use Long Contexts” (2024) — Caída de rendimiento del 30%+ cuando la información relevante queda enterrada en el medio del contexto
- Amazon, “Context Length Alone Hurts LLM Performance” (2025) — Caída de rendimiento del 13.9–85% incluso cuando los tokens innecesarios son espacios en blanco
- Caso de estudio del framework Hono — 186 archivos → 626 archivos, los 4,419 tests pasaron
- Caso de estudio de 527 funciones con tsma — PASS 246 (46.7%), DONE 281 (53.3%), TODO 0
- Experimento Ratchet Pattern — agente autónomo 40/527 (7.6%) vs ratchet CLI 527/527 (100%)