Research-Driven Agents: cuando un agente lee antes de codear

Cometí un error que me costó tres días de debugging y una conversación incómoda con un cliente. Le di a un agente una tarea de refactoring sobre una base de código que nunca había "visto" — sin contexto, sin arquitectura, sin nada. El agente ejecutó. Rápido, limpio, confiado. Y rompió exactamente lo que no tenía que romper.

No lo cuento para hacerme el humilde. Lo cuento porque si trabajás con agentes de IA hoy, ya lo hiciste o lo vas a hacer.

El problema no es que la IA codee mal. Es que codea rápido. Y rápido sin lectura previa es una receta para el desastre.

El patrón que rompió mis agentes: codear sin investigar

Llevo meses prestándole atención a algo que me molesta del ecosistema de agentes. La mayoría de los flujos que veo — y que uso — tienen más o menos esta estructura:

1. Prompt con tarea
2. Herramientas disponibles (filesystem, bash, browser)
3. Output de código
4. Rezar

El paso que falta es obvio cuando lo enunciás: entender el sistema antes de modificarlo.

Cuando estaba trabajando en Project Glasswing, me di cuenta de algo concreto: los lugares donde la IA generaba código problemático no eran los más complejos algorítmicamente. Eran los que requerían contexto implícito — convenciones del proyecto, dependencias no documentadas, decisiones de arquitectura que vivían en la cabeza del dev original (yo) y en ningún otro lado.

El agente no tenía forma de saber lo que no le dije. Y yo asumí que iba a inferirlo. Error mío, no del modelo.

La hipótesis: un artefacto de investigación cambia el output

Empecé a preguntarme: ¿qué pasa si obligo al agente a producir un documento de investigación antes de que toque un solo archivo?

No un plan de alto nivel. No un resumen de la tarea. Un artefacto concreto con estructura fija:

• Contexto del sistema: ¿qué hace este codebase? ¿cuál es la arquitectura?
• Dependencias relevantes: ¿qué módulos/funciones están involucrados?
• Decisiones implícitas detectadas: convenciones de código, patterns que se repiten
• Riesgos identificados: ¿qué puede romper esta tarea si se hace mal?
• Preguntas sin respuesta: lo que el agente no puede inferir y necesita que yo confirme

Ese último punto es el más valioso. Un agente que sabe lo que no sabe es infinitamente más útil que uno que asume.

Armé el experimento en un proyecto real: una API en Next.js con algunos endpoints legacy que necesitaban refactoring. Corrí la misma tarea dos veces:

Control: agente con acceso al filesystem y la tarea directa. Experimental: agente forzado a completar el artefacto de investigación primero, con un checkpoint donde yo apruebo o corrijo antes de que empiece a codear.

// Sistema de prompt para la fase de investigación
// El agente NO puede usar write_file hasta que complete este artefacto
const researchPhasePrompt = `
Antes de modificar cualquier archivo, producí un artefacto de investigación
con el siguiente formato EXACTO. No hay excepciones.

## INVESTIGACIÓN PREVIA AL CÓDIGO

### 1. Contexto del sistema
[Describí en 3-5 oraciones qué hace este codebase, su arquitectura principal
y el propósito del módulo que vas a modificar]

### 2. Archivos involucrados
[Listá cada archivo que vas a leer o modificar, con una línea explicando por qué]

### 3. Dependencias críticas
[Qué funciones, tipos o módulos externos usa el código que vas a tocar]

### 4. Convenciones detectadas
[Patrones que encontraste en el código existente que debés respetar:
naming conventions, error handling, estructura de imports, etc.]

### 5. Riesgos identificados
[Qué puede romper si esta tarea se ejecuta incorrectamente.
Sé específico: "romper el endpoint X" es mejor que "problemas de compatibilidad"]

### 6. Preguntas sin respuesta
[Lo que NO podés inferir del código y necesitás confirmación humana.
Si no tenés preguntas, algo salió mal en tu investigación.]

---
AGUARDÁ APROBACIÓN ANTES DE CONTINUAR.
`;

El checkpoint es clave. No es un prompt que el agente ignora y sigue. Es un waitForApproval() real en el flujo — el agente literalmente no puede avanzar hasta que yo leo el artefacto y le doy luz verde (o corrijo sus supuestos).

