Explorar un código grande sin perder el hilo

Un agente del Agent SDK ayuda a entender un código heredado de cientos de archivos. Durante la primera hora responde con nombres de clases y rutas exactas. Dos horas después habla de “el patrón típico de repositorio” y se contradice con lo que dijo antes. Eso es degradación del contexto (context degradation): la ventana se llenó de salida de búsquedas y lo importante quedó diluido o compactado.

La lección de la ventana de contexto ya presentó el archivo de notas y /compact. Acá va cómo armar una exploración larga para que no llegue a ese punto.

Señales de alarma

• Respuestas con “patrones típicos” en lugar de las clases concretas que ya encontró.
• Afirmaciones sobre el código que salen de memoria y están desactualizadas.
• Respuestas inconsistentes a la misma pregunta.

Dos hábitos ayudan desde el principio: búsquedas acotadas (rutas, números de línea y fragmentos cortos, con tope, en vez de 2.000 líneas de coincidencias) y exigir que cada afirmación sobre el código cite ruta y línea de una lectura fresca.

Repartir en subagentes

El agente principal no tiene que leer los cuarenta archivos. Lanza subagentes con preguntas puntuales (“encontrá todos los archivos de test”, “rastreá las dependencias del flujo de reembolsos”), cada uno explora en su propio contexto y devuelve solo un resumen estructurado. La salida verbosa queda aislada (context isolation) y el agente principal conserva la coordinación y la visión de conjunto. En un monorepo de 40 paquetes: un subagente por paquete y una pasada que integra los resúmenes.

Entre fases, un resumen

Un subagente nuevo arranca de cero: lo único que recibe es su prompt. Si la fase 1 encontró los helpers de tests que ya existen y la fase 2 escribe tests, los subagentes de la fase 2 van a volver a explorar y a ignorar esos helpers, salvo que se los pases. Por eso, antes de lanzar la fase siguiente, el coordinador resume los hallazgos que importan y los mete en el contexto inicial (initial context) de cada subagente nuevo.

Anotar fuera de la conversación

El archivo de notas guarda hallazgos confirmados con ruta y rango de líneas, más las preguntas abiertas. El agente lo consulta antes de responder cada pregunta nueva, no solo al final, y lo relee al retomar al otro día. Como vive fuera del contexto, no depende de lo que conserve una compactación automática.

En una sesión interactiva que se está llenando de salida de grep y de tests a mitad de tarea, /compact resume la conversación para liberar espacio y acepta instrucciones de foco: “conservá los hallazgos sobre las reservas, los nombres de clases y las preguntas abiertas”.

Sobrevivir a una caída

Una investigación multiagente se corta a mitad de camino (el contenedor se reinicia). Si el estado vivía solo en memoria, se arranca de cero o con un conjunto incompleto. La recuperación tras una caída (crash recovery) se diseña así:

1. cada agente exporta su resultado y su estado a un lugar conocido de un almacenamiento que sobrevive al proceso;
2. al reanudar, el coordinador carga un manifiesto (manifest) con las tareas terminadas;
3. inyecta esos resultados en los prompts y lanza solo lo pendiente.

Las trampas típicas

• Una ventana más grande o “acordate de lo que encontraste” como solución.
• Que el agente principal lea todo él mismo.
• Suponer que los subagentes de la fase 2 heredan lo que se aprendió en la fase 1.
• Reiniciar la exploración desde cero después de una caída.

En el examen

Si el síntoma son respuestas genéricas o que se contradicen, la respuesta va por notas fuera del contexto o subagentes que aíslan la exploración. Si los subagentes nuevos repiten trabajo, por inyectar un resumen de la fase anterior. Si el sistema se cae, por estado exportado y un manifiesto.