Fan-out de subagentes para migración de código es dividir un cambio grande entre agentes especializados que exploran, implementan, prueban y revisan partes distintas del repositorio. Ayuda en monorepos, migraciones de TypeScript, cambios de API interna y ajustes de infraestructura, pero solo con fronteras explícitas.

En 2026, GitLab informó que 85% de las personas encuestadas ve la revisión y la validación como el nuevo cuello de botella después de adoptar IA en desarrollo de software (GitLab, "AI Accountability Report", 2026). Si los agentes escriben más código, la orquestación debe reducir ruido, no multiplicar diffs sin dueño.

TL;DR práctico

  • Usa subagentes para lectura paralela antes de edición paralela.
  • Divide por paquete, módulo, contrato o riesgo operativo.
  • Usa worktrees cuando la implementación ocurre en paralelo.
  • El PR final debe mostrar evidencia, comandos y decisiones descartadas.

Diagrama abstracto muestra subagentes coordinados alrededor de una migración de código sin texto visible.

¿Por qué el fan-out se volvió una habilidad de ingeniería?

En 2025, el informe DORA de Google Cloud midió 90% de uso de IA en el trabajo y más de 80% de percepción de mayor productividad (Google Cloud, "Announcing the 2025 DORA Report", 2025). El fan-out se volvió habilidad de ingeniería porque la velocidad individual no resuelve una migración grande cuando la validación sigue centralizada.

El error común es tratar agentes como threads de CPU. Los agentes no comparten memoria de forma consistente, no entienden automáticamente la intención de los demás y pueden editar el mismo archivo con supuestos distintos. Sin partición, el paralelismo se vuelve retrabajo.

Usa fan-out cuando la tarea tiene independencia real. Una migración de fetch a un cliente interno puede dividirse por paquete. Un reemplazo de logger puede dividirse por capa. Un cambio de CI puede separar inventario, parche y validación. Si la tarea es estrictamente secuencial, usa un agente principal con checkpoints.

Este tema continúa la conversación sobre context engineering para agentes de código. Allí la pregunta era cómo ahorrar contexto. Aquí la pregunta es cómo distribuir contexto entre trabajadores sin perder la cadena de decisión.

La ganancia aparece cuando cada subagente entrega una síntesis breve. El agente principal no necesita recibir todos los archivos leídos. Necesita alcance, hallazgo, parche propuesto, prueba ejecutada y riesgo residual. Ese contrato mantiene útil el contexto.

¿Cuándo usar subagentes, workflows o equipos de agentes?

En 2026, la documentación de Claude Code describió cuatro formas de paralelizar trabajo: subagentes, vista de agentes, equipos de agentes y workflows dinámicos (Claude Code Docs, "Run agents in parallel", 2026). La elección depende de quién coordina, si los trabajadores conversan y si editan los mismos archivos.

Los subagentes sirven cuando el agente principal sigue al mando. Investigan, revisan o ejecutan una tarea estrecha y devuelven un resumen. Para una migración de monorepo, úsalos para inventario de módulos, análisis de pruebas rotas, revisión de seguridad o lectura de dependencias.

Los workflows dinámicos encajan cuando el trabajo debe repetirse. La documentación de Claude Code cita auditoría de codebase, migración de 500 archivos e investigación cruzada como casos para workflows dinámicos (Claude Code Docs, "Run agents in parallel", 2026). Eso combina con migraciones mecánicas que necesitan verificación cruzada.

Los equipos de agentes cuestan más coordinación. En 2026, la documentación de Claude Code marcó agent teams como experimental y desactivado por defecto, recomendándolos para exploración paralela, módulos independientes, hipótesis competidoras y coordinación entre capas (Claude Code Docs, "Orchestrate teams of Claude Code sessions", 2026). Úsalos cuando los trabajadores deben conversar.

Superficie Mejor uso en la migración Señal de riesgo
Subagente Lectura, revisión y tarea estrecha. Edita demasiados módulos.
Workflow dinámico Paso repetible con verificación cruzada. Se vuelve script sin regla de parada.
Equipo de agentes Capas independientes que deben negociar. Todos dependen del mismo archivo central.
Sesión principal Decisión final, merge y narrativa del PR. Recibe logs crudos en vez de síntesis.

Una regla útil es simple. Si el resultado de un trabajador cabe en un resumen, usa subagente. Si el trabajo debe reejecutarse, usa workflow. Si los trabajadores necesitan debatir frontend, backend y pruebas, considera un equipo de agentes.

¿Cómo dividir una migración sin crear conflictos?

En 2025, Stack Overflow mostró que 69% de usuarios de agentes percibió aumento de productividad, pero solo 17% percibió mejor colaboración en equipo (Stack Overflow, "2025 Developer Survey: AI", 2025). Particionar una migración convierte velocidad aislada en colaboración verificable.

Diagrama abstracto muestra líneas de trabajo aisladas para migraciones paralelas sin texto visible.

Empieza por inventario. Antes del parche, pide a un subagente solo de lectura que mapee archivos afectados, pruebas probables, dueños de módulo y dependencias cruzadas. Otro subagente puede buscar riesgo operativo: autenticación, pagos, colas, datos personales, migraciones e infraestructura.

