Lección 07 — Definí límites claros para las tareas del agente

Le decís a Claude Code que “agregue autenticación de usuarios a este proyecto” y empieza a modificar el esquema de la base de datos, escribir rutas, cambiar componentes del frontend y —de paso— refactorizar el middleware de manejo de errores. Dos horas después verificás: 12 archivos modificados, 800 líneas nuevas y ni una sola funcionalidad que funcione end-to-end.

Los agentes nacen con el impulso de “hacer un poco más”: ven cosas relacionadas y las manejan al pasar, como quien va al supermercado por una botella de aceite y sale empujando un changuito lleno. El problema es que los humanos que compran de más solo desperdician plata; los agentes que hacen demasiadas cosas a la vez no terminan ninguna bien.

El blog de ingeniería de Anthropic lo establece con claridad: cuando los prompts son demasiado amplios, los agentes tienden a “empezar múltiples cosas a la vez” en lugar de “terminar una primero”. Las prácticas de Codex de OpenAI encontraron lo mismo. No es un problema del modelo, es un problema del harness: no trazaste el límite.

La atención es un recurso finito

Esto no es una metáfora, es aritmética. Si la capacidad de contexto del agente es C y activa k tareas simultáneamente, cada tarea recibe en promedio C/k recursos de razonamiento. Cuando C/k cae por debajo del umbral mínimo necesario para completar una sola tarea, no se termina ninguna.

El comportamiento real es revelador. Pedile que “agregue registro de usuarios” y puede:

1. Crear un modelo de User
2. Escribir la ruta de registro
3. Notar que necesita verificación de email, así que agregar un servicio de correo
4. Ver que las contraseñas necesitan hashing, así que incorporar bcrypt
5. Notar que el manejo de errores es inconsistente, así que refactorizar el middleware global
6. Ver que la estructura de tests está desordenada, así que reorganizar el directorio

Seis pasos después, cada uno está a medio hacer. Sin verificación end-to-end, con acoplamiento complejo entre el código a medio cocinar, y la sesión siguiente que tenga que juntar los pedazos va a estar completamente perdida.

Los datos experimentales de Anthropic apoyan esto: los agentes que usan una estrategia de “pequeño siguiente paso” (equivalente a WIP=1) muestran 37% más de tasa de completitud que los agentes con prompts amplios. Más interesante todavía: el número de líneas de código generadas está débilmente correlacionado de forma negativa con la completitud real de funcionalidades.

El flujo de trabajo WIP=1

stateDiagram-v2
    [*] --> not_started
    not_started --> active: el scheduler selecciona<br/>(solo si no hay otra activa)
    active --> blocked: dependencia externa<br/>o bloqueo documentado
    blocked --> active: bloqueo resuelto
    active --> passing: el comando de verificación<br/>se ejecuta con éxito
    passing --> [*]
    note right of active
        Invariante del harness:
        como máximo UNA tarea
        en estado active
    end note

Conceptos clave

• Sobrealcance (overreach): el agente activa más tareas en una sesión de lo óptimo. Es cuantificable: hacer 5 funcionalidades con 0 pasando end-to-end es sobrealcance.
• Sub-completitud (under-finish): la proporción de tareas que pasan verificación end-to-end, sobre todas las activadas, cae por debajo del umbral. Código escrito pero tests sin pasar es sub-completitud.
• Límite WIP (Work-in-Progress): viene de Kanban. Limitar cuántas tareas están en progreso a la vez. Para agentes, WIP=1 es el valor por defecto más seguro.
• Evidencia de completitud: la condición verificable que una tarea debe satisfacer para pasar de “en progreso” a “terminada”. Sin esto, los agentes sustituyen “el código se ve bien” por “el comportamiento pasa las pruebas”.
• Superficie de alcance (scope surface): una estructura DAG donde cada nodo es una unidad de trabajo y las aristas son dependencias. Los estados se limitan a cuatro: not_started, active, blocked, passing.
• Presión de completitud: la fuerza restrictiva que el harness ejerce mediante límites WIP y requisitos de evidencia, forzando al agente a terminar la tarea actual antes de empezar una nueva.

El sobrealcance y la sub-completitud son simbióticos

flowchart LR
    O["Sobrealcance<br/>5 tareas activas"] --> A["Atención diluida<br/>C/k por tarea"]
    A --> U["Sub-completitud<br/>0 tareas verificadas"]
    U --> M["Código a medio<br/>terminar acumulado"]
    M --> X["Mayor complejidad<br/>del sistema"]
    X --> O

