Un flujo de trabajo nocturno para agentes de programación

Escribe las tareas como para un contratista nuevo

Una tarea nocturna no tiene a quién preguntar. Tiene que llevar su propio contexto. Cada tarea debería caber en un párrafo y responder tres preguntas. Qué falla o qué falta. Cómo es el resultado terminado. Cómo se demuestra.

## Task: paginate the /orders endpoint
Problem: GET /orders returns every order. Large accounts time out.
Done: accepts ?cursor and ?limit (max 100), returns next_cursor.
Proof: new tests in tests/orders_pagination.test.ts pass; existing tests pass.
Do not: change the response shape of existing fields.

Mantén las tareas pequeñas. Lo ideal son de dos a cuatro horas de trabajo humano. Si es más grande, divídela. Una tarea que el agente termina en veinte minutos también vale. Ponlas en un archivo del repositorio o en issues que el agente pueda leer. Un archivo es lo más sencillo.

Una tarea, una rama, un worktree

Las tareas no deben compartir árbol de trabajo. Dos tareas que editan la misma copia producen un diff que nadie puede desenredar. Los worktrees de Git dan a cada tarea su propia carpeta sobre el mismo repositorio.

git worktree add ../work/orders-pagination -b agent/orders-pagination
git worktree add ../work/retry-webhooks -b agent/retry-webhooks

Cada rama tiene su propia ejecución del agente y su propio pull request. Por la mañana los revisas de uno en uno. Si uno está mal, lo cierras y los demás no se tocan.

Decide qué hace el agente solo

Fija el modo de permisos y la lista deny antes de la primera ejecución, no después. La guía para ejecutar Claude Code sin supervisión tiene los ajustes exactos. La versión corta para el trabajo nocturno es esta. Editar archivos con libertad. Ejecutar la suite de tests con libertad. Hacer commit y push de la rama de la tarea con libertad. Abrir un pull request. Nada más sin preguntar, y nada que salga del repositorio.

El bucle de ejecución

Un script pequeño lanza una ejecución headless por tarea, en su worktree, con un límite de turnos y un archivo de log. Esto es todo.

#!/bin/sh
# run-overnight.sh: one agent run per task file in tasks/
for task in tasks/*.md; do
  name=$(basename "$task" .md)
  dir="../work/$name"
  git worktree add "$dir" -b "agent/$name" 2>/dev/null
  (
    cd "$dir" || exit 1
    claude -p "Complete the task in $task. Commit on this branch, push it, and open a pull request with gh pr create. Stop when the tests pass or when you are blocked, and say which." \
      --permission-mode acceptEdits \
      --max-turns 80 \
      > "../logs/$name.log" 2>&1
  )
done

Ejecútalo dentro de tmux para que la conexión SSH no importe. Las tareas se ejecutan una tras otra. Las ejecuciones en paralelo son posibles, pero compiten por la CPU y por tu límite de uso. Además hacen los logs más difíciles de leer. Empieza en secuencia.

Deja que los tests sean el juez

El prompt le dice al agente que pare cuando pasen los tests. Tu CI ejecuta después los mismos tests en el pull request. Si el agente dijo verde y el CI dice rojo, lo sabes antes de leer una línea del diff. Protege main para que nada se fusione sin esa comprobación. Es la salvaguarda más valiosa del flujo, y no cuesta nada.

La revisión de la mañana, en diez minutos

• Abre la lista de pull requests. Compárala con la lista de tareas. Los que faltan están en los logs.
• Lee el log de todo lo que se paró por estar bloqueado. Suele ser una credencial que falta o una tarea ambigua. Arregla el texto de la tarea, no el agente.
• Revisa los pull requests en verde, del más pequeño al más grande. Fusiona los que estén bien. Cierra los que estén mal con una línea que diga por qué, y copia esa línea en el archivo de tareas de mañana.
• Borra los worktrees y las ramas fusionadas para que esta noche empiece limpia.

git worktree remove ../work/orders-pagination
git branch -d agent/orders-pagination

Qué delegar primero

Hay trabajo que encaja mejor con la noche que otro. Empieza por esto y amplía a medida que crezca la confianza.

• Tests que fallan o son inestables, con un comportamiento esperado claro.
• Actualizaciones de dependencias en las que la suite de tests es el juez.
• Refactorizaciones mecánicas en muchos archivos.
• Tests que faltan para código que ya funciona.
• Errores de tipos, errores de lint y avisos de deprecación.

Deja para el día las decisiones de diseño, todo lo que toque facturación o autenticación y todo lo que los tests no puedan verificar. De día puedes responder preguntas.

La máquina que hay debajo

Todo esto supone una máquina que sigue en marcha a las 4 de la madrugada. Un portátil que entra en reposo es la causa más común de que una ejecución nocturna no produzca nada. La guía sobre el reposo lo arregla en un Mac propio. Un Mac para agentes alojado ya viene con ello resuelto.