claudio.cool
CCDV-PLecciones

CCDV-P · Operación de flotas de agentes para entrega de software

Agentes en paralelo, worktrees, descomposición y estrategia de merge

⏱ 3 min de lecturaBorrador

Una migración de una biblioteca afecta a 300 archivos en un monorepo. Un equipo lanza diez agentes de código a la vez, cada uno con una parte, todos en el mismo directorio de trabajo. Al final, tres agentes sobrescribieron cambios de otros, dos corrieron las pruebas contra un árbol a medio editar y hay que desenredar el resultado a mano. El paralelismo era la idea correcta; la ejecución, no.

Cuándo conviene el fan-out

El fan-out paralelo (parallel fan-out) reparte una tarea en partes que corren a la vez. Rinde cuando las partes son independientes y el trabajo de cada una es sustancial: migraciones mecánicas por módulo, agregar pruebas a muchos paquetes, aplicar un refactor repetible. No rinde cuando las partes dependen una de otra, porque lo que se gana en paralelo se pierde en coordinación, o cuando integrar cuesta más que hacer. Cuantos más agentes, más costo en tokens y más resultados para revisar: el cuello de botella pasa de generar a verificar (ver la lección siguiente).

Aislamiento con worktrees

Dos agentes editando el mismo árbol de archivos se pisan. Un worktree de git (git worktree) da a cada agente su propio directorio de trabajo y su propia rama, sobre el mismo repositorio. Cada agente edita, ejecuta pruebas y hace commit sin ver los cambios a medias de los demás. Claude Code y el Agent SDK corren bien dentro de un worktree; el aislamiento también aplica a lo que no es archivos: puertos, bases de datos de prueba y cachés compartidos tienen que repartirse por agente, o dos agentes que corren pruebas a la vez colisionan.

Descomposición de tareas

La descomposición de tareas (task decomposition) define qué recibe cada agente. Criterios:

  • fronteras claras: por módulo, paquete o directorio, con el menor solapamiento posible de archivos;
  • criterio de terminado verificable: las pruebas que tienen que pasar, el comando que lo confirma;
  • contexto suficiente y acotado: la tarea, las convenciones y los archivos relevantes, no todo el repositorio;
  • lo compartido (un cambio en una interfaz usada por todos) se hace antes, en una tarea previa que los demás toman como base, no en paralelo.

Estrategia de merge y conflictos

Se decide antes de lanzar, no después:

  • cada agente entrega una rama o un pull request pequeño y enfocado, no un cambio gigante;
  • se integran de a uno y se corre la suite completa después de cada integración, para detectar conflictos semánticos (que no son conflictos de texto: dos cambios que combinados rompen algo);
  • los conflictos de texto se resuelven con una persona o con un agente integrador, siempre con las pruebas como árbitro;
  • si los conflictos son frecuentes, la descomposición estaba mal: replantear las fronteras en lugar de reintentar el merge.

Fallas de flota y su telemetría

La telemetría de la flota (fleet telemetry) permite diagnosticar a nivel de conjunto: tasa de agentes que terminan, que quedan trabados o que agotan presupuesto; costo y tiempo por tarea; pruebas que pasan en la rama del agente pero fallan tras integrar; archivos tocados por más de un agente; reintentos y herramientas denegadas. Los patrones típicos: muchos agentes fallan en la misma tarea (una premisa común mal descrita), costos que se disparan en tareas donde el agente exploró de más (falta de criterio de terminado) o fallas que aparecen solo después de integrar (dependencias entre partes que parecían independientes). Se actúa sobre la causa común, no sobre cada agente.

Las trampas típicas

  • Varios agentes en el mismo directorio de trabajo.
  • Paralelizar tareas dependientes.
  • Tareas sin criterio de terminado verificable.
  • Integrar todo junto al final.
  • Reintentar cada agente fallido sin buscar la causa común.

En el examen

Para tareas independientes y grandes, fan-out con un worktree por agente, descomposición con fronteras claras, integración de a uno con pruebas y telemetría para detectar patrones comunes. Si la salida de varios agentes se pisa, el arreglo es el aislamiento, no más instrucciones.

Pregunta rápida

Una pregunta del simulacro sobre este dominio. Cuenta para tu progreso.

A team uses Claude Code agents to migrate 200 services in a monorepo from one logging library to another. They launched twenty agents at the same time, all working in the same checkout and committing to one branch. Within an hour, agents were overwriting each other's edits, shared files such as the lockfile and a central logging index were conflicting, and several pull requests mixed unrelated changes.

The work itself is highly parallelizable, since each service is mostly independent, and the team wants to keep the parallelism.

Which orchestration change best fixes the conflicts?

Practicá este dominio en el simulacro →