// Implementación del checkpoint en el flujo del agente
// Usando un runner simple con control de estado
async function researchDrivenAgent(
  task: string,
  projectPath: string
) {
  const agent = new AgentRunner({
    // Herramientas disponibles en fase de investigación
    // Solo lectura — write_file está explícitamente deshabilitado
    tools: [
      readFile,
      listDirectory,
      searchInFiles,
      // write_file: AUSENTE — no puede codear todavía
    ],
  });

  // Fase 1: Investigación pura
  console.log('🔍 Iniciando fase de investigación...');
  const researchArtifact = await agent.run(
    researchPhasePrompt + `\n\nTAREA: ${task}\nPROYECTO: ${projectPath}`
  );

  // Checkpoint humano — esto es el momento crucial
  const approved = await humanReview(researchArtifact);
  
  if (!approved.ok) {
    // El humano corrigió supuestos antes de que el agente codee
    console.log('📝 Supuestos corregidos:', approved.corrections);
  }

  // Fase 2: Coding con contexto validado
  // Ahora sí tiene acceso a write_file
  const codingAgent = new AgentRunner({
    tools: [
      readFile,
      writeFile,      // Habilitado recién acá
      listDirectory,
      searchInFiles,
      runTests,
    ],
    // El artefacto de investigación (corregido) va como contexto
    systemContext: `
      INVESTIGACIÓN PREVIA APROBADA:\n${approved.artifact}
      
      Usá este contexto como base. No inferís lo que ya investigaste.
    `,
  });

  return await codingAgent.run(task);
}

Lo que medí (y lo que me sorprendió)

No tengo métricas científicas. Tengo observaciones concretas de cuatro tareas de refactoring que corrí con este esquema.

Lo que mejoró notablemente:

El agente de control rompió tests en dos de cuatro tareas. El agente experimental no rompió ninguno. Eso solo ya justifica el overhead.

Pero lo más interesante fue la sección "Preguntas sin respuesta". En tres de cuatro tareas, el agente identificó algo que yo asumía que era obvio en el código pero que realmente no lo era. Un caso: había una convención de manejo de errores que usaba en los endpoints nuevos pero no en los legacy. El agente de control la ignoró y fue inconsistente. El experimental me preguntó específicamente qué convención usar.

Eso es el comportamiento que querés. Un agente que admite incertidumbre es un agente confiable.

Lo que no mejoró:

El tiempo total aumentó. No dramáticamente — hablamos de un checkpoint de 5-10 minutos de mi tiempo para revisar el artefacto — pero aumentó. Si el objetivo es velocidad pura, este approach no es para vos.

También noté que en tareas muy pequeñas ("agregá un campo a este DTO"), el overhead de la investigación era desproporcionado. La investigación profunda tiene sentido para cambios con impacto transversal, no para micro-ediciones.

Esto me recuerda a algo que pensé cuando estaba analizando el historial de Git del kernel de Linux: los commits más problemáticos históricamente no son los más grandes. Son los pequeños que tocaron algo con dependencias implícitas que nadie documentó. El patrón es el mismo.

Los gotchas que te vas a comer

El agente va a hacer trampa si puede. Si no deshabilitás las herramientas de escritura durante la fase de investigación, algunos modelos van a "investigar" y codear al mismo tiempo. No por malicia — por inercia de entrenamiento. El control de herramientas por fase no es opcional.

El artefacto de investigación puede convertirse en relleno. Si el prompt no es lo suficientemente específico, vas a recibir cinco párrafos de generalidades inútiles. La estructura fija con secciones nombradas y expectativas concretas es lo que evita eso. La sección de "preguntas sin respuesta" es especialmente importante — si el agente dice que no tiene preguntas, preguntale de vuelta por qué.

El checkpoint humano puede convertirse en un cuello de botella. Si estás corriendo múltiples agentes en paralelo — como estaba experimentando para MegaTrain con orquestación de tareas de training — el modelo de aprobación 1:1 no escala. Hay que pensar en aprobación asíncrona o en criterios de auto-aprobación para casos de bajo riesgo.