En términos de Kanban, la ley de Little nos dice que L = λ · W. Si el trabajo en progreso L es demasiado alto, el tiempo de entrega W de cada tarea inevitablemente aumenta. Para los agentes, esto significa que cada funcionalidad tarda más desde el inicio hasta la completitud verificada, y la probabilidad de fallo crece.

Este es un problema viejo también en el mundo humano: Steve McConnell documentó en Rapid Development que el scope creep es la principal causa de fracaso de proyectos. Pero los humanos al menos tienen la intuición de “ya hice suficiente”. Los agentes no tienen ninguna. Generar la siguiente idea le cuesta al modelo casi nada en tokens extra —escribir “ya que estoy, arreglo esto también” apenas se nota— pero cada modificación adicional diluye la atención.

Cómo hacerlo bien

1. Hacé cumplir WIP=1

Este es el método más directo y efectivo. Decile al agente explícitamente que solo una tarea puede estar en estado activo en cualquier momento:

## Reglas de trabajo
- Trabajar en una funcionalidad a la vez
- Empezar la siguiente solo cuando la actual pase la verificación end-to-end
- No "aprovechar para refactorizar" la funcionalidad B mientras se implementa la A

2. Definí evidencia de completitud explícita para cada tarea

Terminado no es “el código está escrito”, es “la verificación del comportamiento pasa”:

F01: Registro de usuario
  Verificación: curl -X POST /api/register \
                  -d '{"email":"[email protected]","password":"123456"}' \
                  | jq .status == 201
  Estado: passing

3. Externalizá la superficie de alcance

Usá un archivo legible por máquina (JSON o Markdown) para registrar todos los estados. Cualquier sesión nueva puede leerlo y saber inmediatamente qué tarea está activa, qué comportamiento cuenta como terminado y qué verificaciones ya pasaron.

4. Monitoreá la tasa de completitud verificada

El harness debería rastrear continuamente el VCR (Verified Completion Rate) = tareas verificadas / tareas activadas. Bloqueá nuevas activaciones cuando VCR < 1.0.

Caso del mundo real

Un proyecto de API REST con 8 funcionalidades, dos estrategias comparadas:

	Sin restricciones	WIP=1
Funcionalidades activadas en sesión 1	5 simultáneas	1
Código producido en sesión 1	~800 líneas, 12 archivos	~200 líneas, 4 archivos
Tests E2E pasando en sesión 1	20% (solo registro)	100%
Completitud al cierre	3 de 8 (37,5%) tras 3 sesiones	7 de 8 (87,5%) tras 4 sesiones
Líneas totales	~1200	~800

Menos código total, pero más código efectivo.

Ideas clave

• WIP=1 es la configuración por defecto segura para el harness de un agente. Terminá una y después empezá la siguiente.
• La evidencia de completitud debe ser ejecutable: “el código se ve bien” no cuenta; “curl devuelve 201” sí.
• La superficie de alcance debe externalizarse como archivo, no solo mencionarse en la conversación.
• El sobrealcance y la sub-completitud son simbióticos: resolver uno resuelve el otro.
• “Hacé menos pero terminá” siempre le gana a “hacé más pero dejá a medias”. Las líneas de código y la tasa de completitud están negativamente correlacionadas.

Ejercicios

1. Atomización de tareas: tomá un requisito amplio (“implementá un sistema de gestión de usuarios”) y dividilo en al menos 5 unidades atómicas. Para cada una especificá una descripción de comportamiento única, un comando de verificación ejecutable y sus dependencias. Verificá que la descomposición satisface WIP=1.
2. Experimento comparativo: corré el mismo proyecto dos veces, una sin restricciones y otra con WIP=1. Compará tasa de completitud verificada, líneas totales y ratio de código efectivo.
3. Auditoría de evidencia: revisá la salida de una ejecución reciente y clasificá cada cambio de código como “comportamiento completado”, “comportamiento incompleto” o “scaffolding”. Agregá los comandos de verificación faltantes.

Lecturas adicionales

• Anthropic: Effective harnesses for long-running agents
• OpenAI: Harness Engineering
• Kanban: Successful Evolutionary Change — David Anderson
• Rapid Development — Steve McConnell

---

Anterior: Lección 06 — Inicializá antes de cada sesión · Siguiente: Lección 08 — Listas de funciones como primitivas del harness