Ingeniería con IA · Ingeniería de agentes
Tiempo de lectura · 7 min
El contexto es infraestructura: mantener alineados a los agentes en proyectos de software prolongados
Cómo StackLiberate mantiene alineados a los agentes de programación con conocimiento duradero del repositorio, contexto enfocado, planes explícitos, restricciones persistentes y entregas claras entre sesiones.
Un agente de programación puede saber muchísimo de un repositorio a las 2:00 de la tarde y casi nada en una sesión nueva al día siguiente.
No es necesariamente un fallo del modelo.
Es una característica del entorno.
Los proyectos duran meses o años. Las sesiones son temporales. Las ventanas de contexto son finitas. Las conversaciones se compactan. Los modelos cambian. Los ingenieros cambian de herramientas. El trabajo pasa entre ramas, terminales, computadoras y, finalmente, personas que no estaban cuando se tomó una decisión.
Si el conocimiento de ingeniería importante solo existe en la conversación que lo produjo, ya es frágil.
Al construir StackLiberate hemos decidido tratar el contexto de otra forma:
El contexto no es algo que pegamos en un agente antes de una tarea. Es infraestructura que el proyecto necesita para seguir siendo comprensible.
No buscamos que un agente recuerde todo.
Buscamos que recordarlo todo sea innecesario.
El trabajo prolongado expone los límites de la memoria conversacional
Las tareas cortas pueden dar una impresión engañosa del desarrollo con agentes.
Al pedir un componente pequeño, todo el problema puede caber en una sesión:
Solicitud
↓
Leer código
↓
Implementar
↓
Probar
↓
Terminar
El desarrollo prolongado de un producto es distinto.
Una función puede depender de decisiones arquitectónicas de hace tres meses. Otra parte ya puede resolver medio problema. Un atajo rechazado antes puede volver a parecer atractivo para un agente nuevo. Una restricción obvia al diseñar el subsistema puede ser invisible desde el archivo actual.
El fallo es sutil porque el agente nuevo puede ser competente.
Lee el código que encuentra.
Ve una solución local razonable.
La implementa limpiamente.
Pero puede faltarle la historia que explica por qué el sistema tiene esa forma.
Lo hemos visto repetidamente: un agente que entendía un límite puede proponer después un atajo que lo cruce cuando el razonamiento pertinente ya no está en su contexto.
Eso nos enseñó una distinción importante:
La inteligencia del modelo y la memoria del proyecto son capacidades distintas.
Un modelo más potente ayuda a razonar.
No recrea automáticamente decisiones que nunca se conservaron.
Se está convirtiendo en un problema del sector
La comunidad de ingeniería de agentes converge en el mismo problema.
Anthropic describe los agentes de larga duración como un problema de relevo: una sesión nueva se parece a un ingeniero que llega a su turno sin la memoria del anterior. Su solución destaca dejar registros duraderos de progreso y un repositorio limpio para que las sesiones siguientes entiendan lo ocurrido.
OpenAI describe el conocimiento del repositorio como un sistema de registro para la ingeniería con muchos agentes. Un hallazgo útil: dar al agente un archivo enorme de instrucciones no es la respuesta. El contexto es escaso y un manual de mil páginas puede ser casi tan ineficaz como no tener documentación, porque cuesta distinguir lo pertinente del resto.
Kiro aborda lo mismo con orientación y especificaciones persistentes. Las convenciones viven en el espacio de trabajo; los requisitos, decisiones y planes sobreviven a la conversación donde se crearon.
Los tres enfoques comparten un patrón:
Agente temporal
+
Conocimiento duradero del proyecto
=
Continuidad
Llegamos a una conclusión similar al trabajar en StackLiberate.
La conversación es una memoria de trabajo útil.
El repositorio debe conservar la memoria de largo plazo.
El repositorio debe recordar lo que el agente no puede
El código ya contiene mucho conocimiento.
Los tipos describen estados posibles.
Las pruebas describen comportamientos esperados.
Los límites de módulos comunican responsabilidades.
Los esquemas describen datos.
Git registra los cambios.
Pero el código no contiene todas las decisiones necesarias para modificar un sistema con seguridad.
Piensa en una implementación razonable que se rechazó deliberadamente porque crea dos escritores para el mismo estado.
La sintaxis de la alternativa no le dice necesariamente al agente siguiente:
Ya evaluamos este enfoque. No lo reintroduzcas.
Ese conocimiento necesita un lugar duradero.
Para nosotros puede adoptar varias formas:
- Documentación de arquitectura.
- Reglas de ingeniería enfocadas.
- Contratos de funciones.
- Planes y tickets.
- Requisitos de validación.
- Invariantes explícitas.
- Registros de decisiones cuando su razón importe después.
- Pruebas que codifiquen reglas mecánicamente cuando sea posible.
- Historial de Git que explique cómo se llegó al estado actual.
No toda decisión merece documentación permanente.
La pregunta importante es:
¿Olvidar esto haría plausible una implementación futura incorrecta?
Si es así, probablemente no debería existir solo en un chat.
Preferimos mapas a enciclopedias
Hay una respuesta obvia a perder contexto:
Escribirlo todo.
Eso crea otro problema.
Un agente con poca información adivina.
Uno con demasiada información indiferenciada también tiene dificultades.
Si todas las convenciones, notas históricas, ideas futuras, experimentos rechazados, requisitos, órdenes de prueba, principios y preferencias se inyectan en cada interacción, las restricciones importantes compiten con las irrelevantes.
El resultado es lo que consideramos dilución del contexto.
Todo está presente.
Nada tiene suficiente peso.
Por eso preferimos un modelo por capas.
Mapa persistente pequeño
↓
Documentación pertinente del proyecto
↓
Plan específico de la tarea
↓
Código y pruebas pertinentes
↓
Implementación actual
La capa persistente indica cómo navegar.
Debe contener principios de alto valor y aplicación amplia.
La documentación más profunda contiene conocimiento relevante solo para partes concretas del sistema.
La tarea aporta el objetivo inmediato, las restricciones y los criterios de aceptación.
Así el agente puede razonar con suficiente contexto sin cargar toda la historia del producto en cada solicitud.
La distinción importa a medida que crece StackLiberate.
El contexto correcto para autenticación no es idéntico al de una función de edición visual. Pueden compartir principios, pero cargar el historial completo de ambos en cada sesión terminaría siendo contraproducente.
El contexto duradero necesita estructura, no solo volumen.
Los tickets son contexto ejecutable
Uno de nuestros documentos más útiles es el ticket de ingeniería.
Un buen ticket no dice solo:
Añade esta función.
Captura suficiente del problema para que un agente futuro reconstruya el trabajo previsto sin la conversación original.
Según el cambio, puede describir:
- El comportamiento actual.
- El comportamiento deseado.
- Los límites arquitectónicos conocidos.
- La fuente de verdad.
- Las invariantes importantes.
- El comportamiento esperado ante fallos.
- Los objetivos excluidos explícitamente.
- Los requisitos de validación.
- Los límites de reversión.
Eso lo convierte en algo más que gestión de proyectos.
Se vuelve razonamiento portable.
Otro agente puede retomarlo.
Otro modelo puede inspeccionarlo.
El trabajo puede reanudarse días después.
Una persona puede cuestionar sus supuestos.
Una vez iniciada la implementación, sirve como referencia para revisar el resultado.
Por eso nuestro flujo Plan First está conectado con nuestra estrategia de contexto.
Un plan que desaparece con la conversación tiene poco valor de largo plazo.
Uno conservado en el proyecto puede seguir limitando la implementación cuando el agente que lo escribió ya no esté.
Conocimiento persistente y verdad actual son distintos
La documentación crea su propio peligro:
Puede volverse incorrecta.
El contexto antiguo presentado con confianza suele ser peor que no tenerlo, porque el agente no ve motivos para cuestionarlo.
No queremos que la documentación sea un museo de todas nuestras ideas.
El contexto útil necesita un modelo de responsabilidad.
Alguna información es canónica.
Otra es histórica.
Otra es temporal.
Otra es derivada.
Otra debe eliminarse al terminar la función.
Se parece al diseño del estado dentro del software.
Si dos documentos afirman arquitecturas distintas, ¿cuál prevalece?
Si un plan antiguo contradice el código de producción, ¿sigue teniendo autoridad?
Si una hoja de ruta describe algo aplazado después, ¿lo confundirá un agente nuevo con el alcance actual?
Por eso el contexto duradero requiere la misma disciplina que otros límites del sistema:
saber qué representación tiene autoridad.
Intentamos mantener las reglas permanentes pequeñas, concretas y actuales. El razonamiento detallado pertenece cerca de la tarea. Los planes completados pueden servir de historia sin aparentar ser la especificación vigente.
El contexto también necesita gestionar su ciclo de vida.
Parte del conocimiento debe convertirse en código
La documentación no siempre es el lugar más sólido para una invariante.
Si una regla puede imponerse mecánicamente, preferimos acercarla al sistema.
En lugar de repetir al agente:
Nunca crees esta dependencia.
puede ser mejor una comprobación arquitectónica.
En lugar de:
Preserva siempre esta propiedad del esquema.
puede ser mejor un validador.
En lugar de:
Recuerda ejecutar estas comprobaciones de compatibilidad.
puede ser mejor la integración continua.
La progresión es:
Observación importante
↓
Regla documentada
↓
Invariante de ingeniería repetida
↓
Aplicación mecánica, cuando sea viable
Aquí la ingeniería de contexto empieza a coincidir con la ingeniería de software habitual.
A veces la mejor instrucción no es una instrucción.
Es un sistema que hace difícil o imposible crear el estado incorrecto.
El texto persistente importa porque no todos los principios son comprobables mecánicamente. Pero cuanto más crítica es la regla, menos queremos depender de que el agente preste atención a un párrafo.
Los relevos deben dejar comprensible el sistema
Un agente que trabaja por largo tiempo no debe limitarse a completar el trabajo.
Debe dejar un punto de partida claro para lo siguiente.
Por eso importa el final de una tarea.
¿La implementación terminó o se exploró parcialmente?
¿Qué validación se ejecutó?
¿Qué queda sin resolver?
¿Cambió algún supuesto?
¿Se aplazó algo deliberadamente?
¿La documentación contradice ahora la realidad?
Si el siguiente agente debe reconstruir la sesión anterior antes de trabajar, la entrega falló aunque el código sea correcto.
Preferimos terminar con:
Estado conocido del repositorio
+
Estado conocido de implementación
+
Estado conocido de validación
+
Trabajo restante conocido
La siguiente sesión puede dedicar su contexto al próximo problema, sin reconstruir el anterior.
Esto aporta cada vez más valor al trabajar en paralelo.
Un proyecto no puede depender de que todos los agentes compartan una conversación continua enorme, porque tarde o temprano no lo harán.
El repositorio se convierte en la superficie de coordinación.
El contexto debe sobrevivir a cambios de modelo
Hay otra razón para evitar que la conversación sea la arquitectura.
Los modelos cambian rápido.
El usado para una parte del proyecto puede no ser el de otra.
Las herramientas también cambian.
Un flujo puede pasar de un agente en un IDE a uno de terminal. Un modelo puede ser mejor para planificar y otro para implementar o revisar.
Si la inteligencia del proyecto existe principalmente como entendimiento no documentado entre una persona y una sesión concreta, cambiar de herramienta sale caro.
El conocimiento duradero del repositorio hace más portable el trabajo.
Un agente nuevo puede inspeccionar la misma:
- arquitectura;
- contratos;
- tickets;
- pruebas;
- planes;
- código;
- historia.
Puede razonar de otra forma.
Eso incluso puede resultar útil.
Pero parte de la misma realidad del proyecto.
Queremos beneficiarnos de mejores modelos sin que cada uno tenga que redescubrir por qué funciona el sistema.
Contexto no es control
Dar excelente contexto no garantiza una implementación correcta.
Hace algo más modesto y útil:
Le da al agente un problema mejor planteado.
El modelo sigue razonando.
Puede entender mal.
Puede encontrar un atajo.
Puede proponer una abstracción que rechacemos.
Por eso el contexto acompaña a planificación, revisión, pruebas y límites explícitos.
Nuestro ciclo general es aproximadamente:
Conocimiento duradero del proyecto
↓
Intención de la tarea
↓
Exploración
↓
Plan
↓
Revisión
↓
Implementación
↓
Validación
↓
Nuevo conocimiento duradero
El ciclo termina donde empezó.
Una tarea exitosa no produce solo código.
Cuando revela algo que futuros agentes necesitan saber, el proyecto mejora un poco su capacidad de explicarse.
El objetivo no es una memoria perfecta
No esperamos que un agente lleve toda la historia de StackLiberate en su ventana de contexto.
Sería caro, ruidoso y finalmente imposible.
Buscamos algo más parecido a una buena infraestructura.
Un desarrollador no memoriza todos los registros de una base. Sabe dónde está y qué significa su contrato.
Un agente no necesita cargar permanentemente cada discusión arquitectónica. Necesita una forma fiable de descubrir la arquitectura actual, entender restricciones relevantes y distinguir conocimiento autoritativo de ruido histórico.
Ese es el cambio.
De:
¿Cómo hacemos que el agente recuerde esto?
a:
¿Dónde debe vivir este conocimiento para que nadie tenga que recordarlo?
Al verlo así, el contexto dejó de parecernos una cuestión de instrucciones.
Empezó a parecernos ingeniería.
El software sobrevive a la sesión
Los agentes seguirán mejorando en trabajos largos.
Las ventanas de contexto crecerán.
La compactación mejorará.
Los agentes tendrán mejor memoria y recuperación de información.
Esperamos todo eso.
Pero el software seguirá sobreviviendo a las sesiones individuales.
Los equipos seguirán cambiando.
Los requisitos seguirán evolucionando.
La arquitectura seguirá acumulando decisiones cuyo significado no se desprende de la sintaxis final.
No queremos que la fiabilidad de un proyecto prolongado dependa de una continuidad conversacional perfecta.
Lo duradero pertenece al proyecto.
La conversación puede desaparecer.
El agente puede cambiar.
El modelo puede cambiar.
El trabajo debe seguir explicando qué es, qué importa y por dónde debe empezar el siguiente ingeniero.
Por eso, para nosotros, el contexto es infraestructura.