Construyendo un agente de codificación para contexto de 8k: División planificador/ejecutor, presupuesto de tokens y ejecución paralela

La mayoría de las herramientas de IA para programación asumen modelos de 200k tokens, pero si ejecutas LLMs locales mediante Ollama, LM Studio o APIs gratuitas como Groq u OpenRouter, te quedas con ~8k tokens. Eso no alcanza para un proyecto completo —apenas cabe un solo archivo grande. Un desarrollador pasó semanas construyendo un agente CLI diseñado para esta limitación y compartió las lecciones prácticas aprendidas.

Arquitectura central: división planificador/ejecutor

El agente nunca muestra el proyecto completo al LLM. En su lugar, divide el trabajo en tres roles:

• Planificador: ve solo un mapa ligero del proyecto (resúmenes en Markdown de cada carpeta, ~300-500 tokens en total) más la solicitud del usuario, y genera una lista de tareas.
• Ejecutor: ve exactamente un archivo más una tarea por llamada —nunca dos archivos juntos.
• Orquestador: código puro (sin LLM) que construye un grafo de dependencias a partir de la lista de tareas y decide qué tareas pueden ejecutarse en paralelo vs secuencialmente.

Esto convierte las refactorizaciones multiarchivo de un problema de ventana de contexto a un problema de planificación. El planificador no necesita ver código, y el ejecutor solo ve una cantidad limitada de código a la vez.

Presupuesto de tokens impuesto en código

Cada llamada al LLM pasa por una verificación canFit() que mide el prompt del sistema + tokens de salida reservados + memoria + código real. Si el código no cabe, el agente recurre a un índice de líneas por archivo (generado una vez para archivos de más de ~150 líneas) y extrae solo la sección relevante.

Cálculo de presupuesto para 8192 tokens:

Prompt del sistema + instrucciones: ~1000
Reservado para respuesta: ~2000
Memoria a corto plazo (4 entradas): ~360
Disponible para código real: ~4800 (aproximadamente 140-190 líneas)

Cuando el presupuesto es ajustado, se descarta primero el contexto de carpeta, luego la memoria, antes de recortar el código real.

Ejecución paralela como multiplicador de velocidad

Debido a que cada ejecutor ve solo un archivo, las ediciones independientes en múltiples archivos se ejecutan simultáneamente. Una refactorización de 5 archivos se completa aproximadamente en el tiempo de la edición individual más larga. El grafo de dependencias (construido en código a partir de la lista de tareas del planificador) decide el orden.

Puntos problemáticos y soluciones

• Sobrescritura de archivos por solicitudes de tipo pregunta: preguntar "¿cuántas líneas tiene X?" provocaba que el ejecutor escribiera la respuesta dentro del archivo. Solucionado añadiendo un campo action_type: "query" en la salida del planificador, enrutado a través de una ruta de código que nunca toca el disco.
• Mapas de proyecto desactualizados causando desvíos silenciosos: si el usuario mencionaba un archivo renombrado que no estaba en el mapa, el planificador lo enrutaba silenciosamente a la coincidencia más cercana. Ahora el orquestador valida que las rutas de archivo mencionadas existan en disco y lanza un error claro si no existen.
• Bloques de código Markdown en la salida del ejecutor: los modelos más pequeños envuelven el código en triple backtic incluso cuando se les indica que no lo hagan. Solución: eliminarlos en el postprocesamiento en lugar de luchar contra el prompt.
• Costo de tokens de memoria: la memoria persistente añade ~80-90 tokens por entrada. El contexto de carpeta se descarta primero cuando el presupuesto es ajustado, luego la memoria, antes de que el código real sea recortado.

Preguntas abiertas

Si la división planificador/ejecutor escala a bases de código de más de 50 archivos —el grafo de dependencias se mantiene manejable, pero el mapa del proyecto comienza a costar tokens reales. Actualmente se descarta primero el contexto de carpeta, pero las ediciones más profundas pierden contexto. La implementación es de código abierto si quieres profundizar.