Usa varios agentes de coding solo cuando el siguiente cambio tenga alcances independientes, un contrato estable, workspaces aislados y capacidad real de review. Si dos agentes necesitan los mismos archivos, si la interfaz todavía se mueve o si nadie puede revisar ambos diffs, un solo agente supervisado suele entregar antes.
El punto de partida seguro para un equipo pequeño no es un swarm autónomo. Empieza con una persona lead, un implementador aislado y un verificador. Cada tarea necesita owner, branch o worktree, allowed files, forbidden files, handoff, comando de prueba y merge gate.
| Ruta | Cuándo usarla | Gate mínimo |
|---|---|---|
| Un agente | Archivos solapados, contrato cambiante o poca review capacity | Review humana de un diff |
| Pipeline de dos agentes | Uno implementa y otro verifica sin tocar los mismos archivos | Handoff más pruebas |
| División de tres agentes | Dos alcances independientes comparten una interfaz estable | Owner de interfaz y merge secuencial |
| Agent team | Hay muchos flujos independientes y reviewers suficientes | Ownership, CI, merge queue y stop rules |
Primero valida el tablero de ruta, el brief, los worktrees, el handoff, el gate de verificación, la cola de merge y la métrica por hora de review. Añade más agentes solo cuando ese mínimo produzca código revisable.
Empieza por la ruta, no por el número de agentes
Un flujo multiagente funciona cuando el equipo puede separar zonas de propiedad. "Frontend agent más backend agent" no es una división segura si ambos siguen inventando la API. "Fix más tests" tampoco es seguro si el agente de tests debe adivinar cómo será el fix. La división buena tiene contrato estable, workspace aislado y un reviewer que entiende el diff sin leer todo el chat.
Para equipos pequeños hay cuatro rutas. Un agente sirve para bugs acoplados, refactors móviles, migraciones o archivos sensibles. Dos agentes sirven como implementador y verificador. Tres agentes sirven cuando dos ámbitos ya no compiten por la interfaz. Un agent team solo sirve si el equipo tiene CI fuerte, cola de merge y tiempo de review.
| Ruta | Forma de equipo | Primera tarea | Señal de parada |
|---|---|---|---|
| Un agente | Una persona supervisa un agente | Bug estrecho, archivo caliente, refactor inseguro | El agente necesita steering repetido en los mismos archivos |
| Dos agentes | Lead, implementador, verificador | Cambio acotado y verificación independiente | El verificador no puede explicar el diff |
| Tres agentes | Lead y dos implementadores independientes | Frontend/backend tras congelar API | Los agentes discuten la forma de la interfaz |
| Agent team | Lead, specialists, verifier | Muchos flujos independientes | La cola de review crece más rápido que el trabajo aceptado |
La ruta puede cambiar durante la semana. Empieza con un pipeline de dos agentes, mide si produce diffs claros y añade otro implementador solo cuando el primer split haya funcionado. Aumentar agentes antes de definir ownership suele aumentar coordinación, no throughput.
Cuándo varios agentes de coding ayudan de verdad
El caso fuerte es trabajo breadth-first con bordes visibles. Un agente implementa estado de UI y otro escribe pruebas de integración. Un agente investiga un camino que falla y otro revisa cobertura de regresión. Dos agentes cambian módulos separados después de congelar un type o API contract. En todos los casos, cada agente puede terminar sin esperar el código incompleto del otro.
Cinco condiciones deben cumplirse a la vez. El scope cabe en uno o dos filesets. El contrato compartido es suficientemente estable. Cada agente tiene branch o worktree. Una persona puede revisar el diff, no solo confiar en el transcript. CI y reviewers pueden hacer merges secuenciales.
La quinta condición suele romper equipos pequeños. Dos agentes escriben más rápido de lo que una persona revisa. Si el lead se convierte en resolver conflictos, el flujo no aceleró; solo movió el cuello de botella.
Cuándo conviene un solo agente
Un solo agente es mejor para trabajo acoplado. Database migrations, auth middleware, billing, public API, weak tests, package lock, repo-wide refactor y cambios de seguridad necesitan una sola línea de control. Aquí importa más mantener criterio que paralelizar.
La regla práctica es simple: si un agente necesita el código inacabado de otro para saber qué hacer, no los ejecutes en paralelo. Primero el lead escribe el contrato, luego un agente implementa el primer cambio, después un verifier o humano confirma el diff y el siguiente agente empieza desde main actualizado.
En un equipo pequeño, esa secuencia suele llegar antes a producción. Cada paso posterior tiene una base real, no una interfaz supuesta. El review es más corto y el rollback más barato.
Flujo del primer día
No cambies todo el proceso en la primera semana. Elige una issue de bajo riesgo. El lead escribe el brief y escoge ruta. El implementador trabaja en branch o worktree separado. El verificador lee solo brief, changed files y handoff. El reviewer humano mira semantic diff y riesgo de merge. Main recibe un merge a la vez. Los worktrees restantes se actualizan antes de continuar.
No entregues todo el backlog a cada agente. Entrega una tarea que pueda terminar, explicar y devolver. El output debe ser una branch más un artefacto escrito, no una carpeta llena de cambios sin contexto.
El primer checklist debe decir por qué la tarea es separable, quién owns el contrato compartido, qué archivos están prohibidos, qué comando prueba el resultado, a quién vuelve si falla y en qué orden entran los merges. Si no puedes responder eso, la tarea aún no está lista para paralelo.
Un task brief que evita solapamiento
El brief es el objeto central. Evita que dos agentes resuelvan problemas distintos y permite que el reviewer vea el contrato sin reconstruir la conversación.
mdAgent Task Brief owner: agent-a workspace: ../agent-a branch: agent/a-checkout-state goal: Add checkout state to the order summary component. non_goals: - Do not change payment provider code. - Do not change database schema. allowed_files: - src/features/checkout/** - tests/checkout/** forbidden_files: - src/lib/payments/** - db/migrations/** - package-lock.json interface_contract: - Use existing OrderStatus values. - If a new status is required, stop and ask the human lead. shared_state: - No local database migration. - Use test fixtures only. required_checks: - pnpm lint - pnpm test tests/checkout handoff_required: - changed files - commands run - proof or failing output - known risks - review focus done_means: - The verifier can reproduce the checks and explain the diff.
La lista de forbidden files no es burocracia. Protege schemas, route maps, lock files, env, public API y configuración compartida. Si una tarea no puede nombrar zonas prohibidas, probablemente es demasiado amplia para parallel coding.
Aísla con worktrees o branches
Git worktree permite varias working trees asociadas al mismo repo. Un agente puede correr tests y editar archivos sin ensuciar el checkout de otro. La documentación oficial cubre la mecánica; en un equipo pequeño importa la frontera operativa: directorio, branch, comandos y plan de merge.
bashgit switch main git pull --ff-only git worktree add ../agent-a -b agent/a-checkout-state git worktree add ../agent-b -b agent/b-profile-copy git worktree add ../verify -b verify/checkout-state git worktree list
Worktree aísla archivos fuente, no todo el estado. Database, ports, local services, secrets, package locks, CI runners, feature flags y public contracts necesitan single owner.
| Recurso compartido | Regla de propiedad |
|---|---|
| Schema y migrations | Un owner humano, sin edición paralela |
| Ports y local services | Reservados en el brief |
| Secrets y env files | Read-only salvo approval |
| Package lock y dependencies | Una branch owns dependency change |
| CI queue | Merge de uno en uno si hay poca capacidad |
| Public API y feature flags | Congelar contrato antes de paralelizar |
Si no puedes usar worktree, usa branches y checkouts limpios. El requisito real es workspace isolation más merge plan.
Handoffs durables
Un resumen de chat no es handoff. El verifier y el reviewer necesitan un artefacto que sobreviva en el pull request, issue comment o un handoff.md corto. Debe registrar changed files, commands, proof, risks y review focus.
mdAgent Handoff task: checkout state in order summary owner: agent-a branch: agent/a-checkout-state changed_files: - src/features/checkout/OrderSummary.tsx - tests/checkout/order-summary.test.ts commands_run: - pnpm lint - pnpm test tests/checkout proof: - All checkout tests pass locally. known_risks: - Empty order state still uses the existing fallback copy. review_focus: - Confirm the OrderStatus mapping is complete. next_owner: - verifier
El verifier no debe continuar la implementación por defecto. Primero comprueba si el implementador respetó allowed files, tests, interface contract, proof y risks. Si el verifier tiene que editar los mismos feature files, el brief fue insuficiente.
Añade roles solo si reducen carga
Un equipo pequeño no necesita una taxonomía enorme. Empieza con human lead, implementer, verifier y human reviewer. Añade specialist solo cuando docs, tests, migration o investigation sean flujos independientes.
| Rol | Trabajo | Añadir cuando | Quitar cuando |
|---|---|---|---|
| Human lead | Scope, contracts, merge order, risk | Siempre | Nunca del todo |
| Implementer | Scoped diff | El brief tiene allowed y forbidden files | La tarea cruza límites |
| Verifier | Tests, review, challenge | El output es separable | Reescribe el mismo diff |
| Reviewer | Semantic review y merge decision | Hay production code | No se salta |
| Specialist | Docs, tests, migration, investigation | Existe independent stream | Handoff cost supera utilidad |
El lead no tiene que escribir todas las líneas, pero owns el contrato. Si ningún humano owns el contrato, los agentes inventan contratos distintos y cada invención será un conflicto futuro.
Verification gate y merge queue
El trabajo paralelo se convierte en trabajo de producto en la merge queue. Las branches se mezclan secuencialmente, los checks se repiten y los worktrees restantes se actualizan tras cada merge.
bashgit switch main git pull --ff-only git merge --no-ff agent/a-checkout-state pnpm lint pnpm test git push cd ../agent-b git fetch origin git rebase origin/main
El gate revisa cinco cosas: el diff solo cambia allowed files; los checks requeridos se ejecutaron y registraron; el interface contract sigue intacto; el handoff nombra risks y review focus; una persona entiende el cambio semántico. AI review ayuda, pero semantics, security, data handling y merge responsibility siguen siendo humanas.
Dónde entran Codex, Claude Code, Cursor y frameworks
Elige herramientas después de definir el workflow. Codex encaja cuando quieres reviewable diffs, CLI, IDE, cloud tasks y PR-oriented flow. Claude Code encaja con supervised local sessions, contexto complejo y permisos más finos. Cursor background agents, worktree wrappers y orchestration frameworks pueden implementar el mismo proceso.
Si la decisión real es Codex frente a Claude Code, usa la comparación separada Claude Code vs Codex. Si el bloqueo es uso o cuota de Codex, usa OpenAI Codex usage limits. El dueño de este proceso no es una marca; son brief, workspace isolation, handoff, diff, verification y human merge.
Una buena superficie conserva el brief, separa workspace, muestra diff, registra proof y permite que el reviewer pare el merge. Si no hace eso, un modelo fuerte puede producir más trabajo difícil de revisar.
Mide por hora de review aceptada
Contar agentes es una mala métrica. Contar commits también: un agente puede crear un diff enorme que nadie confía en mergear. En un equipo pequeño, el recurso escaso suele ser review hour.
| Métrica | Por qué importa | Umbral de parada |
|---|---|---|
| Accepted diff per review hour | Mide trabajo útil contra el bottleneck | Por debajo del baseline de un agente |
| Rework rate | Muestra si los agentes adivinan contratos | Más de una reescritura grande por tarea |
| CI failure rate | Muestra estabilidad de branches paralelas | Se repite la misma causa |
| Merge conflict minutes | Expone overlap oculto | Conflictos en los mismos archivos |
| Cost per accepted change | Conecta tokens o plan con resultado | Sube coste y no sube trabajo aceptado |
Pasa dos o tres issues por el flujo antes de estandarizar. Compara contra un buen baseline de un agente. Si el pipeline de dos agentes da tests más claros, review más rápido o más accepted work per lead hour, mantenlo. Si genera coordinación extra, reduce el split.
Plan de una semana
Day 1: elige una issue de bajo riesgo con test coverage separada y crea brief más branch. Day 2: añade verifier sin implementation edits. Day 3: merge secuencial y registra review minutes. Day 4: prueba un segundo implementador solo si el contrato está estable. Day 5: compara accepted work, rework, conflicts, CI y review time.
| Día | Acción | Output |
|---|---|---|
| Day 1 | Elegir issue de bajo riesgo | Brief y una branch |
| Day 2 | Añadir verifier | Handoff y verification notes |
| Day 3 | Merge secuencial | Baseline de cola |
| Day 4 | Segundo implementador si hay contrato estable | Dos branches aisladas |
| Day 5 | Comparar trabajo y conflictos | Keep, shrink o stop |
El objetivo no es demostrar que los agent teams impresionan. El objetivo es encontrar el proceso mínimo que permite a un equipo pequeño entregar código revisable con menos lead time y menos retrabajo.
Preguntas frecuentes
¿Cuál es el flujo seguro más pequeño?
Human lead, un implementador y un verificador. El implementador escribe un scoped diff en workspace aislado. El verificador revisa brief, tests, allowed files y risks. Una persona revisa y decide merge.
¿Un equipo de dos personas debería usar varios agentes?
Sí, pero solo para trabajo separable. Un equipo de dos personas debería empezar con pipeline de dos agentes, no con agent team grande. El lead necesita tiempo para leer diff y handoff.
¿Git worktree es obligatorio?
No. Worktree es un buen default porque da una working tree por agente. Branches separadas o clean checkouts también sirven. Lo obligatorio es workspace isolation y merge plan.
¿Qué archivos deben ser single-owner?
Schemas, migrations, package locks, env files, auth middleware, feature flags, public API contracts y shared route maps. Solo cambian de regla si el human lead modifica el contrato.
¿AI review reemplaza human review?
No. AI review ayuda con syntax, tests, style y consistency. Human review mantiene semantics, product risk, security, data handling y merge responsibility.
¿Cuándo se detiene el modo multiagente?
Cuando los agentes necesitan los mismos files, la interfaz sigue cambiando, reviewers no alcanzan, CI falla por la misma causa o accepted diff per review hour cae bajo el baseline de un agente.
¿Dónde encajan Codex y Claude Code?
Codex, Claude Code, Cursor, worktree wrappers y orchestration frameworks son superficies para el mismo workflow. Elige la que preserve brief, workspace, diff, proof y review gate.
¿Cuántos agentes debería correr un equipo pequeño?
La mayoría debe probar one implementer plus one verifier antes de más. Tres agentes pueden funcionar con scopes independientes. Un agent team grande necesita ownership, CI, merge queue y review capacity.