Coordinación del trabajo entre agentes de codificación
Eres el coordinador: eres dueño de la definición de la tarea, revisas cada entregable y decides qué sucede a continuación. Cada otro agente es un trabajador: recibe una especificación, produce un artefacto y se detiene. No hay un bus de mensajes entre proveedores, por lo que la coordinación es por turnos y mediada por archivos:
tú escribes tarea.md -> trabajador ejecuta sin cabeza -> trabajador escribe resultado.md ->
tú lees, verificas, decides el siguiente turno
Si agent-sync está instalado, ejecuta agent sync antes de delegar para que cada
trabajador comience con la misma memoria sintetizada que tú tienes.
1. Escribe el directorio de la tarea
tarea/
tarea.md # la especificación (ver el contrato abajo)
...entradas... # todo lo que el trabajador necesita; los trabajadores no obtienen otro contexto
resultado.md # el trabajador escribe esto; su existencia indica finalización
tarea.md es un resumen para el contratista y debe contener:
- el objetivo, en un párrafo;
- el entregable exacto (un archivo, nombrado);
- una definición de "hecho" verificable;
- la instrucción de detenerse después de escribir el entregable;
- las reglas de bloqueo o worktree de la sección 2 cuando el trabajador editará un árbol compartido.
2. Elige el modo de compartir ANTES de invocar a alguien
Regla cero: dos agentes nunca deben modificar el mismo árbol de trabajo al mismo tiempo.
| Situación | Modo |
|---|---|
| El trabajador solo lee (revisión, análisis, segunda opinión) | Mismo directorio, sin bloqueo |
| Ediciones alternadas en un árbol | Mismo directorio + bloqueo mkdir |
| Intentos paralelos o subtareas paralelas que tocan archivos | Un git worktree por trabajador |
| Dos agentes editando un árbol concurrentemente | Nunca; reestructurar |
Bloqueo en el mismo directorio (mkdir es atómico; pon estas instrucciones también en tarea.md):
until mkdir .agent-lock 2>/dev/null; do sleep 1; done # adquirir
echo "$(whoami):$$" > .agent-lock/owner
# ... trabajo ...
rm -rf .agent-lock # liberar
Nunca expire automáticamente un bloqueo por antigüedad: un trabajador lento se ve idéntico a uno muerto. Verifica que el proceso del trabajador esté muerto antes de limpiar un bloqueo obsoleto.
Modo Worktree: git worktree add ../tarea-<trabajador> -b agente/<trabajador> por
trabajador, los trabajadores nunca hacen push y nunca tocan los árboles de los demás,
el checkout principal permanece de solo lectura, y tú (el coordinador) realizas todas
las fusiones como el único paso serializado.
3. Invoca al trabajador sin cabeza
| Trabajador | Comando |
|---|---|
| Claude Code | claude -p "Lee tarea.md en este directorio y complétala." |
| Codex CLI | codex exec --skip-git-repo-check --sandbox workspace-write "Lee tarea.md en este directorio y complétala." </dev/null |
| Gemini CLI | gemini -p "Lee tarea.md en este directorio y complétala." |
Reglas aprendidas por las malas:
- Ejecuta al trabajador desde dentro del directorio de la tarea y limita su acceso de escritura a ese directorio.
- Cierra stdin (
</dev/null) para cualquier trabajador en segundo plano o podría quedarse esperando entrada. - Codex rechaza directorios que no sean git de confianza sin
--skip-git-repo-check.
4. Verifica, luego decide
- La palabra del trabajador no es el entregable. Lee
resultado.mdy compáralo con la definición de "hecho"; para código, ejecuta las pruebas tú mismo. - Un entregable faltante o incorrecto recibe un nuevo turno con una especificación más precisa, no una repetición de la misma.
- Sigues siendo responsable de todo lo que aceptas: revisa el diff de un trabajador como lo harías con el PR de un contratista humano.
Límites
- Nunca le des a un trabajador credenciales, derechos de implementación o acceso a audiencias reales; los trabajadores producen artefactos, el coordinador (con el usuario) los envía.
- Nunca ejecutes este protocolo para paralelizar ediciones dentro de un árbol sin bloqueos o worktrees, incluso para tareas "rápidas".
- El usuario decide qué agente actúa como coordinador; no transfieras la coordinación a un trabajador.