Consejos clave — Con saber esto, ya puedes dar instrucciones
El mayor problema al pedir a los agentes que modifiquen código es tener 20 funciones empaquetadas en un solo archivo. Necesitas una función, abres el archivo y 19 funciones innecesarias vienen de regalo. Esto reduce el rendimiento del agente un 30-85%.
La solución son tres frases. Soporta Go, TypeScript y Python.
Al agente: “Encuentra el archivo más largo y divídelo por función. El nombre del archivo debe coincidir con el nombre de la función. Todos los tests existentes deben pasar.”
Al agente: “Ejecuta filefunc validate y lleva las violaciones a 0. Todos los tests existentes deben pasar.”
Al agente: “Repite tsma next para agregar tests a todas las funciones. Si aparecen ramas no cubiertas, agrega tests que las cubran también. Hasta que salga All functions complete.”
Incluso sin leer código, estas tres frases bastan. Las herramientas juzgan, los agentes ejecutan. Tú solo tomas decisiones.
“¿No habrá demasiados archivos?” — Los archivos aumentan 3-14x. Pero los agentes no abren directorios. Buscan. Sean 500 o 1,000 archivos, un solo comando de búsqueda es suficiente.
“¿Y el código legado sin tests?” — Repite tsma next. Si el agente muere a medio camino, el progreso se preserva. El nuevo agente ejecuta tsma next y continúa. Verificado con 527 funciones.
Prueba rápida
Abre la app de la Clase 1 con Claude Code:
“¿Cuál es el archivo más largo en este proyecto? ¿Cuántas funciones tiene?”
Lo más probable es que varias funciones estén empaquetadas en un solo archivo. Ahora pide:
“Separa cada función de ese archivo en archivos independientes. El nombre del archivo coincide con el nombre de la función.”
Después de separar, prueba:
“Encuentra la función que maneja completar tareas y explícala.”
Antes de separar, el agente tenía que leer el archivo largo completo. Después de separar, solo abre complete_todo.go. El costo de exploración del agente se reduce — ves de primera mano el efecto de “un archivo, un concepto.”
Por qué debes dar instrucciones de esta manera
Introducción: No metas robots en una oficina de humanos
A lo largo de las Clases 1-7 aprendimos a prevenir drift (Hurl), separar decisiones de implementación (yongol), forzar progreso con trinquetes (Ratchet Pattern), y hacer ingeniería inversa del sesgo de adulación (IFEval).
Incluso con todo eso, queda una cosa. La estructura del propio código.
Cuando le dices a un agente “modifica esta función”, ¿qué hace? Busca el archivo, abre el archivo, lee el contenido, modifica. La unidad de exploración del agente es el archivo.
¿Pero qué si un archivo tiene 20 funciones? Necesitas una función, abres el archivo y 19 innecesarias vienen de regalo. Esto es contaminación de contexto.
No metas robots en una oficina de humanos. Construye una fábrica donde los robots puedan trabajar. Lo mismo para el código.
Código legible por ingenieros ≠ Código operable por agentes
Los ingenieros leen código desplazándose por archivos y captando contexto. Incluso en un archivo de 2,000 líneas, la experiencia proporciona intuición para “no toques esta parte.”
Los agentes no tienen esa intuición.
La investigación muestra que el rendimiento cae un 30-85% cuando se mezcla información irrelevante.1
Contexto más corto es mejor. Entonces divide estructuralmente el código para que solo entre lo necesario. filefunc llena ese vacío. Soporta proyectos Go, TypeScript y Python.
filefunc — Un archivo, un concepto
El principio central de filefunc es uno solo.
Un archivo, un concepto. Nombre del archivo = nombre del concepto.
# Sin filefunc
read utils.go → 20 funcs, 19 innecesarias. Contaminación de contexto.
# filefunc
read check_one_file_one_func.go → 1 func. Exactamente lo necesario.
Demostrado en el framework Hono (23k+ estrellas). 186 archivos divididos en 626. 4,419 tests, ni uno se rompió. Los archivos aumentaron 3.4x pero la lógica no cambió ni una línea. Refactorización puramente estructural.
Elegir los 5-10 que necesitas importa menos que no abrir los 290 que no necesitas.
Los programas son solo tres cosas
El criterio de división de archivos de filefunc no es arbitrario. Cualquier programa se puede hacer con una combinación de tres operaciones:
- Secuencia — Ejecutar de arriba a abajo
- Selección — Elegir un camino según condiciones
- Iteración — Repetir la misma operación múltiples veces
Esto fue demostrado matemáticamente en 1966 (teorema de Bohm-Jacopini). filefunc fuerza que cada función tenga solo uno de estos tres tipos de flujo.
No necesitas leer este código. Lo importante es que //ff:what tiene una descripción de una línea de lo que hace la función:
//ff:func feature=validate type=rule control=sequence
//ff:what F1: validates one func per file
func CheckOneFileOneFunc(gf *model.GoFile) []model.Violation {
| control | Significado | Límite de anidamiento |
|---|---|---|
sequence | Ejecución secuencial | 2 niveles |
selection | Ramificación (switch) | 2 niveles |
iteration | Bucle | 2-3 niveles |
¿Por qué limitar el anidamiento? Cuando condiciones dentro de condiciones dentro de bucles dentro de condiciones alcanzan profundidad 3, tanto humanos como agentes se confunden. Limitar a profundidad 2 simplifica cada función, reduciendo efectos secundarios cuando los agentes modifican.
22 reglas de validación — No necesitas memorizarlas
filefunc tiene 22 reglas. Parece mucho pero no necesitas memorizarlas. Ejecuta filefunc validate y la herramienta encuentra todas las violaciones, y el agente las corrige. Tú solo dices “lleva las violaciones a 0.”
Codebook y anotaciones — El mapa del agente
Codebook (codebook.yaml):
Un codebook es la lista de vocabulario del proyecto. El mapa del agente IA. Tampoco necesitas crear este archivo tú mismo — dile al agente “crea codebook.yaml para este proyecto.” Con un codebook, el agente encuentra archivos exactos sin exploración.
Anotaciones:
//ff:func feature=validate type=rule control=sequence
//ff:what F1: validates one func per file
//ff:why Primary citizen is AI agent. 1 file 1 concept prevents context pollution.
func CheckOneFileOneFunc(gf *model.GoFile) []model.Violation {
Estas anotaciones sirven como índice de búsqueda. Sin infraestructura pesada como embeddings vectoriales o RAG, un solo grep produce una lista precisa de archivos.
Con filefunc + codebook, el agente encuentra con precisión solo los 5 archivos necesarios entre 300. Los otros 295 ni se abren.
tsma — Línea de defensa contra regresiones de código legado
El código ahora es legible por el agente (filefunc). Ahora el agente necesita saber si puede modificar de forma segura. Modificar una función sin tests significa que nadie sabe qué se rompe.
Imagina heredar un código legado de 100K líneas. Sin tests. Quieres refactorizar pero tocar algo podría romper cualquier cosa.
El 60-80% de los presupuestos de TI del Fortune 500 están atrapados en este punto muerto.
tsma resuelve los tres problemas: no saber por dónde empezar, no poder verificar la calidad de los tests, y estancarse al 60-70% sin retroalimentación.
tsma next — Un solo comando
$ tsma next
Este solo comando conduce todo el bucle. Repite hasta que aparezca “All functions complete!”
La retroalimentación de tsma — reportar ramas no cubiertas con números de línea precisos — es lo que cambia dramáticamente los tests del LLM.
Sin retroalimentación: Cobertura 60-70%
Con retroalimentación: Cobertura 100% (para funciones alcanzables)
Tres líneas de números de línea separan el 60% del 100%.
Verificado con 527 funciones
| Resultado | Cantidad | Proporción |
|---|---|---|
| PASS (100% cobertura de ramas) | 246 | 46.7% |
| DONE (mejor esfuerzo) | 281 | 53.3% |
| TODO (sin procesar) | 0 | 0% |
Los agentes mueren pero el progreso se preserva en .tsma/session.json. Múltiples agentes pueden trabajar en rotación sin conflictos. Atómico a nivel de función.
filefunc + tsma + whyso: Tres herramientas combinadas
filefunc fuerza un archivo por función, así que la indexación de funciones de tsma equivale a indexación de archivos. Test por función = test por archivo. Cero costo de rastreo.
whyso también se beneficia: como func = file, el historial de cambios por función se mapea con precisión a por archivo.
4 condiciones para un Agent Operable Codebase
| Condición | Herramienta | Efecto |
|---|---|---|
| 1. Un concepto por archivo | filefunc | Bloquea contaminación de contexto |
| 2. Tests para todas las funciones | tsma | Detecta regresión post-modificación |
| 3. Referencias simbólicas para conexiones | operationId (yongol) | Rastreo entre capas |
| 4. Eliminar acoplamiento implícito | whyso coupling | Detectar dependencias ocultas |
Mensaje central de la Clase 8: No hagas trenes más rápidos. Tiende rieles.
No modelos más grandes, no agentes más inteligentes — la estructura para que los agentes trabajen viene primero.
Ejercicio (filefunc + tsma)
Requisitos: Proyecto (Go, TypeScript o Python — la app de la Clase 1 funciona), filefunc, tsma (pide al agente que las instale).
Objetivo: Convertir un proyecto existente en un agent-operable codebase.
Paso 1 — Aplicar filefunc validate
filefunc validate
“Corrige todos los ERRORs de los resultados de filefunc validate. Los tests existentes no deben romperse.”
Paso 2 — Separar funciones que violan las reglas
- Archivos con múltiples funciones → separar cada función en archivos independientes
- Coincidir nombres de archivo con nombres de función
Paso 3 — Medir cobertura con tsma
tsma status
“Repite tsma next para agregar tests. Si aparecen ramas no cubiertas, agrega tests que las cubran. Hasta All functions complete.”
Paso 4 — Verificar resultados
- filefunc validate: 0 errores
- tsma status: TODO 0
- Tests existentes: todos pasan
Artículos relacionados
- filefunc — Un archivo, un concepto
- tsma — Línea de defensa contra regresiones de código legado
- whyso — Lo que git blame no muestra
Curso completo de Reins Engineering
| Clase | Título |
|---|---|
| Clase 1 | Cómo dirigir la IA |
| Clase 2 | Cómo desconfiar de la IA |
| Clase 3 | Aplicaciones irrompibles |
| Clase 4 | Decisiones fuera del código |
| Clase 5 | IA con riendas |
| Clase 6 | Si pasa, se bloquea |
| Clase 7 | Invertir la adulación |
| Clase 8 | La fábrica de agentes |
| Clase 9 | Automatización más allá del código |
| Clase 10 | La ley de los datos |
Fuentes
- Stanford, “Lost in the Middle: How Language Models Use Long Contexts” (2024) — 30%+ de caída de rendimiento cuando la información relevante se entierra en medio del contexto
- Amazon, “Context Length Alone Hurts LLM Performance” (2025) — 13.9-85% de caída de rendimiento incluso cuando los tokens innecesarios son espacios en blanco
- Teorema de Bohm-Jacopini (1966) — Cualquier programa expresable como combinación de tres estructuras de control: secuencia, selección, iteración
- Demostración en framework Hono — 186 archivos → 626 archivos divididos, los 4,419 tests pasaron
- Demostración tsma con 527 funciones — PASS 246 (46.7%), DONE 281 (53.3%), TODO 0
- Estadísticas de presupuesto TI Fortune 500 — 60-80% atrapado en mantenimiento de legado
Stanford “Lost in the Middle” (2024): 30%+ de caída cuando la información relevante se entierra en medio del contexto. Amazon “Context Length Alone Hurts LLM Performance” (2025): 13.9-85% de caída incluso cuando los tokens innecesarios son espacios en blanco. ↩︎