Serie AI-Native · Prácticas de ingeniería

El próximo desarrollador en tu repositorio no es humano. Seis prácticas para prepararlo.

Cada práctica de abajo está explicada como se la explicaría a un adolescente inteligente de 15 años, y luego respaldada por un número de una semana de trabajo real en un repositorio. ~8 min.

El lector que nunca se salta nada

La semana pasada, antes de hacer merge de una rama, le entregué mi repositorio a un revisor de IA adversarial con una sola instrucción: find how this fails in production. No compliments. (Traducción: encuentra cómo falla esto en producción. Sin cumplidos.) Volvió con 21 hallazgos. Uno era un path traversal real — una verificación léxica que habría dejado que Recordings/../../.ssh/id_rsa pasara de largo sin problema. Yo mismo había revisado ese archivo. Se me pasó.

Ahí fue cuando la abstracción se me hizo concreta: el próximo desarrollador que lea tu código no es un humano cansado hojeando un diff. Es un agente que lee las 10.000 líneas completas, sigue cada rama y toma la estructura de tu repositorio literalmente. Si tu base de código solo es legible para humanos, impides que su mejor lector — y su revisor más severo — pueda ayudarte.

Así que la pregunta cambió de "¿está limpio este código?" a "can an agent work here?" (Traducción: ¿puede un agente trabajar aquí?) Seis prácticas responden a eso. Ninguna es nueva. Lo nuevo es para qué sirve cada una.

1 · OOP — la estructura ahora es legibilidad para agentes

Versión simple: la programación orientada a objetos consiste en agrupar el código en pequeñas unidades, cada una responsable de una sola tarea y que oculta cómo la realiza. La unidad promete "dame markdown, te doy fragmentos" — y nadie de afuera necesita saber más.

El argumento clásico a favor de OOP era la mantenibilidad humana. El nuevo argumento es más contundente: las costuras son donde los agentes pueden operar con seguridad. Cuando mi script de ingesta era un solo bloque procedural, un bucle de refactorización automatizado le puso 56/100 y apenas pudo mejorarlo (logró +2 y abandonó). Cuando lo reestructuré en tres costuras — un MarkdownChunker, un OpenAIEmbedder, a KnowledgeStore — cualquiera de ellas puede reemplazarse (otro proveedor de embeddings, otra base de datos) sin tocar las demás. Un agente al que se le pide "cambiar a un embedder local" ahora tiene un radio de impacto de una sola clase, en vez de todo el archivo.

Comprobante: puntaje de calidad 56 → 95/100 en la superficie Python del repositorio — tipado 100%, docstrings 100%, anidamiento 100% — con la propia compuerta de pruebas del repositorio en verde todo el trayecto.

2 · AI-native — los agentes son usuarios de primera clase

Versión simple: un repositorio AI-native trata a los agentes como usuarios, no como intrusos. Ofrece lo que un agente necesita para trabajar sin supervisión: una guía que explica la arquitectura y — lo más importante — una línea de meta detectable por máquinas.

Mi repositorio tiene un CLAUDE.md que documenta no solo qué hace el código, sino también las trampas ("nunca reemplaces en caliente un binario dentro del paquete firmado — macOS lo mata al ejecutarlo"). Y tiene un Makefile raíz con un solo objetivo: check. Ese objetivo es la definición de "terminado" del repositorio. El resultado se notó de inmediato: una herramienta de orquestación que apunté al repositorio descubrió make check por su cuenta, lo ejecutó y reportó un verde honesto. Sin configuración. El repositorio le dijo al agente cómo verificarse a sí mismo.

Comprobante: anyagent goal --drive descubrió Makefile:check, lo ejecutó, exit 0. La misma compuerta ahora corre en CI en cada push.

3 · Ingeniería de contexto — el contexto es un presupuesto, no una mochila

Versión simple: todo lo que metes en el prompt de una IA cuesta tiempo y atención. La ingeniería de contexto es decidir qué se gana un lugar ahí — y ajustarlo al tamaño del modelo que tiene que cargarlo.

El system prompt de mi asistente de IA había crecido calladamente hasta 87KB de paquetes de conocimiento acumulados. En un modelo en la nube con prompt caching, eso sale casi gratis. En el modelo local de 7B al que había cambiado durante una caída de la API, fue catastrófico — y de forma invisible: el modelo truncaba la mayor parte del prompt sin leerlo, mientras cada respuesta tardaba más de dos minutos. Lo medí: 0.3 segundos sin system prompt, 129.7 segundos con el paquete completo. Después de recortarlo a 5KB y mover los paquetes a archivos de carga bajo demanda: 3.0 segundos. Mismo modelo, mismo hardware, 43 veces más rápido — nada más borrando palabras que el modelo ni siquiera llegaba a ver.

Comprobante: 130s → 3s por respuesta, medido con llamadas cronometradas antes y después. Los paquetes no se borraron — se movieron a archivos que cargan solo cuando la tarea los necesita.

4 · Ingeniería de harness — que la verdad salga barata