Después divide por fronteras estables. Paquete, servicio, ruta, cola, schema, biblioteca compartida y pipeline de CI son mejores fronteras que "la primera mitad de los archivos". Si dos subagentes necesitan tocar la misma abstracción central, esa parte debe quedarse con la sesión principal.

Usa worktrees cuando haya edición paralela. La documentación de Claude Code recomienda aislamiento con worktrees cuando las tareas pueden tocar archivos y observa que sesiones paralelas pueden ejecutarse en checkouts separados (Claude Code Docs, "Run agents in parallel", 2026). Así una tentativa no rompe el estado de otra.

migracion:
  inventario:
    papel: "solo lectura"
    salida: "archivos afectados, pruebas y riesgos"
  parches:
    paquete_api:
      frontera: "packages/api/**"
      prohibido: "packages/web/**"
    paquete_web:
      frontera: "packages/web/**"
      prohibido: "packages/api/**"
  consolidacion:
    responsable: "sesion principal"
    exige: "pruebas, diff limpio y resumen de decisiones"

En la práctica, solo dejo editar a un subagente cuando la frontera es objetiva. Si el cambio cruza contrato público, tipos compartidos o migración de base de datos, el subagente puede proponer un parche, pero la sesión principal lo aplica. Eso preserva autoría técnica.

¿Cómo mantener contexto y costo bajo control?

En 2026, la documentación de Claude Code advirtió que ejecutar varias sesiones o subagentes a la vez multiplica el uso de tokens (Claude Code Docs, "Run agents in parallel", 2026). El control viene de limitar entrada, limitar herramienta y exigir salida breve de cada trabajador.

Define una pregunta por subagente. "Encuentra todos los impactos en el paquete de billing" es mejor que "entiende la codebase". La salida debe listar archivos, motivo, prueba recomendada y confianza. Si necesita más contexto, debe pedir una herramienta estrecha, no volcar el repositorio en la conversación.

Los permisos también controlan costo. Un subagente de inventario no necesita escribir. Un revisor de seguridad no necesita deploy. Un evaluador de pruebas quizá solo necesita leer archivos y ejecutar comandos. Es el mismo principio de RAG de codebase con MCP para agentes: herramientas estrechas generan mejor contexto.

Cuando la migración pasa por muchas sesiones, evidencias y subagentes, uso RemoteCode para extender Claude Code y Codex en flujos agentic largos como recurso propio. La utilidad aquí es cualitativa: reducir desperdicio de contexto cuando el trabajo atraviesa etapas sin recargar todo el historial.

area: paquete de autenticacion
estado: listo_para_parche
archivos: src/auth/session.ts, src/auth/session.spec.ts
riesgo: medio
prueba: test unitario cubre expiracion y revocacion
proxima_accion: aplicar parche solo en este paquete

Ese contrato evita que el fan-out se vuelva una pila de narrativas. El agente principal puede comparar resultados, elegir orden de aplicación y abrir un PR que explique el camino. Buen contexto es el que cabe en la próxima decisión.

¿Dónde entran Codex, MCP y CI?

En 2026, la documentación de Codex afirmó que la configuración MCP vive en config.toml y puede limitarse al proyecto con .codex/config.toml en repositorios confiables (OpenAI Developers, "Model Context Protocol - Codex", 2026). Eso permite que la migración use herramientas del propio repositorio en vez de copiar y pegar manualmente.

Codex puede participar como ejecutor o como herramienta. En 2026, la documentación de OpenAI mostró que Codex CLI puede correr como servidor MCP con codex mcp-server, exponiendo herramientas para workflows multiagente con trazas revisables (OpenAI Developers, "Use Codex with the Agents SDK", 2026). Esa arquitectura encaja con migraciones que necesitan auditoría.

CI debe ser el juez determinístico. Los subagentes pueden proponer, pero lint, typecheck, pruebas, build y análisis de contrato deben ejecutarse fuera del chat. Si el proyecto ya tiene CI maduro, usa los jobs existentes antes de crear rúbricas con IA.

Para backend, conecta la migración con límites de servicios. Un cambio bien dividido respeta las fronteras de arquitectura de servicios en TypeScript. Si la frontera del sistema es confusa, el agente expondrá esa confusión como conflicto.

### Evidencia de la migración
- Inventario: paquetes afectados y archivos fuera de alcance.
- Parches: worktrees usados y conflictos resueltos.
- Pruebas: comandos ejecutados y fallas corregidas.
- Revisión: hallazgos de seguridad, tipos y regresión.
- Riesgo residual: puntos que exigen juicio humano.

Esto conecta fan-out con evals de PR para agentes de código en CI. Los agentes pueden hacer trabajo paralelo, pero la aceptación debe seguir basada en pruebas.

¿Cuál es el despliegue mínimo para esta semana?

En 2026, GitHub relató que Copilot code review creció 10 veces desde su lanzamiento y ya representa más de una de cada cinco revisiones de código en GitHub (GitHub, "60 million Copilot code reviews and counting", 2026). El despliegue mínimo debe reducir carga de revisión, no solo aumentar volumen de parches.