El contexto del artefacto puede degradarse. Si el artefacto de investigación es muy largo y va como contexto en la fase de coding, los modelos con ventanas de contexto grandes pueden "perderlo" a mitad de tarea. Comprimí el artefacto a lo esencial antes de pasarlo como contexto de la fase 2.

Un patrón que me preocupa más en general: la dependencia de que el modelo sea honesto sobre lo que no sabe. Esto está directamente relacionado con cuánto confiás en tu proveedor de IA — si el modelo tiene incentivos de entrenamiento para parecer confiado, va a llenar las secciones de incertidumbre con plausibilidades. Evaluá el artefacto con escepticismo.

FAQ: Agentes IA que investigan antes de codear

¿Esto funciona con cualquier modelo o solo con los más grandes? Funcionó bien con Claude Sonnet y con GPT-4o. Con modelos más chicos la calidad del artefacto baja notablemente — especialmente la sección de "convenciones detectadas" y "riesgos". Para production uso modelos frontier para la fase de investigación aunque use algo más liviano para tareas de coding simples.

¿El artefacto de investigación reemplaza la documentación del proyecto? No, y es importante no confundirlos. El artefacto es efímero — es contexto para esa tarea específica. La documentación del proyecto es persistente. Dicho eso, si encontrás que el agente está documentando cosas que deberían estar en el README y no están, tomalo como una señal de deuda técnica.

¿Cuánto tiempo agrega este approach al flujo de trabajo? Depende de la tarea. Para un refactoring con impacto transversal: 15-30 minutos adicionales entre la investigación del agente y mi revisión del artefacto. Para una tarea acotada: no lo uso. El criterio que uso: ¿puede esta tarea romper algo que no está en el scope directo? Si sí, investigación primero.

¿Puedo automatizar la revisión del artefacto con otro agente? Técnicamente sí, y lo probé. Un "agente revisor" que valida el artefacto contra un checklist. Funciona para validaciones mecánicas ("¿tiene todas las secciones?") pero no reemplaza el juicio humano para los supuestos de arquitectura. Es un buen filtro de primer nivel si tenés muchos agentes corriendo en paralelo.

¿Cómo manejás las "preguntas sin respuesta" que el agente identifica? Las respondo en texto plano directamente en el artefacto antes de aprobar. No como un chat separado — las escribo dentro del documento para que queden como contexto explícito en la fase de coding. El agente ve mis respuestas como parte del artefacto aprobado.

¿Este approach escala para proyectos muy grandes o muy complejos? Esta es la limitación real. En proyectos grandes, la fase de investigación puede ser superficial si el agente no sabe en qué enfocarse — ve demasiado para poder leerlo todo. Lo que funciona mejor es scope bien definido: no "investigá el proyecto", sino "investigá el módulo de autenticación y sus dependencias directas". El scope es tu responsabilidad, no del agente.

El problema no era la IA, era yo

Después de meses de frustración con agentes que tiraban código sin contexto, llegué a una conclusión incómoda: el problema principal era mi workflow, no el modelo.

Yo quería la velocidad del agente sin poner el trabajo de diseñar el sistema en que opera. El agente codea rápido porque eso es lo que le pedimos — literal y metafóricamente. Si querés que investigue primero, tenés que diseñar eso explícitamente en el flujo. No alcanza con pedirlo en el prompt.

Lo que me queda claro después de este experimento: la diferencia entre un agente que te ayuda y uno que te crea trabajo extra no está en el modelo. Está en la arquitectura del flujo. El checkpoint humano, las herramientas habilitadas por fase, el artefacto con estructura fija — son decisiones de diseño, no de prompting.

Y sí, agrega tiempo. Pero el debugging de código roto por contexto faltante agrega más.

Si estás usando agentes en proyectos que importan — no para generar boilerplate, sino para tocar código que ya está en producción — probá este approach. Empezá con una tarea de mediano impacto, diseñá el checkpoint, y fijate qué preguntas te hace el agente antes de codear.

Si no te hace ninguna, algo está mal. O el scope es demasiado chico, o el artefacto no está funcionando, o el modelo está llenando la incertidumbre con confianza falsa.

En los tres casos, querés saberlo antes de que toque el filesystem.

¿Usás algún mecanismo parecido en tus flujos de agentes? Me interesa saber qué otros patterns de "investigación forzada" están usando — escribime o comentá.