Versión simple: un harness es el aparato alrededor de tu código que hace que verificar salga barato y mentir salga caro: sondas, compuertas, autopruebas. La regla es verificar a la altitud del usuario — probar lo que el usuario experimenta, no lo que devuelve la función.

Este fue el que salvó la semana. La transcripción de mi app no producía nada, en silencio. Las pruebas unitarias pasaban — la falla vivía en la maquinaria de permisos de macOS que solo se manifiesta en un app bundle real. El harness que la encontró: una app de sonda que reprodujo la señal de kill del sistema operativo, forense de crash reports que identificó los permisos de qué proceso importaban, y finalmente una autoprueba de altavoz a micrófono — voz sintetizada reproducida dentro del flujo en vivo del micrófono — que probó la solución de punta a punta sin un humano en el bucle. Cuando mi usuario dijo "I am not a testing machine" (Traducción: "no soy una máquina de pruebas"), tenía razón. Ese es el trabajo del harness.

Comprobante: tres causas raíz (bloqueo de permisos, atribución de prompts, inanición del run-loop), cada una aislada mediante una prueba diseñada a medida, y una autoprueba final que produjo 51 fragmentos de transcripción en vivo con una cadencia de ~1.2s, sin pasos humanos.

5 · Ingeniería de bucles — retroalimentación cerrada, puntuación honesta

Versión simple: un bucle es cualquier ciclo de actuar → medir → ajustar. La ingeniería de bucles consiste en hacer que esos ciclos sean cerrados (la medición realmente retroalimenta el sistema) y honestos (una meseta se reporta como meseta, nunca como un éxito falso).

El repositorio funciona con bucles en cada escala: una cadena de conmutación por error de LLM con un circuit breaker (si el proveedor principal falla a mitad de una llamada, el siguiente nivel responde); reintentos por fragmento en la transcripción (si falla la nube, lo local toma el fragmento, sin perder nada); y el bucle de refactorización de arriba, cuyo comportamiento más valioso fue detenerse — reportó 56→58, dijo "no change proposed" ("no se propone ningún cambio") y se detuvo. Un motor que infla su propia puntuación es peor que no tener motor. La meseta honesta me indicó exactamente dónde terminaba el esfuerzo de la máquina y dónde tenía que entrar el juicio humano.

Comprobante: el bucle de refactorización reportó su propia meseta en 58/100 en lugar de proclamar una victoria falsa; el paso guiado por un humano lo llevó a 95 con la misma compuerta. Cada paso pasó por el gate de pruebas, con rollback ante cualquier regresión.

6 · Ingeniería de grafos — la memoria son entidades más relaciones

Versión simple: los archivos y las carpetas olvidan cómo se relacionan las cosas entre sí. Un grafo —cosas conectadas con cosas— es lo que hace que el trabajo se acumule: esta reunión pertenece a ese proyecto, esta transcripción alimenta esa base de conocimiento.

La capa de memoria del repositorio tiene forma de grafo de principio a fin: las transcripciones se convierten en embeddings dentro de un almacén de conocimiento (recuperación por significado, no por nombre de archivo); las reuniones se exportan a un motor de grafo de conocimiento que mapea quién dijo qué sobre qué; y el borde más nuevo —"Projectize"— deposita las notas de una reunión dentro de la carpeta del proyecto donde continúa el trabajo, con el siguiente paso ya enrutado. Antes, una grabación era un callejón sin salida. Ahora es un nodo con bordes.

Comprobante: un clic en una reunión → un documento de notas con fecha en el repositorio del proyecto, con el siguiente paso auto-enrutado ya incrustado — la reunión se integró al grafo del proyecto en vez de pudrirse en una biblioteca.

Lo que se rompió en el camino (dejado a propósito)

• El bucle de refactorización automatizado se estancó en 58/100. Los motores enrutan y filtran; el juicio humano sigue siendo el que cierra las brechas.
• Cambié en caliente un binario fijo dentro de la app instalada para probar más rápido. macOS lo mató al instante por romper la firma de código del paquete. Lección archivada en la guía del repositorio para agentes, para que ningún agente —humano o no— la repita.
• De los 21 hallazgos adversariales, corregí 9 antes del merge y documenté los otros 12 en el PR en vez de fingir que no existían. Un ❌ honesto vale más que un ✅ falso.

La versión de una sola frase

Estructura tu código en costuras (OOP), dale a los agentes una puerta de entrada y una línea de meta (AI-native), gasta el contexto como si fuera dinero (ingeniería de contexto), abarata la verificación de la verdad (ingeniería de harness), cierra cada ciclo de retroalimentación con honestidad (ingeniería de bucles) y guarda la memoria como cosas-con-relaciones (ingeniería de grafos). Después, entrégale tu repositorio al revisor más implacable que encuentres —el que nunca se salta nada— y deja que te haga mejor.

Relacionado

• Mi IA detectó las citas falsas. Después señaló sus propios puntos ciegos.
• Estrategia como código
• Enseñar a las máquinas a vigilar