Primero, elige una migración pequeña, pero real. Reemplazar una función utilitaria, actualizar una API interna o migrar un paquete TypeScript es mejor que atacar todo el monorepo. El objetivo es probar el protocolo de fan-out.

Segundo, escribe tres papeles. Un subagente de inventario, uno de pruebas y uno de revisión. Solo después agrega agentes que editan. Ese orden evita confundir paralelismo con falta de proceso.

Tercero, ejecuta con límite. Dos o tres subagentes bastan al comienzo. Si encuentran fronteras claras, avanza a worktrees. Si encuentran acoplamiento inesperado, para y ajusta la arquitectura antes de multiplicar sesiones.

Diagrama abstracto muestra flujos de subagentes convergiendo hacia una verificación final sin texto visible.

Cuarto, guarda el aprendizaje en el repositorio. Coloca comandos, fronteras, áreas sensibles y formato de evidencia en AGENTS.md, CLAUDE.md o documento equivalente. Eso ayuda a Claude Code, Codex, Copilot y futuros agentes a repetir el flujo.

La señal de éxito es una revisión menor y más objetiva. Si el PR llega con alcance, pruebas y decisiones descartadas, el fan-out ayudó. Si llega con cinco narrativas incompatibles, solo automatizaste la confusión.

FAQ sobre fan-out de subagentes

En 2026, GitLab dijo que 92% reporta algún desafío de gobernanza con código generado por IA (GitLab, "AI Accountability Report", 2026). Estas respuestas ayudan a aplicar fan-out sin perder trazabilidad.

¿Fan-out sirve para cualquier migración?

No. En 2026, la documentación de Claude Code recomienda elegir la aproximación según coordinación, comunicación y archivos tocados (Claude Code Docs, "Run agents in parallel", 2026). Usa fan-out cuando hay fronteras independientes. Para un cambio secuencial o un archivo central, usa un agente principal con checkpoints.

¿Los subagentes deben editar código o solo revisar?

Depende de la frontera. En 2026, la documentación de Claude Code explicó que los subagentes tienen contexto, herramientas y permisos propios (Claude Code Docs, "Create custom subagents", 2026). Pueden editar con alcance estrecho. Para contratos compartidos, prefiere propuesta de parche aplicada por la sesión principal.

¿Worktree es obligatorio para fan-out?

No, pero ayuda cuando hay edición paralela. En 2026, la documentación de Claude Code recomienda worktrees para aislar tareas que tocan archivos (Claude Code Docs, "Run agents in parallel", 2026). Si los subagentes solo leen y resumen, worktree es exceso. Si editan, reduce conflicto.

¿Cómo medir si la orquestación mejoró?

Mide retrabajo de revisión. En 2026, GitHub dijo que los comentarios de alta señal importan más que el volumen y que 71% de las revisiones de Copilot code review tienen feedback accionable (GitHub, "60 million Copilot code reviews and counting", 2026). Localmente, busca menos comentarios repetidos, conflictos y fallas posmerge.

Cierre

En 2026, GitLab afirmó que solo 28% dice tener herramientas del ciclo de desarrollo totalmente integradas con datos y flujos compartidos (GitLab, "AI Accountability Report", 2026). Fan-out de subagentes es una respuesta práctica cuando el equipo necesita migrar código grande con trazabilidad.

Empieza pequeño: inventario, pruebas y revisión. Luego permite parches dentro de fronteras claras. Usa worktrees cuando haya edición paralela, MCP cuando el agente necesite herramientas estrechas y CI para validar el resultado. El objetivo no es tener más agentes. Es entregar una migración que el equipo pueda entender, verificar y mantener.

Fuentes consultadas

  • GitLab, "AI Accountability Report", recuperado el 2026-07-03, https://ir.gitlab.com/news/news-details/2026/GitLab-Research-Reveals-Organizations-Are-Generating-AI-Code-Faster-Than-They-Can-Control-It/default.aspx
  • Google Cloud, "Announcing the 2025 DORA Report", recuperado el 2026-07-03, https://cloud.google.com/blog/products/ai-machine-learning/announcing-the-2025-dora-report
  • Claude Code Docs, "Run agents in parallel", recuperado el 2026-07-03, https://code.claude.com/docs/en/agents
  • Claude Code Docs, "Orchestrate teams of Claude Code sessions", recuperado el 2026-07-03, https://code.claude.com/docs/en/agent-teams
  • Stack Overflow, "2025 Developer Survey: AI", recuperado el 2026-07-03, https://survey.stackoverflow.co/2025/ai
  • OpenAI Developers, "Model Context Protocol - Codex", recuperado el 2026-07-03, https://developers.openai.com/codex/mcp
  • OpenAI Developers, "Use Codex with the Agents SDK", recuperado el 2026-07-03, https://developers.openai.com/codex/guides/agents-sdk
  • GitHub, "60 million Copilot code reviews and counting", recuperado el 2026-07-03, https://github.blog/ai-and-ml/github-copilot/60-million-copilot-code-reviews-and-counting/